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.js contains a stub
  12  * implementation of this interface for non-Windows systems, for testing and
  13  * development purposes only.
  14  */
  15 [scriptable, uuid(319faae0-82ca-4c2f-8a24-2b2445e5a72a)]
  16 interface nsIWinMetroUtils : nsISupports
  17 {
  18   /**
  19    * Determine if the current device has the hardware capabilities to run
  20    * in metro mode.
  21    */
  22   readonly attribute boolean supported;
  23
  24   /**
  25    * Determine if the current browser is running in the metro immersive
  26    * environment.
  27    */
  28   readonly attribute boolean immersive;
  29
  30   /**
  31    * Determine the activation URI
  32    */
  33   readonly attribute AString activationURI;
  34
  35   /**
  36    * Determine the previous execution state. The possible values of this
  37    * attribute are exactly those values in the
  38    * Windows::ApplicationModel::Activation enumeration.
  39    */
  40   readonly attribute long previousExecutionState;
  41
  42   /**
  43    * Helper for our restart logic up in the about flyout. We set this
  44    * right before we restart for an update so that MetroAppShell can
  45    * communicate this to the ceh.
  46    */
  47   attribute boolean updatePending;
  48
  49   /*
  50    * Determine if metro firefox is running in the foreground.
  51    */
  52   readonly attribute boolean foreground;
  53
  54    /**
  55     * Show the settings flyout
  56     */
  57    void showSettingsFlyout();
  58
  59   /**
  60    * Launches the specified application with the specified arguments and
  61    * switches to Desktop mode if in metro mode.
  62    */
  63    void launchInDesktop(in AString aPath, in AString aArguments);
  64
  65   /**
  66    * Displays a native Windows 8 toast.
  67    *
  68    * @param aAppId  Application ID for current application.
  69    *                If using Metro mode, it can be null string.
  70    */
  71    void showNativeToast(in AString aTitle, in AString aMessage,
  72                         in AString anImage, in AString aCookie,
  73                         [optional] in AString aAppId);
  74
  75   /**
  76    * Secondary tiles are a Windows 8 specific feature for pinning new tiles
  77    * to the start screen.   Tiles can later be activated whether the browser is
  78    * already opened or not.
  79    */
  80
  81   /**
  82    * Pins a new tile to the Windows 8 start screen.
  83    *
  84    * @param aTileID         An ID which can later be used to remove the tile
  85    *                        ID must only contain valid filesystem characters
  86    * @param aShortName      A short name for the tile
  87    * @param aDiplayName     The name that will be displayed on the tile
  88    * @param aActivationArgs The arguments to pass to the browser upon
  89    *                        activation of the tile
  90    * @param aTileImage An image for the normal tile view
  91    * @param aSmallTileImage An image for the small tile view
  92    */
  93   void pinTileAsync(in AString aTileID,
  94                     in AString aShortName,
  95                     in AString aDisplayName,
  96                     in AString aActivationArgs,
  97                     in AString aTileImage,
  98                     in AString aSmallTileImage);
  99
 100   /**
 101    * Unpins a tile from the Windows 8 start screen.
 102    *
 103    * @param aTileID An existing ID which was previously pinned
 104    *                ID must only contain valid filesystem characters
 105    */
 106   void unpinTileAsync(in AString aTileID);
 107
 108   /**
 109    * Determines if a tile is pinned to the Windows 8 start screen.
 110    *
 111    * @param aTileID An ID which may have been pinned with pinTileAsync
 112    *                ID must only contain valid filesystem characters
 113    * @return true if the tile is pinned
 114    */
 115   bool isTilePinned(in AString aTileID);
 116
 117   /**
 118    * Soft keyboard attributes. Used in unison with shown/hidden observer
 119    * events sent via FrameworkView.
 120    *
 121    * keyboardVisible - returns true if the soft keyboard is currently
 122    * displayed, false otherwise.
 123    * keyboardX, keyboardY, keyboardWidth, keyboardHeight - occlude rect
 124    * of the keyboard when displayed in device independent pixels.
 125    */
 126   readonly attribute boolean keyboardVisible;
 127   readonly attribute unsigned long keyboardX;
 128   readonly attribute unsigned long keyboardY;
 129   readonly attribute unsigned long keyboardWidth;
 130   readonly attribute unsigned long keyboardHeight;
 131
 132   /**
 133    * Settings panel links. addSettingsPanelEntry adds an entry to
 134    * the settings flyout panel that the user can invoke.
 135    *
 136    * @param aChromePanelId panel id invoked via nsIBrowserDOMWindow's
 137    * ShowPanel api. Example: 'prefs-container'
 138    * @return a unique identifier that will be passed as "data" in the
 139    * "metro-settings-entry-selected" notification when the entry is clicked
 140    */
 141   unsigned long addSettingsPanelEntry(in AString aLabel);
 142
 143   /**
 144    * Change the value of the "switch primary and secondary buttons" preference.
 145    * See the Windows SwapMouseButton API docs for details.
 146    * Included here for use in automated tests (see bug 839460).
 147    *
 148    * @param aSwap true to enable the preference, false to disable it.
 149    * @return original value of the preference.
 150    */
 151   bool swapMouseButton(in bool aSwap);
 152 };