/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

/**
 * Integration with the "Metro"/"Modern" UI environment in Windows 8.
 *
 * Note: browser/metro/base/content/browser.js contains a stub
 * implementation of this interface for non-Windows systems, for testing and
 * development purposes only.
 */
[scriptable, uuid(319faae0-82ca-4c2f-8a24-2b2445e5a72a)]
interface nsIWinMetroUtils : nsISupports
{
  /**
   * Determine if the current device has the hardware capabilities to run
   * in metro mode.
   */
  readonly attribute boolean supported;

  /**
   * Determine if the current browser is running in the metro immersive
   * environment.
   */
  readonly attribute boolean immersive;

  /**
   * Determine the activation URI
   */
  readonly attribute AString activationURI;

  /**
   * Determine the previous execution state. The possible values of this
   * attribute are exactly those values in the
   * Windows::ApplicationModel::Activation enumeration.
   */
  readonly attribute long previousExecutionState;

  /**
   * Helper for our restart logic up in the about flyout. We set this
   * right before we restart for an update so that MetroAppShell can
   * communicate this to the ceh.
   */
  attribute boolean updatePending;

  /*
   * Determine if metro firefox is running in the foreground.
   */
  readonly attribute boolean foreground;

   /**
    * Show the settings flyout
    */
   void showSettingsFlyout();

  /**
   * Launches the specified application with the specified arguments and
   * switches to Desktop mode if in metro mode.
   */
   void launchInDesktop(in AString aPath, in AString aArguments); 

  /**
   * Displays a native Windows 8 toast.
   *
   * @param aAppId  Application ID for current application.
   *                If using Metro mode, it can be null string.
   */
   void showNativeToast(in AString aTitle, in AString aMessage,
                        in AString anImage, in AString aCookie,
                        [optional] in AString aAppId);

  /**
   * Secondary tiles are a Windows 8 specific feature for pinning new tiles
   * to the start screen.   Tiles can later be activated whether the browser is
   * already opened or not. 
   */

  /**
   * Pins a new tile to the Windows 8 start screen.
   * 
   * @param aTileID         An ID which can later be used to remove the tile
   *                        ID must only contain valid filesystem characters
   * @param aShortName      A short name for the tile
   * @param aDiplayName     The name that will be displayed on the tile
   * @param aActivationArgs The arguments to pass to the browser upon 
   *                        activation of the tile
   * @param aTileImage An image for the normal tile view
   * @param aSmallTileImage An image for the small tile view
   */
  void pinTileAsync(in AString aTileID,
                    in AString aShortName,
                    in AString aDisplayName,
                    in AString aActivationArgs,
                    in AString aTileImage,
                    in AString aSmallTileImage);

  /**
   * Unpins a tile from the Windows 8 start screen.
   * 
   * @param aTileID An existing ID which was previously pinned
   *                ID must only contain valid filesystem characters
   */
  void unpinTileAsync(in AString aTileID);

  /**
   * Determines if a tile is pinned to the Windows 8 start screen.
   * 
   * @param aTileID An ID which may have been pinned with pinTileAsync
   *                ID must only contain valid filesystem characters
   * @return true if the tile is pinned
   */
  bool isTilePinned(in AString aTileID);

  /**
   * Soft keyboard attributes. Used in unison with shown/hidden observer
   * events sent via FrameworkView.
   *
   * keyboardVisible - returns true if the soft keyboard is currently
   * displayed, false otherwise.
   * keyboardX, keyboardY, keyboardWidth, keyboardHeight - occlude rect
   * of the keyboard when displayed in device independent pixels.
   */
  readonly attribute boolean keyboardVisible;
  readonly attribute unsigned long keyboardX;
  readonly attribute unsigned long keyboardY;
  readonly attribute unsigned long keyboardWidth;
  readonly attribute unsigned long keyboardHeight;

  /**
   * Settings panel links. addSettingsPanelEntry adds an entry to
   * the settings flyout panel that the user can invoke.
   *
   * @param aChromePanelId panel id invoked via nsIBrowserDOMWindow's
   * ShowPanel api. Example: 'prefs-container'
   * @return a unique identifier that will be passed as "data" in the
   * "metro-settings-entry-selected" notification when the entry is clicked
   */
  unsigned long addSettingsPanelEntry(in AString aLabel);

  /**
   * Change the value of the "switch primary and secondary buttons" preference.
   * See the Windows SwapMouseButton API docs for details.
   * Included here for use in automated tests (see bug 839460).
   *
   * @param aSwap true to enable the preference, false to disable it.
   * @return original value of the preference.
   */
  bool swapMouseButton(in bool aSwap);
};