summaryrefslogtreecommitdiffstats
path: root/widget/nsIWinTaskbar.idl
diff options
context:
space:
mode:
Diffstat (limited to 'widget/nsIWinTaskbar.idl')
-rw-r--r--widget/nsIWinTaskbar.idl196
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);
+};