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 nsIDOMCanvasRenderingContext2D;
  12 interface nsITaskbarPreview;
  13 interface nsITaskbarPreviewButton;
  14
  15 /**
  16  * nsITaskbarPreviewController
  17  *
  18  * nsITaskbarPreviewController provides the behavior for the taskbar previews.
  19  * Its methods and properties are used by nsITaskbarPreview. Clients are
  20  * intended to provide their own implementation of this interface. Depending on
  21  * the interface the controller is attached to, only certain methods/attributes
  22  * are required to be implemented.
  23  */
  24 [scriptable, uuid(4FC0AFBB-3E22-4FBA-AC21-953350AF0411)]
  25 interface nsITaskbarPreviewController : nsISupports
  26 {
  27   /**
  28    * The width of the preview image. This value is allowed to change at any
  29    * time. See drawPreview for more information.
  30    */
  31   readonly attribute unsigned long width;
  32
  33   /**
  34    * The height of the preview image. This value is allowed to change at any
  35    * time.  See drawPreview for more information.
  36    */
  37   readonly attribute unsigned long height;
  38
  39   /**
  40    * The aspect ratio of the thumbnail - this does not need to match the ratio
  41    * of the preview. This value is allowed to change at any time. See
  42    * drawThumbnail for more information.
  43    */
  44   readonly attribute float thumbnailAspectRatio;
  45
  46   /**
  47    * Invoked by nsITaskbarPreview when it needs to render the preview. The
  48    * context is attached to a surface with the controller's width and height
  49    * which are obtained immediately before the call.
  50    *
  51    * Note that the context is not attached to a canvas element.
  52    *
  53    * @param ctx Canvas drawing context
  54    */
  55   boolean drawPreview(in nsIDOMCanvasRenderingContext2D ctx);
  56
  57   /**
  58    * Invoked by the taskbar preview when it needs to draw the thumbnail in the
  59    * taskbar's application preview window.
  60    *
  61    * Note: it is guaranteed that width/height == thumbnailAspectRatio
  62    * (modulo rounding errors)
  63    *
  64    * Also note that the context is not attached to a canvas element.
  65    *
  66    * @param ctx Canvas drawing context
  67    * @param width The width of the surface backing the drawing context
  68    * @param height The height of the surface backing the drawing context
  69    */
  70   boolean drawThumbnail(in nsIDOMCanvasRenderingContext2D ctx, in unsigned long width, in unsigned long height);
  71
  72   /**
  73    * Invoked when the user presses the close button on the tab preview.
  74    */
  75   void onClose();
  76
  77   /**
  78    * Invoked when the user clicks on the tab preview.
  79    *
  80    * @return true if the top level window corresponding to the preview should
  81    *         be activated, false if activation is not accepted.
  82    */
  83   boolean onActivate();
  84
  85   /**
  86    * Invoked when one of the buttons on the window preview's toolbar is pressed.
  87    *
  88    * @param button The button that was pressed. This can be compared with the
  89    *               buttons returned by nsITaskbarWindowPreview.getButton.
  90    */
  91   void onClick(in nsITaskbarPreviewButton button);
  92 };
  93