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