widget/nsITaskbarWindowPreview.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 "nsITaskbarPreview.idl"
   9 interface nsITaskbarPreviewButton;
  10
  11 /*
  12  * nsITaskbarWindowPreview
  13  *
  14  * This interface represents the preview for a window in the taskbar. By
  15  * default, Windows implements much of the behavior for applications by
  16  * default. The primary purpose of this interface is to allow Gecko
  17  * applications to take control over parts of the preview. Some parts are not
  18  * controlled through this interface: the title and icon of the preview match
  19  * the title and icon of the window always.
  20  *
  21  * By default, Windows takes care of drawing the thumbnail and preview for the
  22  * application however if enableCustomDrawing is set to true, then the
  23  * controller will start to receive requestPreview and requestThumbnail calls
  24  * as well as reads on the thumbnailAspectRatio, width and height properties.
  25  *
  26  * By default, nsITaskbarWindowPreviews are visible. When made invisible, the
  27  * window disappears from the list of windows in the taskbar for the
  28  * application.
  29  *
  30  * If the window has any visible nsITaskbarTabPreviews, then the
  31  * nsITaskbarWindowPreview for the corresponding window is automatically
  32  * hidden. This is not reflected in the visible property. Note that other parts
  33  * of the system (such as alt-tab) may still request thumbnails and/or previews
  34  * through the nsITaskbarWindowPreview's controller.
  35  *
  36  * nsITaskbarWindowPreview will never invoke the controller's onClose or
  37  * onActivate methods since handling them may conflict with other internal
  38  * Gecko state and there is existing infrastructure in place to allow clients
  39  * to handle those events
  40  *
  41  * Window previews may have a toolbar with up to 7 buttons. See
  42  * nsITaskbarPreviewButton for more information about button properties.
  43  */
  44 [scriptable, uuid(EC67CC57-342D-4064-B4C6-74A375E07B10)]
  45 interface nsITaskbarWindowPreview : nsITaskbarPreview
  46 {
  47   /**
  48    * Max 7 buttons per preview per the Windows Taskbar API
  49    */
  50   const long NUM_TOOLBAR_BUTTONS = 7;
  51
  52   /**
  53    * Gets the nth button for the preview image. By default, all of the buttons
  54    * are invisible.
  55    *
  56    * @see nsITaskbarPreviewButton
  57    *
  58    * @param index The index into the button array. Must be >= 0 and <
  59    *              MAX_TOOLBAR_BUTTONS.
  60    */
  61   nsITaskbarPreviewButton getButton(in unsigned long index);
  62
  63   /**
  64    * Enables/disables custom drawing of thumbnails and previews
  65    *
  66    * Default value: false
  67    */
  68   attribute boolean enableCustomDrawing;
  69 };