1 files changed, 178 insertions, 0 deletions
diff --git a/widget/nsIWinTaskbar.idl b/widget/nsIWinTaskbar.idl
new file mode 100644
index 000000000..bcc2dd128
--- /dev/null
+++ b/widget/nsIWinTaskbar.idl
@@ -0,0 +1,178 @@
+/* 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 nsITaskbarTabPreview;
+interface nsITaskbarWindowPreview;
+interface nsITaskbarPreviewController;
+interface nsITaskbarProgress;
+interface nsITaskbarOverlayIconController;
+interface nsIJumpListBuilder;
+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 nsIJumpListBuilder 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;
+
+  /**
+   * 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 taskbar jump list builder
+   *
+   * Fails if a jump list build operation has already been initiated, developers
+   * should make use of a single instance of nsIJumpListBuilder for building lists
+   * within an application.
+   *
+   * @throw NS_ERROR_ALREADY_INITIALIZED if an nsIJumpListBuilder instance is
+   * currently building a list.
+   */
+  nsIJumpListBuilder createJumpListBuilder();
+
+  /**
+   * Application window taskbar group settings
+   */
+
+  /**
+   * 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 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.
+   */
+  void prepareFullScreen(in mozIDOMWindow aWindow, in boolean aFullScreen);
+
+  /**
+   * 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 prepareFullScreenHWND(in voidPtr aWindow, in boolean aFullScreen);
+};