/* -*- 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-scripts.js contains a stub
 * implementation of this interface for non-Windows systems, for testing and
 * development purposes only.
 */
[scriptable, uuid(fa6750a2-f0fe-411c-af23-1cd6d2fdeceb)]
interface nsIWinMetroUtils : nsISupports
{
  /* return constants for the handPreference property */
  const long handPreferenceLeft = 0;
  const long handPreferenceRight = 1;

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

  /**
   * Determine if the user prefers left handed or right handed input.
   */
  readonly attribute long handPreference;

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

   /**
    * 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.
   */
   void showNativeToast(in AString aTitle, in AString aMessage, in AString anImage);

  /**
   * 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);

  /**
   * Stores the sync info securely
   *
   * @param aEmail The sync account email
   * @param aPassword The sync account password
   * @param aKey The sync account key
   */
  void storeSyncInfo(in AString aEmail, in AString aPassword, in AString aKey);

  /**
   * Loads the sync info
   *
   * @param aEmail The sync account email
   * @param aPassword The sync account password
   * @param aKey The sync account key
   */
  void loadSyncInfo(out AString aEmail, out AString aPassword, out AString aKey);

  /**
   * Clears the stored sync info if any.
   */
  void clearSyncInfo();

  /**
   * 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);
};