widget/nsIWinTaskbar.idl
author Jim Chen <nchen@mozilla.com>
Wed, 20 Jun 2018 16:46:20 -0400
changeset 423113 2806729c61eaac199ad4670788c4008079a99f34
parent 282426 e22b3043887ed36bf2c634c2924a7c8d39d226b1
permissions -rw-r--r--
Bug 1469683 - 1. Fix crash tests; r=esawin Specify individual sessions in crash tests (i.e. "mainSession.waitUntilCalled" instead of "sessionRule.waitUntilCalled"), so that the tests assert behavior on the correct session, and not inadvertently on the cached session. Also, under x86 debug builds, Gecko installs an "ah_crap_handler" for SIGSEGV that waits for a long time, which causes our crash tests to time out. Therefore, ignore crash tests under x86 debug. MozReview-Commit-ID: DdtmRBLmPGp

/* 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);
};