diff options
Diffstat (limited to 'widget/nsIWinTaskbar.idl')
| -rw-r--r-- | widget/nsIWinTaskbar.idl | 196 |
1 files changed, 196 insertions, 0 deletions
diff --git a/widget/nsIWinTaskbar.idl b/widget/nsIWinTaskbar.idl new file mode 100644 index 0000000000..7d9b96a9d8 --- /dev/null +++ b/widget/nsIWinTaskbar.idl @@ -0,0 +1,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); +}; |