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