1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/widget/nsIWinTaskbar.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,178 @@
1.4 +/* vim: se cin sw=2 ts=2 et : */
1.5 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.6 + *
1.7 + * This Source Code Form is subject to the terms of the Mozilla Public
1.8 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.9 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.10 +
1.11 +#include "nsISupports.idl"
1.12 +#include "nsIBaseWindow.idl"
1.13 +
1.14 +interface nsIDocShell;
1.15 +interface nsITaskbarTabPreview;
1.16 +interface nsITaskbarWindowPreview;
1.17 +interface nsITaskbarPreviewController;
1.18 +interface nsITaskbarProgress;
1.19 +interface nsITaskbarOverlayIconController;
1.20 +interface nsIJumpListBuilder;
1.21 +interface nsIDOMWindow;
1.22 +
1.23 +/*
1.24 + * nsIWinTaskbar
1.25 + *
1.26 + * This interface represents a service which exposes the APIs provided by the
1.27 + * Windows taskbar to applications.
1.28 + *
1.29 + * Starting in Windows 7, applications gain some control over their appearance
1.30 + * in the taskbar. By default, there is one taskbar preview per top level
1.31 + * window (excluding popups). This preview is represented by an
1.32 + * nsITaskbarWindowPreview object.
1.33 + *
1.34 + * An application can register its own "tab" previews. Such previews will hide
1.35 + * the corresponding nsITaskbarWindowPreview automatically (though this is not
1.36 + * reflected in the visible attribute of the nsITaskbarWindowPreview). These
1.37 + * tab previews do not have to correspond to tabs in the application - they can
1.38 + * vary in size, shape and location. They do not even need to be actual GUI
1.39 + * elements on the window. Unlike window previews, tab previews require most of
1.40 + * the functionality of the nsITaskbarPreviewController to be implemented.
1.41 + *
1.42 + * Applications can also show progress on their taskbar icon. This does not
1.43 + * interact with the taskbar previews except if the nsITaskbarWindowPreview is
1.44 + * made invisible in which case the progress is naturally not shown on that
1.45 + * window.
1.46 + *
1.47 + * When taskbar icons are combined as is the default in Windows 7, the progress
1.48 + * for those windows is also combined as defined here:
1.49 + * http://msdn.microsoft.com/en-us/library/dd391697%28VS.85%29.aspx
1.50 + *
1.51 + * Applications may also define custom taskbar jump lists on application shortcuts.
1.52 + * See nsIJumpListBuilder for more information.
1.53 + */
1.54 +
1.55 +[scriptable, uuid(3232f40a-e94b-432d-9496-096abf1387bd)]
1.56 +interface nsIWinTaskbar : nsISupports
1.57 +{
1.58 + /**
1.59 + * Returns true if the operating system supports Win7+ taskbar features.
1.60 + * This property acts as a replacement for in-place os version checking.
1.61 + */
1.62 + readonly attribute boolean available;
1.63 +
1.64 + /**
1.65 + * Returns the default application user model identity the application
1.66 + * registers with the system. This id is used by the taskbar in grouping
1.67 + * windows and in associating pinned shortcuts with running instances and
1.68 + * jump lists.
1.69 + */
1.70 + readonly attribute AString defaultGroupId;
1.71 +
1.72 + /**
1.73 + * Taskbar window and tab preview management
1.74 + */
1.75 +
1.76 + /**
1.77 + * Creates a taskbar preview. The docshell should be a toplevel docshell and
1.78 + * is used to find the toplevel window. See the documentation for
1.79 + * nsITaskbarTabPreview for more information.
1.80 + */
1.81 + nsITaskbarTabPreview createTaskbarTabPreview(in nsIDocShell shell,
1.82 + in nsITaskbarPreviewController controller);
1.83 +
1.84 + /**
1.85 + * Gets the taskbar preview for a window. The docshell is used to find the
1.86 + * toplevel window. See the documentation for nsITaskbarTabPreview for more
1.87 + * information.
1.88 + *
1.89 + * Note: to implement custom drawing or buttons, a controller is required.
1.90 + */
1.91 + nsITaskbarWindowPreview getTaskbarWindowPreview(in nsIDocShell shell);
1.92 +
1.93 + /**
1.94 + * Taskbar icon progress indicator
1.95 + */
1.96 +
1.97 + /**
1.98 + * Gets the taskbar progress for a window. The docshell is used to find the
1.99 + * toplevel window. See the documentation for nsITaskbarProgress for more
1.100 + * information.
1.101 + */
1.102 + nsITaskbarProgress getTaskbarProgress(in nsIDocShell shell);
1.103 +
1.104 + /**
1.105 + * Taskbar icon overlay
1.106 + */
1.107 +
1.108 + /**
1.109 + * Gets the taskbar icon overlay controller for a window. The docshell is used
1.110 + * to find the toplevel window. See the documentation in
1.111 + * nsITaskbarOverlayIconController for more details.
1.112 + */
1.113 + nsITaskbarOverlayIconController getOverlayIconController(in nsIDocShell shell);
1.114 +
1.115 + /**
1.116 + * Taskbar and start menu jump list management
1.117 + */
1.118 +
1.119 + /**
1.120 + * Retrieve a taskbar jump list builder
1.121 + *
1.122 + * Fails if a jump list build operation has already been initiated, developers
1.123 + * should make use of a single instance of nsIJumpListBuilder for building lists
1.124 + * within an application.
1.125 + *
1.126 + * @throw NS_ERROR_ALREADY_INITIALIZED if an nsIJumpListBuilder instance is
1.127 + * currently building a list.
1.128 + */
1.129 + nsIJumpListBuilder createJumpListBuilder();
1.130 +
1.131 + /**
1.132 + * Application window taskbar group settings
1.133 + */
1.134 +
1.135 + /**
1.136 + * Set the grouping id for a window.
1.137 + *
1.138 + * The runtime sets a default, global grouping id for all windows on startup.
1.139 + * setGroupIdForWindow allows individual windows to be grouped independently
1.140 + * on the taskbar. Ids should be unique to the app and window to insure
1.141 + * conflicts with other pinned applications do no arise.
1.142 + *
1.143 + * The default group id is based on application.ini vendor, application, and
1.144 + * version values, with a format of 'vendor.app.version'. The default can be
1.145 + * retrieved via defaultGroupId.
1.146 + *
1.147 + * Note, when a window changes taskbar window stacks, it is placed at the
1.148 + * bottom of the new stack.
1.149 + *
1.150 + * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
1.151 + * associated with a widget.
1.152 + * @throw NS_ERROR_FAILURE if the property on the window could not be set.
1.153 + * @throw NS_ERROR_UNEXPECTED for general failures.
1.154 + */
1.155 + void setGroupIdForWindow(in nsIDOMWindow aParent, in AString aIdentifier);
1.156 +
1.157 + /**
1.158 + * Notify the taskbar that a window is about to enter full screen mode.
1.159 + *
1.160 + * A Windows autohide taskbar will not behave correctly in all cases if
1.161 + * it is not notified when full screen operations start and end.
1.162 + *
1.163 + * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
1.164 + * @throw NS_ERROR_UNEXPECTED for general failures.
1.165 + * @throw NS_ERROR_NOT_AVAILABLE if the taskbar cannot be obtained.
1.166 + */
1.167 + void prepareFullScreen(in nsIDOMWindow aWindow, in boolean aFullScreen);
1.168 +
1.169 + /**
1.170 + * Notify the taskbar that a window identified by its HWND is about to enter
1.171 + * full screen mode.
1.172 + *
1.173 + * A Windows autohide taskbar will not behave correctly in all cases if
1.174 + * it is not notified when full screen operations start and end.
1.175 + *
1.176 + * @throw NS_ERROR_INVALID_ARG if the window is not a valid top level window
1.177 + * @throw NS_ERROR_UNEXPECTED for general failures.
1.178 + * @throw NS_ERROR_NOT_AVAILABLE if the taskbar cannot be obtained.
1.179 + */
1.180 + [noscript] void prepareFullScreenHWND(in voidPtr aWindow, in boolean aFullScreen);
1.181 +};
