widget/nsIWinMetroUtils.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 /**
   9  * Integration with the "Metro"/"Modern" UI environment in Windows 8.
  10  *
  11  * Note: browser/metro/base/content/browser-scripts.js contains a stub
  12  * implementation of this interface for non-Windows systems, for testing and
  13  * development purposes only.
  14  */
  15 [scriptable, uuid(ac813696-3b0a-4259-bce1-1d078021ebbe)]
  16 interface nsIWinMetroUtils : nsISupports
  17 {
  18   /* Fullscreen landscape orientation */
  19   const long fullScreenLandscape = 0;
  20   /* Larger snapped state */
  21   const long filled = 1;
  22   /* Smaller snapped state */
  23   const long snapped = 2;
  24   /* Fullscreen portrait orientation */
  25   const long fullScreenPortrait = 3;
  26
  27   /* return constants for the handPreference property */
  28   const long handPreferenceLeft = 0;
  29   const long handPreferenceRight = 1;
  30
  31   /**
  32    * Determines the current snapped state.
  33    */
  34   readonly attribute long snappedState;
  35
  36   /**
  37    * Determine if the current browser is running in the metro immersive
  38    * environment.
  39    */
  40   readonly attribute boolean immersive;
  41
  42   /**
  43    * Determine if the user prefers left handed or right handed input.
  44    */
  45   readonly attribute long handPreference;
  46
  47   /**
  48    * Determine the activation URI
  49    */
  50   readonly attribute AString activationURI;
  51
  52   /**
  53    * Attempts to unsnap the application from snapped state to filled state
  54    */
  55    void unsnap();
  56
  57
  58    /**
  59     * Show the settings flyout
  60     */
  61    void showSettingsFlyout();
  62
  63   /**
  64    * Launches the specified application with the specified arguments and
  65    * switches to Desktop mode if in metro mode.
  66    */
  67    void launchInDesktop(in AString aPath, in AString aArguments);
  68
  69   /**
  70    * Secondary tiles are a Windows 8 specific feature for pinning new tiles
  71    * to the start screen.   Tiles can later be activated whether the browser is
  72    * already opened or not.
  73    */
  74
  75   /**
  76    * Pins a new tile to the Windows 8 start screen.
  77    *
  78    * @param aTileID         An ID which can later be used to remove the tile
  79    * @param aShortName      A short name for the tile
  80    * @param aDiplayName     The name that will be displayed on the tile
  81    * @param aActivationArgs The arguments to pass to the browser upon
  82    *                        activation of the tile
  83    * @param aTileImage An image for the normal tile view
  84    * @param aSmallTileImage An image for the small tile view
  85    */
  86   void pinTileAsync(in AString aTileID,
  87                     in AString aShortName,
  88                     in AString aDisplayName,
  89                     in AString aActivationArgs,
  90                     in AString aTileImage,
  91                     in AString aSmallTileImage);
  92
  93   /**
  94    * Unpins a tile from the Windows 8 start screen.
  95    *
  96    * @param aTileID An existing ID which was previously pinned
  97    */
  98   void unpinTileAsync(in AString aTileID);
  99
 100   /**
 101    * Determines if a tile is pinned to the Windows 8 start screen.
 102    *
 103    * @param aTileID An ID which may have been pinned with pinTileAsync
 104    * @return true if the tile is pinned
 105    */
 106   bool isTilePinned(in AString aTileID);
 107
 108   /**
 109    * Stores the sync info securely
 110    *
 111    * @param aEmail The sync account email
 112    * @param aPassword The sync account password
 113    * @param aKey The sync account key
 114    */
 115   void storeSyncInfo(in AString aEmail, in AString aPassword, in AString aKey);
 116
 117   /**
 118    * Loads the sync info
 119    *
 120    * @param aEmail The sync account email
 121    * @param aPassword The sync account password
 122    * @param aKey The sync account key
 123    */
 124   void loadSyncInfo(out AString aEmail, out AString aPassword, out AString aKey);
 125
 126   /**
 127    * Clears the stored sync info if any.
 128    */
 129   void clearSyncInfo();
 130
 131   /**
 132    * Soft keyboard attributes. Used in unison with shown/hidden observer
 133    * events sent via FrameworkView.
 134    *
 135    * keyboardVisible - returns true if the soft keyboard is currently
 136    * displayed, false otherwise.
 137    * keyboardX, keyboardY, keyboardWidth, keyboardHeight - occlude rect
 138    * of the keyboard when displayed in device independent pixels.
 139    */
 140   readonly attribute boolean keyboardVisible;
 141   readonly attribute unsigned long keyboardX;
 142   readonly attribute unsigned long keyboardY;
 143   readonly attribute unsigned long keyboardWidth;
 144   readonly attribute unsigned long keyboardHeight;
 145
 146   /**
 147    * Settings panel links. addSettingsPanelEntry adds an entry to
 148    * the settings flyout panel that the user can invoke.
 149    *
 150    * @param aChromePanelId panel id invoked via nsIBrowserDOMWindow's
 151    * ShowPanel api. Example: 'prefs-container'
 152    * @return a unique identifier that will be passed as "data" in the
 153    * "metro-settings-entry-selected" notification when the entry is clicked
 154    */
 155   unsigned long addSettingsPanelEntry(in AString aLabel);
 156
 157   /**
 158    * Change the value of the "switch primary and secondary buttons" preference.
 159    * See the Windows SwapMouseButton API docs for details.
 160    * Included here for use in automated tests (see bug 839460).
 161    *
 162    * @param aSwap true to enable the preference, false to disable it.
 163    * @return original value of the preference.
 164    */
 165   bool swapMouseButton(in bool aSwap);
 166 };