widget/public/nsIWinTaskbar.idlScriptable
Represents a service that exposes the APIs provided by the Microsoft Windows taskbar.
1.0
66
Introduced
Gecko 1.9.2
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

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.

Warning: This API has undergone changes that are not yet documented. Among these is the addition of the method getOverlayIconController(). This method is currently known to crash if used under certain conditions. See bug 744992 for details and to track progress on a fix.

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

nsIJumpListBuilder createJumpListBuilder();
nsITaskbarTabPreview createTaskbarTabPreview(in nsIDocShell shell, in nsITaskbarPreviewController controller);
nsITaskbarProgress getTaskbarProgress(in nsIDocShell shell);
nsITaskbarWindowPreview getTaskbarWindowPreview(in nsIDocShell shell);
void setGroupIdForWindow(in nsIDOMWindow aParent, in AString aIdentifier);

Attributes

Attribute Type Description
available boolean Returns true if the operating system supports Windows 7 or later taskbar features; you can use this instead of in-place operating system version checking. Read only.
defaultGroupId AString The default application user model ID the application registers with the system. This ID is used by the taskbar for grouping windows and when associating pinned shortcuts with running instances and jump lists. Read only.

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

createJumpListBuilder()

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.

setGroupIdForWindow()

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