michael@0: /* vim: se cin sw=2 ts=2 et : */
michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
michael@0:  *
michael@0:  * This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: #include "nsIBaseWindow.idl"
michael@0: 
michael@0: interface nsIDocShell;
michael@0: interface nsITaskbarTabPreview;
michael@0: interface nsITaskbarWindowPreview;
michael@0: interface nsITaskbarPreviewController;
michael@0: interface nsITaskbarProgress;
michael@0: interface nsITaskbarOverlayIconController;
michael@0: interface nsIJumpListBuilder;
michael@0: interface nsIDOMWindow;
michael@0: 
michael@0: /*
michael@0:  * nsIWinTaskbar
michael@0:  *
michael@0:  * This interface represents a service which exposes the APIs provided by the
michael@0:  * Windows taskbar to applications.
michael@0:  *
michael@0:  * Starting in Windows 7, applications gain some control over their appearance
michael@0:  * in the taskbar. By default, there is one taskbar preview per top level
michael@0:  * window (excluding popups). This preview is represented by an
michael@0:  * nsITaskbarWindowPreview object.
michael@0:  *
michael@0:  * An application can register its own "tab" previews. Such previews will hide
michael@0:  * the corresponding nsITaskbarWindowPreview automatically (though this is not
michael@0:  * reflected in the visible attribute of the nsITaskbarWindowPreview). These
michael@0:  * tab previews do not have to correspond to tabs in the application - they can
michael@0:  * vary in size, shape and location. They do not even need to be actual GUI
michael@0:  * elements on the window. Unlike window previews, tab previews require most of
michael@0:  * the functionality of the nsITaskbarPreviewController to be implemented.
michael@0:  *
michael@0:  * Applications can also show progress on their taskbar icon. This does not
michael@0:  * interact with the taskbar previews except if the nsITaskbarWindowPreview is
michael@0:  * made invisible in which case the progress is naturally not shown on that
michael@0:  * window.
michael@0:  *
michael@0:  * When taskbar icons are combined as is the default in Windows 7, the progress
michael@0:  * for those windows is also combined as defined here:
michael@0:  * http://msdn.microsoft.com/en-us/library/dd391697%28VS.85%29.aspx
michael@0:  *
michael@0:  * Applications may also define custom taskbar jump lists on application shortcuts.
michael@0:  * See nsIJumpListBuilder for more information.
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(3232f40a-e94b-432d-9496-096abf1387bd)]
michael@0: interface nsIWinTaskbar : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Returns true if the operating system supports Win7+ taskbar features.
michael@0:    * This property acts as a replacement for in-place os version checking.
michael@0:    */
michael@0:   readonly attribute boolean available;
michael@0: 
michael@0:   /**
michael@0:    * Returns the default application user model identity the application
michael@0:    * registers with the system. This id is used by the taskbar in grouping
michael@0:    * windows and in associating pinned shortcuts with running instances and
michael@0:    * jump lists.
michael@0:    */
michael@0:   readonly attribute AString defaultGroupId;
michael@0: 
michael@0:   /**
michael@0:    * Taskbar window and tab preview management
michael@0:    */
michael@0: 
michael@0:   /**
michael@0:    * Creates a taskbar preview. The docshell should be a toplevel docshell and
michael@0:    * is used to find the toplevel window. See the documentation for
michael@0:    * nsITaskbarTabPreview for more information.
michael@0:    */
michael@0:   nsITaskbarTabPreview createTaskbarTabPreview(in nsIDocShell shell,
michael@0:                                                in nsITaskbarPreviewController controller);
michael@0: 
michael@0:   /**
michael@0:    * Gets the taskbar preview for a window. The docshell is used to find the
michael@0:    * toplevel window. See the documentation for nsITaskbarTabPreview for more
michael@0:    * information.
michael@0:    *
michael@0:    * Note: to implement custom drawing or buttons, a controller is required.
michael@0:    */
michael@0:   nsITaskbarWindowPreview getTaskbarWindowPreview(in nsIDocShell shell);
michael@0: 
michael@0:   /**
michael@0:    * Taskbar icon progress indicator
michael@0:    */
michael@0: 
michael@0:   /**
michael@0:    * Gets the taskbar progress for a window. The docshell is used to find the
michael@0:    * toplevel window. See the documentation for nsITaskbarProgress for more
michael@0:    * information.
michael@0:    */
michael@0:   nsITaskbarProgress getTaskbarProgress(in nsIDocShell shell);
michael@0: 
michael@0:   /**
michael@0:    * Taskbar icon overlay
michael@0:    */
michael@0: 
michael@0:   /**
michael@0:    * Gets the taskbar icon overlay controller for a window. The docshell is used
michael@0:    * to find the toplevel window. See the documentation in
michael@0:    * nsITaskbarOverlayIconController for more details.
michael@0:    */
michael@0:   nsITaskbarOverlayIconController getOverlayIconController(in nsIDocShell shell);
michael@0: 
michael@0:   /**
michael@0:    * Taskbar and start menu jump list management
michael@0:    */
michael@0: 
michael@0:   /**
michael@0:    * Retrieve a taskbar jump list builder
michael@0:    *
michael@0:    * Fails if a jump list build operation has already been initiated, developers
michael@0:    * should make use of a single instance of nsIJumpListBuilder for building lists
michael@0:    * within an application.
michael@0:    *
michael@0:    * @throw NS_ERROR_ALREADY_INITIALIZED if an nsIJumpListBuilder instance is
michael@0:    * currently building a list.
michael@0:    */
michael@0:   nsIJumpListBuilder createJumpListBuilder();
michael@0: 
michael@0:   /**
michael@0:    * Application window taskbar group settings
michael@0:    */
michael@0: 
michael@0:   /**
michael@0:    * Set the grouping id for a window.
michael@0:    *
michael@0:    * The runtime sets a default, global grouping id for all windows on startup.
michael@0:    * setGroupIdForWindow allows individual windows to be grouped independently
michael@0:    * on the taskbar. Ids should be unique to the app and window to insure
michael@0:    * conflicts with other pinned applications do no arise.
michael@0:    *
michael@0:    * The default group id is based on application.ini vendor, application, and
michael@0:    * version values, with a format of 'vendor.app.version'. The default can be
michael@0:    * retrieved via defaultGroupId.
michael@0:    *
michael@0:    * Note, when a window changes taskbar window stacks, it is placed at the
michael@0:    * bottom of the new stack.
michael@0:    *
michael@0:    * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
michael@0:    * associated with a widget.
michael@0:    * @throw NS_ERROR_FAILURE if the property on the window could not be set.
michael@0:    * @throw NS_ERROR_UNEXPECTED for general failures.
michael@0:    */
michael@0:   void setGroupIdForWindow(in nsIDOMWindow aParent, in AString aIdentifier);
michael@0: 
michael@0:   /**
michael@0:    * Notify the taskbar that a window is about to enter full screen mode.
michael@0:    *
michael@0:    * A Windows autohide taskbar will not behave correctly in all cases if
michael@0:    * it is not notified when full screen operations start and end.
michael@0:    *
michael@0:    * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
michael@0:    * @throw NS_ERROR_UNEXPECTED for general failures.
michael@0:    * @throw NS_ERROR_NOT_AVAILABLE if the taskbar cannot be obtained.
michael@0:    */
michael@0:   void prepareFullScreen(in nsIDOMWindow aWindow, in boolean aFullScreen);
michael@0: 
michael@0:   /**
michael@0:    * Notify the taskbar that a window identified by its HWND is about to enter
michael@0:    * full screen mode.
michael@0:    *
michael@0:    * A Windows autohide taskbar will not behave correctly in all cases if
michael@0:    * it is not notified when full screen operations start and end.
michael@0:    *
michael@0:    * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
michael@0:    * @throw NS_ERROR_UNEXPECTED for general failures.
michael@0:    * @throw NS_ERROR_NOT_AVAILABLE if the taskbar cannot be obtained.
michael@0:    */
michael@0:   [noscript] void prepareFullScreenHWND(in voidPtr aWindow, in boolean aFullScreen);
michael@0: };