nsITaskbarWindowPreview

widget/public/nsITaskbarWindowPreview.idlScriptable

This interface is used on Microsoft Windows to represent the preview for a window in the taskbar.

1.0

Introduced

Gecko 1.9.2

Inherits from: nsITaskbarPreview Last changed in Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

You can't directly instantiate this interface; instead, call nsIWinTaskbar.getTaskbarWindowPreview() to get the taskbar preview for a specific window.

Window preview behavior

By default, Windows implements much of the behavior for applications in a standard way. This interface's primary purpose is to let Gecko applications take control over parts of the preview; however, certain parts of the preview are not controlled using this interface. For example, the title and icon for each preview always match the title and icon of the corresponding window.

If the enableCustomDrawing attribute is true, the controller you implement will start receiving calls to its nsITaskbarPreviewController.drawPreview() and nsITaskbarPreviewController.drawThumbnail() methods, as well as reads of its width, height, and thumbnailAccessRatio attributes. By default, however, Windows handles this drawing by itself.

In addition, these previews are visible by default. When made invisible, the window disappears from the list of the application's windows in the taskbar.

If a window has any visible nsITaskbarTabPreview objects, the nsITaskbarWindowPreview for the corresponding window is automatically hidden. This is not reflected by the visible attribute. Note that even while the preview is hidden, its thumbnails and/or previews may still be requested by other parts of the operating system through the nsITaskbarWindowPreview's controller.

Note: This interface will never invoke the controller's nsITaskbarPreviewController.onClose() or nsITaskbarPreviewController.onActivate() methods, since handling them may conflict with other internal Gecko state management. There is existing infrastructure in place to let clients handle those events.

Window preview toolbars

Window previews may have a toolbar with up to seven buttons. The array of buttons may be accessed by calling getButton(); each button is an nsITaskbarPreviewButton object. You may customize these buttons using the attributes on that interface. User clicks on the toolbar buttons are reported to your nsITaskbarPreviewController implementation's nsITaskbarPreviewController.onClick() method.

Method overview

nsITaskbarPreviewButton getButton(in unsigned long index);

Attributes

Attribute	Type	Description
`enableCustomDrawing`	`boolean`	If true, the `nsITaskbarPreviewController` object's `nsITaskbarPreviewController.drawPreview()` and `nsITaskbarPreviewController.drawThumbnail()` methods will be called to draw the preview. If false, the operating system draws these for you.

Constants

Constant	Value	Description
`NUM_TOOLBAR_BUTTONS`	`7`	The maximum number of toolbar buttons supported by the Windows Taskbar API.

Methods

getButton()

Returns the specified button from the preview's toolbar.

Note: By default, all buttons are hidden. You must fetch and configure each button that you want to make visible.

nsITaskbarPreviewButton getButton(
  in unsigned long index
);

Parameters

index: The index into the button array for the nsITaskbarPreviewButton to retrieve. This value must be at least 0 (the leftmost button) and less than NUM_TOOLBAR_BUTTONS.

Return value

An nsITaskbarPreviewButton describing the requested button.