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 nsIJumpListBuilder;
  13 interface nsITaskbarTabPreview;
  14 interface nsITaskbarWindowPreview;
  15 interface nsITaskbarPreviewController;
  16 interface nsITaskbarProgress;
  17 interface nsITaskbarOverlayIconController;
  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    * Retrieves a Windows Jump List builder. This jump list builder can be used
 124    * to asynchronously add, remove, and update items in the Windows Jump List.
 125    *
 126    * @throws NS_ERROR_UNEXPECTED if the builder failed to be created.
 127    */
 128   nsIJumpListBuilder createJumpListBuilder(in boolean aPrivateBrowsing);
 129
 130   /**
 131    * Application window taskbar group settings
 132    */
 133
 134   /**
 135    * Get the grouping id for a window.
 136    *
 137    * The runtime sets a default, global grouping id for all windows on startup.
 138    * getGroupIdForWindow allows finding the grouping of individual windows
 139    * on the taskbar.
 140    *
 141    * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
 142    * associated with a widget.
 143    * @throw NS_ERROR_FAILURE if the property on the window could not be set.
 144    * @throw NS_ERROR_UNEXPECTED for general failures.
 145    */
 146   AString getGroupIdForWindow(in mozIDOMWindow aParent);
 147
 148   /**
 149    * Set the grouping id for a window.
 150    *
 151    * The runtime sets a default, global grouping id for all windows on startup.
 152    * setGroupIdForWindow allows individual windows to be grouped independently
 153    * on the taskbar. Ids should be unique to the app and window to insure
 154    * conflicts with other pinned applications do no arise.
 155    *
 156    * The default group id is based on application.ini vendor, application, and
 157    * version values, with a format of 'vendor.app.version'. The default can be
 158    * retrieved via defaultGroupId.
 159    *
 160    * Note, when a window changes taskbar window stacks, it is placed at the
 161    * bottom of the new stack.
 162    *
 163    * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
 164    * associated with a widget.
 165    * @throw NS_ERROR_FAILURE if the property on the window could not be set.
 166    * @throw NS_ERROR_UNEXPECTED for general failures.
 167    */
 168   void setGroupIdForWindow(in mozIDOMWindow aParent, in AString aIdentifier);
 169
 170   /**
 171    * Notify the taskbar that a window identified by its HWND is about to enter
 172    * full screen mode.
 173    *
 174    * A Windows autohide taskbar will not behave correctly in all cases if
 175    * it is not notified when full screen operations start and end.
 176    *
 177    * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
 178    * @throw NS_ERROR_UNEXPECTED for general failures.
 179    * @throw NS_ERROR_NOT_AVAILABLE if the taskbar cannot be obtained.
 180    */
 181   [noscript] void prepareFullScreen(in voidPtr aHWND, in boolean aFullScreen);
 182 };