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 nsILegacyJumpListBuilder;
  19 interface mozIDOMWindow;
  20
  21 /*
  22  * nsIWinTaskbar
  23  *
  24  * This interface represents a service which exposes the APIs provided by the
  25  * Windows taskbar to applications.
  26  *
  27  * Starting in Windows 7, applications gain some control over their appearance
  28  * in the taskbar. By default, there is one taskbar preview per top level
  29  * window (excluding popups). This preview is represented by an
  30  * nsITaskbarWindowPreview object.
  31  *
  32  * An application can register its own "tab" previews. Such previews will hide
  33  * the corresponding nsITaskbarWindowPreview automatically (though this is not
  34  * reflected in the visible attribute of the nsITaskbarWindowPreview). These
  35  * tab previews do not have to correspond to tabs in the application - they can
  36  * vary in size, shape and location. They do not even need to be actual GUI
  37  * elements on the window. Unlike window previews, tab previews require most of
  38  * the functionality of the nsITaskbarPreviewController to be implemented.
  39  *
  40  * Applications can also show progress on their taskbar icon. This does not
  41  * interact with the taskbar previews except if the nsITaskbarWindowPreview is
  42  * made invisible in which case the progress is naturally not shown on that
  43  * window.
  44  *
  45  * When taskbar icons are combined as is the default in Windows 7, the progress
  46  * for those windows is also combined as defined here:
  47  * http://msdn.microsoft.com/en-us/library/dd391697%28VS.85%29.aspx
  48  *
  49  * Applications may also define custom taskbar jump lists on application shortcuts.
  50  * See nsILegacyJumpListBuilder for more information.
  51  */
  52
  53 [scriptable, uuid(11751471-9246-4c72-a80f-0c7df765d640)]
  54 interface nsIWinTaskbar : nsISupports
  55 {
  56   /**
  57    * Returns true if the operating system supports Win7+ taskbar features.
  58    * This property acts as a replacement for in-place os version checking.
  59    */
  60   readonly attribute boolean available;
  61
  62   /**
  63    * Returns the default application user model identity the application
  64    * registers with the system. This id is used by the taskbar in grouping
  65    * windows and in associating pinned shortcuts with running instances and
  66    * jump lists.
  67    */
  68   readonly attribute AString defaultGroupId;
  69
  70   /**
  71    * Same as above, but a different value so that Private Browsing windows
  72    * can be separated in the Taskbar.
  73    */
  74   readonly attribute AString defaultPrivateGroupId;
  75
  76   /**
  77    * Taskbar window and tab preview management
  78    */
  79
  80   /**
  81    * Creates a taskbar preview. The docshell should be a toplevel docshell and
  82    * is used to find the toplevel window. See the documentation for
  83    * nsITaskbarTabPreview for more information.
  84    */
  85   nsITaskbarTabPreview createTaskbarTabPreview(in nsIDocShell shell,
  86                                                in nsITaskbarPreviewController controller);
  87
  88   /**
  89    * Gets the taskbar preview for a window. The docshell is used to find the
  90    * toplevel window. See the documentation for nsITaskbarTabPreview for more
  91    * information.
  92    *
  93    * Note: to implement custom drawing or buttons, a controller is required.
  94    */
  95   nsITaskbarWindowPreview getTaskbarWindowPreview(in nsIDocShell shell);
  96
  97   /**
  98    * Taskbar icon progress indicator
  99    */
 100
 101   /**
 102    * Gets the taskbar progress for a window. The docshell is used to find the
 103    * toplevel window. See the documentation for nsITaskbarProgress for more
 104    * information.
 105    */
 106   nsITaskbarProgress getTaskbarProgress(in nsIDocShell shell);
 107
 108   /**
 109    * Taskbar icon overlay
 110    */
 111
 112   /**
 113    * Gets the taskbar icon overlay controller for a window. The docshell is used
 114    * to find the toplevel window. See the documentation in
 115    * nsITaskbarOverlayIconController for more details.
 116    */
 117   nsITaskbarOverlayIconController getOverlayIconController(in nsIDocShell shell);
 118
 119   /**
 120    * Taskbar and start menu jump list management
 121    */
 122
 123   /**
 124    * Retrieve a legacy taskbar jump list builder. This jump list builder backend
 125    * is in the process of being phased out.
 126    *
 127    * Fails if a jump list build operation has already been initiated, developers
 128    * should make use of a single instance of nsILegacyJumpListBuilder for building lists
 129    * within an application.
 130    *
 131    * @throws NS_ERROR_ALREADY_INITIALIZED if an nsILegacyJumpListBuilder instance is
 132    * currently building a list.
 133    */
 134   nsILegacyJumpListBuilder createLegacyJumpListBuilder(in boolean aPrivateBrowsing);
 135
 136   /**
 137    * Retrieves a Windows Jump List builder. This jump list builder can be used
 138    * to asynchronously add, remove, and update items in the Windows Jump List.
 139    *
 140    * @throws NS_ERROR_UNEXPECTED if the builder failed to be created.
 141    */
 142   nsIJumpListBuilder createJumpListBuilder(in boolean aPrivateBrowsing);
 143
 144   /**
 145    * Application window taskbar group settings
 146    */
 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 };