1/* vim: se cin sw=2 ts=2 et : */
2/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
3 *
4 * This Source Code Form is subject to the terms of the Mozilla Public
5 * License, v. 2.0. If a copy of the MPL was not distributed with this
6 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7
8#include "nsISupports.idl"
9
10interface nsIDocShell;
11interface nsITaskbarPreview;
12interface nsITaskbarPreviewButton;
13
14/**
15 * nsITaskbarPreviewCallback
16 *
17 * Provides an interface for async image result callbacks. See
18 * nsITaskbarPreviewController request apis below.
19 */
20[scriptable, function, uuid(f3744696-320d-4804-9c27-6a84c29acaa6)]
21interface nsITaskbarPreviewCallback : nsISupports
22{
23  void done(in nsISupports aCanvas, in boolean aDrawBorder);
24};
25
26/**
27 * nsITaskbarPreviewController
28 *
29 * nsITaskbarPreviewController provides the behavior for the taskbar previews.
30 * Its methods and properties are used by nsITaskbarPreview. Clients are
31 * intended to provide their own implementation of this interface. Depending on
32 * the interface the controller is attached to, only certain methods/attributes
33 * are required to be implemented.
34 */
35[scriptable, uuid(8b427646-e446-4941-ae0b-c1122a173a68)]
36interface nsITaskbarPreviewController : nsISupports
37{
38  /**
39   * The width of the preview image. This value is allowed to change at any
40   * time. See drawPreview for more information.
41   */
42  readonly attribute unsigned long width;
43
44  /**
45   * The height of the preview image. This value is allowed to change at any
46   * time.  See drawPreview for more information.
47   */
48  readonly attribute unsigned long height;
49
50  /**
51   * The aspect ratio of the thumbnail - this does not need to match the ratio
52   * of the preview. This value is allowed to change at any time. See
53   * drawThumbnail for more information.
54   */
55  readonly attribute float thumbnailAspectRatio;
56
57  [deprecated]
58  boolean drawPreview(in nsISupports ctx);
59
60  [deprecated]
61  boolean drawThumbnail(in nsISupports ctx, in unsigned long width, in unsigned long height);
62
63  /**
64   * Invoked by nsITaskbarPreview when it needs to render the preview.
65   *
66   * @param aCallback Async callback the controller should invoke once
67   * the thumbnail is rendered. aCallback receives as its only parameter
68   * a canvas containing the preview image.
69   */
70  void requestPreview(in nsITaskbarPreviewCallback aCallback);
71
72  /**
73   * An asynchronous version of drawPreview and drawThumbnail apis
74   * implemented in nsITaskbarPreviewController.
75   *
76   * Note: it is guaranteed that width/height == thumbnailAspectRatio
77   * (modulo rounding errors)
78   *
79   * Also note that the context is not attached to a canvas element.
80   *
81   * @param aCallback Async callback the controller should invoke once
82   * the thumbnail is rendered. aCallback receives as its only parameter
83   * a canvas containing the thumbnail image. Canvas dimensions should
84   * match the requested width or height otherwise setting the thumbnail
85   * will fail.
86   * @param width The width of the requested thumbnail
87   * @param height The height of the requested thumbnail
88   */
89  void requestThumbnail(in nsITaskbarPreviewCallback aCallback,
90                        in unsigned long width, in unsigned long height);
91
92  /**
93   * Invoked when the user presses the close button on the tab preview.
94   */
95  void onClose();
96
97  /**
98   * Invoked when the user clicks on the tab preview.
99   *
100   * @return true if the top level window corresponding to the preview should
101   *         be activated, false if activation is not accepted.
102   */
103  boolean onActivate();
104
105  /**
106   * Invoked when one of the buttons on the window preview's toolbar is pressed.
107   *
108   * @param button The button that was pressed. This can be compared with the
109   *               buttons returned by nsITaskbarWindowPreview.getButton.
110   */
111  void onClick(in nsITaskbarPreviewButton button);
112};
113