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    * Same as above, but a different value so that Private Browsing windows
  71    * can be separated in the Taskbar.
  72    */
  73   readonly attribute AString defaultPrivateGroupId;
  74
  75   /**
  76    * Taskbar window and tab preview management
  77    */
  78
  79   /**
  80    * Creates a taskbar preview. The docshell should be a toplevel docshell and
  81    * is used to find the toplevel window. See the documentation for
  82    * nsITaskbarTabPreview for more information.
  83    */
  84   nsITaskbarTabPreview createTaskbarTabPreview(in nsIDocShell shell,
  85                                                in nsITaskbarPreviewController controller);
  86
  87   /**
  88    * Gets the taskbar preview for a window. The docshell is used to find the
  89    * toplevel window. See the documentation for nsITaskbarTabPreview for more
  90    * information.
  91    *
  92    * Note: to implement custom drawing or buttons, a controller is required.
  93    */
  94   nsITaskbarWindowPreview getTaskbarWindowPreview(in nsIDocShell shell);
  95
  96   /**
  97    * Taskbar icon progress indicator
  98    */
  99
 100   /**
 101    * Gets the taskbar progress for a window. The docshell is used to find the
 102    * toplevel window. See the documentation for nsITaskbarProgress for more
 103    * information.
 104    */
 105   nsITaskbarProgress getTaskbarProgress(in nsIDocShell shell);
 106
 107   /**
 108    * Taskbar icon overlay
 109    */
 110
 111   /**
 112    * Gets the taskbar icon overlay controller for a window. The docshell is used
 113    * to find the toplevel window. See the documentation in
 114    * nsITaskbarOverlayIconController for more details.
 115    */
 116   nsITaskbarOverlayIconController getOverlayIconController(in nsIDocShell shell);
 117
 118   /**
 119    * Taskbar and start menu jump list management
 120    */
 121
 122   /**
 123    * Retrieve a taskbar jump list builder
 124    *
 125    * Fails if a jump list build operation has already been initiated, developers
 126    * should make use of a single instance of nsIJumpListBuilder for building lists
 127    * within an application.
 128    *
 129    * @throw NS_ERROR_ALREADY_INITIALIZED if an nsIJumpListBuilder instance is
 130    * currently building a list.
 131    */
 132   nsIJumpListBuilder createJumpListBuilder(in boolean aPrivateBrowsing);
 133
 134   /**
 135    * Application window taskbar group settings
 136    */
 137
 138   /**
 139    * Set the grouping id for a window.
 140    *
 141    * The runtime sets a default, global grouping id for all windows on startup.
 142    * setGroupIdForWindow allows individual windows to be grouped independently
 143    * on the taskbar. Ids should be unique to the app and window to insure
 144    * conflicts with other pinned applications do no arise.
 145    *
 146    * The default group id is based on application.ini vendor, application, and
 147    * version values, with a format of 'vendor.app.version'. The default can be
 148    * retrieved via defaultGroupId.
 149    *
 150    * Note, when a window changes taskbar window stacks, it is placed at the
 151    * bottom of the new stack.
 152    *
 153    * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
 154    * associated with a widget.
 155    * @throw NS_ERROR_FAILURE if the property on the window could not be set.
 156    * @throw NS_ERROR_UNEXPECTED for general failures.
 157    */
 158   void setGroupIdForWindow(in mozIDOMWindow aParent, in AString aIdentifier);
 159
 160   /**
 161    * Notify the taskbar that a window identified by its HWND is about to enter
 162    * full screen mode.
 163    *
 164    * A Windows autohide taskbar will not behave correctly in all cases if
 165    * it is not notified when full screen operations start and end.
 166    *
 167    * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
 168    * @throw NS_ERROR_UNEXPECTED for general failures.
 169    * @throw NS_ERROR_NOT_AVAILABLE if the taskbar cannot be obtained.
 170    */
 171   [noscript] void prepareFullScreen(in voidPtr aHWND, in boolean aFullScreen);
 172 };