DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (25c4c2685699)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 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);
};