widget/nsITaskbarPreviewController.idl
author Rob Wu <rob@robwu.nl>
Sat, 24 Sep 2016 11:16:32 +0200
changeset 320058 a41f871e2d1b37754bbd1001c36c075511b49342
parent 279632 8afe4f072efd11c8d41a3718f71c01f429c264c8
permissions -rw-r--r--
Bug 1299411 - Decouple Port implementation from API r=aswan Decoupled the API from the implementation. From now on it is possible to create Port instances without generating an API. This allows us to internally use Ports to pass around messages with minimal overhead (in the form of unnecessary clones of messages). This will be used by native messaging. This commit has no behavioral change, it is mostly moving around some code and storing the internal message listener in a set. MozReview-Commit-ID: 4h0LNJvTH9R

/* 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"

interface nsIDocShell;
interface nsITaskbarPreview;
interface nsITaskbarPreviewButton;

/**
 * nsITaskbarPreviewCallback
 *
 * Provides an interface for async image result callbacks. See
 * nsITaskbarPreviewController request apis below.
 */
[scriptable, function, uuid(f3744696-320d-4804-9c27-6a84c29acaa6)]
interface nsITaskbarPreviewCallback : nsISupports
{
  void done(in nsISupports aCanvas, in boolean aDrawBorder);
};

/**
 * nsITaskbarPreviewController
 *
 * nsITaskbarPreviewController provides the behavior for the taskbar previews.
 * Its methods and properties are used by nsITaskbarPreview. Clients are
 * intended to provide their own implementation of this interface. Depending on
 * the interface the controller is attached to, only certain methods/attributes
 * are required to be implemented.
 */
[scriptable, uuid(8b427646-e446-4941-ae0b-c1122a173a68)]
interface nsITaskbarPreviewController : nsISupports
{
  /**
   * The width of the preview image. This value is allowed to change at any
   * time. See drawPreview for more information.
   */
  readonly attribute unsigned long width;

  /**
   * The height of the preview image. This value is allowed to change at any
   * time.  See drawPreview for more information.
   */
  readonly attribute unsigned long height;

  /**
   * The aspect ratio of the thumbnail - this does not need to match the ratio
   * of the preview. This value is allowed to change at any time. See
   * drawThumbnail for more information.
   */
  readonly attribute float thumbnailAspectRatio;

  [deprecated]
  boolean drawPreview(in nsISupports ctx);

  [deprecated]
  boolean drawThumbnail(in nsISupports ctx, in unsigned long width, in unsigned long height);

  /**
   * Invoked by nsITaskbarPreview when it needs to render the preview.
   *
   * @param aCallback Async callback the controller should invoke once
   * the thumbnail is rendered. aCallback receives as its only parameter
   * a canvas containing the preview image.
   */
  void requestPreview(in nsITaskbarPreviewCallback aCallback);

  /**
   * An asynchronous version of drawPreview and drawThumbnail apis
   * implemented in nsITaskbarPreviewController.
   *
   * Note: it is guaranteed that width/height == thumbnailAspectRatio
   * (modulo rounding errors)
   *
   * Also note that the context is not attached to a canvas element.
   *
   * @param aCallback Async callback the controller should invoke once
   * the thumbnail is rendered. aCallback receives as its only parameter
   * a canvas containing the thumbnail image. Canvas dimensions should
   * match the requested width or height otherwise setting the thumbnail
   * will fail.
   * @param width The width of the requested thumbnail
   * @param height The height of the requested thumbnail
   */
  void requestThumbnail(in nsITaskbarPreviewCallback aCallback,
                        in unsigned long width, in unsigned long height);

  /**
   * Invoked when the user presses the close button on the tab preview.
   */
  void onClose();

  /**
   * Invoked when the user clicks on the tab preview.
   *
   * @return true if the top level window corresponding to the preview should
   *         be activated, false if activation is not accepted.
   */
  boolean onActivate();

  /**
   * Invoked when one of the buttons on the window preview's toolbar is pressed.
   *
   * @param button The button that was pressed. This can be compared with the
   *               buttons returned by nsITaskbarWindowPreview.getButton.
   */
  void onClick(in nsITaskbarPreviewButton button);
};