widget/nsIWinTaskbar.idl@b8a032363ba2
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
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/. */
8 #include "nsISupports.idl"
9 #include "nsIBaseWindow.idl"
11 interface nsIDocShell;
12 interface nsITaskbarTabPreview;
13 interface nsITaskbarWindowPreview;
14 interface nsITaskbarPreviewController;
15 interface nsITaskbarProgress;
16 interface nsITaskbarOverlayIconController;
17 interface nsIJumpListBuilder;
18 interface nsIDOMWindow;
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 */
52 [scriptable, uuid(3232f40a-e94b-432d-9496-096abf1387bd)]
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;
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;
69 /**
70 * Taskbar window and tab preview management
71 */
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);
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);
90 /**
91 * Taskbar icon progress indicator
92 */
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);
101 /**
102 * Taskbar icon overlay
103 */
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);
112 /**
113 * Taskbar and start menu jump list management
114 */
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();
128 /**
129 * Application window taskbar group settings
130 */
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 nsIDOMWindow aParent, in AString aIdentifier);
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 nsIDOMWindow aWindow, in boolean aFullScreen);
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 };
