widget/nsIWinTaskbar.idl
author Masayuki Nakano <masayuki@d-toybox.com>
Thu, 15 Sep 2016 00:48:47 +0900
changeset 360042 de82c28636a102736d72f823a934030eda7c8fb5
parent 320665 e22b3043887ed36bf2c634c2924a7c8d39d226b1
permissions -rw-r--r--
Bug 1297013 part.2 Implement some helper methods to log constants related to event handling r=smaug This patch implements some helper methods to log constants related to event handling. ToString(KeyNameIndex) and ToString(CodeNameIndex) converts the enum itmes to human readable string. They use WidgetKeyboardEvent's helper class which returns Unicode text. Therefore, this need to convert from UTF16 to UTF8. That's the reason why these methods don't return |const char*|. GetDOMKeyCodeName(uint32_t) returns DOM keycode name if it's defined. Otherwise, returns hexadecimal value. For generating switch-case statement, VirtualKeyCodeList.h shouldn't include ",". Therefore, this patch removes "," from VirtualKeyCodeList.h and append it at defining NS_DEFINE_VK. Additionally, the last item of enum and array should not end with ",". Therefore, this adds dummy last item at each of them. Finally, some of the keyCode values are shared between 2 keys. Therefore, it needs to support NS_DISALLOW_SAME_KEYCODE for switch-case generator. See the comment in the file for more detail. GetModifiersName(Modifiers) returns all modifier names included in the given value. MozReview-Commit-ID: 9i2ftFOTpDn

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