widget/nsIWinTaskbar.idl

   1 /* vim: se cin sw=2 ts=2 et : */
   2 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   3  *
   4  * This Source Code Form is subject to the terms of the Mozilla Public
   5  * License, v. 2.0. If a copy of the MPL was not distributed with this
   6  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   7
   8 #include "nsISupports.idl"
   9 #include "nsIBaseWindow.idl"
  10
  11 interface nsIDocShell;
  12 interface nsITaskbarTabPreview;
  13 interface nsITaskbarWindowPreview;
  14 interface nsITaskbarPreviewController;
  15 interface nsITaskbarProgress;
  16 interface nsITaskbarOverlayIconController;
  17 interface nsIJumpListBuilder;
  18 interface mozIDOMWindow;
  19
  20 /*
  21  * nsIWinTaskbar
  22  *
  23  * This interface represents a service which exposes the APIs provided by the
  24  * Windows taskbar to applications.
  25  *
  26  * Starting in Windows 7, applications gain some control over their appearance
  27  * in the taskbar. By default, there is one taskbar preview per top level
  28  * window (excluding popups). This preview is represented by an
  29  * nsITaskbarWindowPreview object.
  30  *
  31  * An application can register its own "tab" previews. Such previews will hide
  32  * the corresponding nsITaskbarWindowPreview automatically (though this is not
  33  * reflected in the visible attribute of the nsITaskbarWindowPreview). These
  34  * tab previews do not have to correspond to tabs in the application - they can
  35  * vary in size, shape and location. They do not even need to be actual GUI
  36  * elements on the window. Unlike window previews, tab previews require most of
  37  * the functionality of the nsITaskbarPreviewController to be implemented.
  38  *
  39  * Applications can also show progress on their taskbar icon. This does not
  40  * interact with the taskbar previews except if the nsITaskbarWindowPreview is
  41  * made invisible in which case the progress is naturally not shown on that
  42  * window.
  43  *
  44  * When taskbar icons are combined as is the default in Windows 7, the progress
  45  * for those windows is also combined as defined here:
  46  * http://msdn.microsoft.com/en-us/library/dd391697%28VS.85%29.aspx
  47  *
  48  * Applications may also define custom taskbar jump lists on application shortcuts.
  49  * See nsIJumpListBuilder for more information.
  50  */
  51
  52 [scriptable, uuid(11751471-9246-4c72-a80f-0c7df765d640)]
  53 interface nsIWinTaskbar : nsISupports
  54 {
  55   /**
  56    * Returns true if the operating system supports Win7+ taskbar features.
  57    * This property acts as a replacement for in-place os version checking.
  58    */
  59   readonly attribute boolean available;
  60
  61   /**
  62    * Returns the default application user model identity the application
  63    * registers with the system. This id is used by the taskbar in grouping
  64    * windows and in associating pinned shortcuts with running instances and
  65    * jump lists.
  66    */
  67   readonly attribute AString defaultGroupId;
  68
  69   /**
  70    * Taskbar window and tab preview management
  71    */
  72
  73   /**
  74    * Creates a taskbar preview. The docshell should be a toplevel docshell and
  75    * is used to find the toplevel window. See the documentation for
  76    * nsITaskbarTabPreview for more information.
  77    */
  78   nsITaskbarTabPreview createTaskbarTabPreview(in nsIDocShell shell,
  79                                                in nsITaskbarPreviewController controller);
  80
  81   /**
  82    * Gets the taskbar preview for a window. The docshell is used to find the
  83    * toplevel window. See the documentation for nsITaskbarTabPreview for more
  84    * information.
  85    *
  86    * Note: to implement custom drawing or buttons, a controller is required.
  87    */
  88   nsITaskbarWindowPreview getTaskbarWindowPreview(in nsIDocShell shell);
  89
  90   /**
  91    * Taskbar icon progress indicator
  92    */
  93
  94   /**
  95    * Gets the taskbar progress for a window. The docshell is used to find the
  96    * toplevel window. See the documentation for nsITaskbarProgress for more
  97    * information.
  98    */
  99   nsITaskbarProgress getTaskbarProgress(in nsIDocShell shell);
 100
 101   /**
 102    * Taskbar icon overlay
 103    */
 104
 105   /**
 106    * Gets the taskbar icon overlay controller for a window. The docshell is used
 107    * to find the toplevel window. See the documentation in
 108    * nsITaskbarOverlayIconController for more details.
 109    */
 110   nsITaskbarOverlayIconController getOverlayIconController(in nsIDocShell shell);
 111
 112   /**
 113    * Taskbar and start menu jump list management
 114    */
 115
 116   /**
 117    * Retrieve a taskbar jump list builder
 118    *
 119    * Fails if a jump list build operation has already been initiated, developers
 120    * should make use of a single instance of nsIJumpListBuilder for building lists
 121    * within an application.
 122    *
 123    * @throw NS_ERROR_ALREADY_INITIALIZED if an nsIJumpListBuilder instance is
 124    * currently building a list.
 125    */
 126   nsIJumpListBuilder createJumpListBuilder();
 127
 128   /**
 129    * Application window taskbar group settings
 130    */
 131
 132   /**
 133    * Set the grouping id for a window.
 134    *
 135    * The runtime sets a default, global grouping id for all windows on startup.
 136    * setGroupIdForWindow allows individual windows to be grouped independently
 137    * on the taskbar. Ids should be unique to the app and window to insure
 138    * conflicts with other pinned applications do no arise.
 139    *
 140    * The default group id is based on application.ini vendor, application, and
 141    * version values, with a format of 'vendor.app.version'. The default can be
 142    * retrieved via defaultGroupId.
 143    *
 144    * Note, when a window changes taskbar window stacks, it is placed at the
 145    * bottom of the new stack.
 146    *
 147    * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
 148    * associated with a widget.
 149    * @throw NS_ERROR_FAILURE if the property on the window could not be set.
 150    * @throw NS_ERROR_UNEXPECTED for general failures.
 151    */
 152   void setGroupIdForWindow(in mozIDOMWindow aParent, in AString aIdentifier);
 153
 154   /**
 155    * Notify the taskbar that a window is about to enter full screen mode.
 156    *
 157    * A Windows autohide taskbar will not behave correctly in all cases if
 158    * it is not notified when full screen operations start and end.
 159    *
 160    * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
 161    * @throw NS_ERROR_UNEXPECTED for general failures.
 162    * @throw NS_ERROR_NOT_AVAILABLE if the taskbar cannot be obtained.
 163    */
 164   void prepareFullScreen(in mozIDOMWindow aWindow, in boolean aFullScreen);
 165
 166   /**
 167    * Notify the taskbar that a window identified by its HWND is about to enter
 168    * full screen mode.
 169    *
 170    * A Windows autohide taskbar will not behave correctly in all cases if
 171    * it is not notified when full screen operations start and end.
 172    *
 173    * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
 174    * @throw NS_ERROR_UNEXPECTED for general failures.
 175    * @throw NS_ERROR_NOT_AVAILABLE if the taskbar cannot be obtained.
 176    */
 177   [noscript] void prepareFullScreenHWND(in voidPtr aWindow, in boolean aFullScreen);
 178 };