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