widget/nsITaskbarPreviewController.idl

   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
  10 interface nsIDocShell;
  11 interface nsITaskbarPreview;
  12 interface 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)]
  21 interface 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)]
  36 interface nsITaskbarPreviewController : nsISupports
  37 {
  38   /**
  39    * The width of the preview image. This value is allowed to change at any
  40    * time. See requestPreview 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 requestPreview 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    * requestThumbnail for more information.
  54    */
  55   readonly attribute float thumbnailAspectRatio;
  56
  57   /**
  58    * Invoked by nsITaskbarPreview when it needs to render the preview.
  59    *
  60    * @param aCallback Async callback the controller should invoke once
  61    * the thumbnail is rendered. aCallback receives as its only parameter
  62    * a canvas containing the preview image.
  63    */
  64   void requestPreview(in nsITaskbarPreviewCallback aCallback);
  65
  66   /**
  67    * Note: it is guaranteed that width/height == thumbnailAspectRatio
  68    * (modulo rounding errors)
  69    *
  70    * Also note that the context is not attached to a canvas element.
  71    *
  72    * @param aCallback Async callback the controller should invoke once
  73    * the thumbnail is rendered. aCallback receives as its only parameter
  74    * a canvas containing the thumbnail image. Canvas dimensions should
  75    * match the requested width or height otherwise setting the thumbnail
  76    * will fail.
  77    * @param width The width of the requested thumbnail
  78    * @param height The height of the requested thumbnail
  79    */
  80   void requestThumbnail(in nsITaskbarPreviewCallback aCallback,
  81                         in unsigned long width, in unsigned long height);
  82
  83   /**
  84    * Invoked when the user presses the close button on the tab preview.
  85    */
  86   void onClose();
  87
  88   /**
  89    * Invoked when the user clicks on the tab preview.
  90    *
  91    * @return true if the top level window corresponding to the preview should
  92    *         be activated, false if activation is not accepted.
  93    */
  94   boolean onActivate();
  95
  96   /**
  97    * Invoked when one of the buttons on the window preview's toolbar is pressed.
  98    *
  99    * @param button The button that was pressed. This can be compared with the
 100    *               buttons returned by nsITaskbarWindowPreview.getButton.
 101    */
 102   void onClick(in nsITaskbarPreviewButton button);
 103 };