ITaskbarList3 interface (shobjidl_core.h)

Article
07/22/2021

Extends ITaskbarList2 by exposing methods that support the unified launching and switching taskbar button functionality added in Windows 7. This functionality includes thumbnail representations and switch targets based on individual tabs in a tabbed application, thumbnail toolbars, notification and status overlays, and progress indicators.

Inheritance

The ITaskbarList3 interface inherits from ITaskbarList2. ITaskbarList3 also has these types of members:

Methods

The ITaskbarList3 interface has these methods.


ITaskbarList3::RegisterTab Informs the taskbar that a new tab or document thumbnail has been provided for display in an application's taskbar group flyout.
ITaskbarList3::SetOverlayIcon Applies an overlay to a taskbar button to indicate application status or a notification to the user.
ITaskbarList3::SetProgressState Sets the type and state of the progress indicator displayed on a taskbar button.
ITaskbarList3::SetProgressValue Displays or updates a progress bar hosted in a taskbar button to show the specific percentage completed of the full operation.
ITaskbarList3::SetTabActive Informs the taskbar that a tab or document window has been made the active window.
ITaskbarList3::SetTabOrder Inserts a new thumbnail into a tabbed-document interface (TDI) or multiple-document interface (MDI) application's group flyout or moves an existing thumbnail to a new position in the application's group.
ITaskbarList3::SetThumbnailClip Selects a portion of a window's client area to display as that window's thumbnail in the taskbar.
ITaskbarList3::SetThumbnailTooltip Specifies or updates the text of the tooltip that is displayed when the mouse pointer rests on an individual preview thumbnail in a taskbar button flyout.
ITaskbarList3::ThumbBarAddButtons Adds a thumbnail toolbar with a specified set of buttons to the thumbnail image of a window in a taskbar button flyout.
ITaskbarList3::ThumbBarSetImageList Specifies an image list that contains button images for a toolbar embedded in a thumbnail image of a window in a taskbar button flyout.
ITaskbarList3::ThumbBarUpdateButtons Shows, enables, disables, or hides buttons in a thumbnail toolbar as required by the window's current state. A thumbnail toolbar is a toolbar embedded in a thumbnail image of a window in a taskbar button flyout.
ITaskbarList3::UnregisterTab Removes a thumbnail from an application's preview group when that tab or document is closed in the application.

Remarks

This interface also provides the methods of the ITaskbarList and ITaskbarList2 interfaces, from which it inherits.

When to Implement

An implementation of this interface is provided in Windows as CLSID_TaskbarList. This interface is not implemented by third parties.

When to Use

Use the methods of this interface to do the following:

When working with a TDI application (such as Windows Internet Explorer) or a MDI application (such as Microsoft Excel) that is displaying its windows as a group on the taskbar:
- Provide the taskbar with a thumbnail that represents the view of an individual tab or document.
- Remove the thumbnail of an individual tab or document from the group.
- Change the order of thumbnails in the group.
- Set a tab thumbnail as the selected item when the thumbnails are shown.
When applying an overlay to a taskbar icon, such as a notification.
When showing the progress of an operation, such as copying or installing an item.
When adding a toolbar to a thumbnail.

When an application displays a window, its taskbar button is created by the system. When the button is in place, the taskbar sends a TaskbarButtonCreated message to the window. Your application should call RegisterWindowMessage(L"TaskbarButtonCreated") and handle that message in its wndproc. That message must be received by your application before it calls any ITaskbarList3 method.

Note Applications cannot programmatically pin themselves to the taskbar. That functionality is reserved strictly for the user.

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	shobjidl_core.h (include Shobjidl.h)