nsIWinTaskbar

Starting with Windows 7, applications gain some control over their appearance in the taskbar. By default, there is a single taskbar preview per top level window (excluding pop-ups). This preview is represented by an nsITaskbarWindowPreview object.

An application can register its own "tab" previews. These previews automatically hide the corresponding nsITaskbarWindowPreview. These don't have to correspond to tabs within the application; they can vary in size, shape, and location. They don't even have to represent actual GUI elements on the window.

Unlike window previews, tab previews require most of the functionality of the nsITaskbarPreviewController interface be implemented.

Implemented by: @mozilla.org/windows-taskbar;1. To create an instance, use:

var winTaskbar = Components.classes["@mozilla.org/windows-taskbar;1"]
                 .getService(Components.interfaces.nsIWinTaskbar);

Method overview

Attributes

For XULRunner applications, the defaultGroupId attribute is configured using application.ini settings, and is of the format "vendor.application.version". For example, if the Vendor is configured to "Foobar Systems", the application's Name is "Squashweb", and the application's Version is 1.0, the defaultGroupId attribute would be "Foobar Systems.Squashweb.1.0". See XUL Application Packaging for additional details.

Methods

Retrieve a taskbar jump list builder.

Fails if a jump list build operation has already been initiated, developers should make use of a single instance of nsIJumpListBuilder for building lists within an application.

nsIJumpListBuilder createJumpListBuilder();

Parameters

None.

Return value

An nsIJumpListBuilder.

createTaskbarTabPreview()

Creates a taskbar tab preview, given an nsIDocShell reference to a top-level window.

nsITaskbarTabPreview createTaskbarTabPreview(
  in nsIDocShell shell,
  in nsITaskbarPreviewController controller
);

Parameters

shell

An nsIDocShell object representing the top-level window from which to create the preview.

controller

An nsITaskbarPreviewController you implement.

Return value

An nsITaskbarTabPreview object for the new tab preview.

Example

netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
var taskbar = Components.classes["@mozilla.org/windows-taskbar;1"].getService(Components.interfaces.nsIWinTaskbar);

// Get the docShell for the browser

var navigator2 = top.QueryInterface(Components.interfaces.nsIInterfaceRequestor).getInterface(Components.interfaces.nsIWebNavigation);
var docShell = navigator2.QueryInterface(Components.interfaces.nsIDocShell);

// Get the parent docShell; this is the top-level docShell

var docShellTreeItem = docShell.QueryInterface(Components.interfaces.nsIDocShellTreeItem);
var parent = docShellTreeItem.parent;
var ds = parent.QueryInterface(Components.interfaces.nsIDocShell);

// Create the preview

taskbar.createTaskbarTabPreview(ds, {});

getTaskbarProgress()

Gets the taskbar progress for a window.

nsITaskbarProgress getTaskbarProgress(
  in nsIDocShell shell
);

Parameters

shell

The nsIDocShell used to find the toplevel window.

Return value

An nsITaskbarProgress.

getTaskbarWindowPreview()

Returns the taskbar preview for the window whose top level is identified by nsIDocShell.

nsITaskbarWindowPreview getTaskbarWindowPreview(
  in nsIDocShell shell
);

Parameters

shell

An nsIDocShell object to use to find the top-level window.

Return value

An nsITaskbarWindowPreview object for the window's preview.

Set the grouping id for a window. Ids should be unique to the application and window to insure conflicts with other pinned applications do no arise.

void setGroupIdForWindow(
  in nsIDOMWindow aParent,
  in AString aIdentifier
);

Parameters

aParent

The parent nsIDOMWindow.

aIdentifier

The new identifier for the window.

See also

• nsITaskbarPreview
• nsITaskbarPreviewController
• nsITaskbarProgress
• nsITaskbarTabPreview
• nsITaskbarWindowPreview
• nsITaskbarPreviewButton