/* -*- 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(45656788-B111-4317-B054-FFE881A0737E)]
interface nsIWinMetroUtils : nsISupports
{
  /* Fullscreen landscape orientation */
  const long fullScreenLandscape = 0;
  /* Larger snapped state */
  const long filled = 1;
  /* Smaller snapped state */
  const long snapped = 2;
  /* Fullscreen portrait orientation */
  const long fullScreenPortrait = 3;

  /* return constants for the handPreference property */
  const long handPreferenceLeft = 0;
  const long handPreferenceRight = 1;

  /**
   * Determines the current snapped state.
   */
  readonly attribute long snappedState;

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

  /**
   * Attempts to unsnap the application from snapped state to filled state
   */
   void unsnap();

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

  /**
   * 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
   * @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
   */
  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
   * @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'
   * @param aLabel Localized string label displayed in the settings
   * flyout panel for this option.
   */
  void addSettingsPanelEntry(in AString aChromePanelId, in AString aLabel);
};