Platforms to show: All Mac Windows Linux Cross-Platform

Back to WindowsTaskbarListMBS class.

WindowsTaskbarListMBS.ActivateTab(WindowHandle as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Activates an item on the taskbar.

The window is not actually activated; the window's item on the taskbar is merely displayed as active.
Lasterror is set.

WindowsTaskbarListMBS.AddTab(WindowHandle as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Adds an item to the taskbar.

Any type of window can be added to the taskbar, but it is recommended that the window at least have the WS_CAPTION style.

Any window added with this method must be removed with the DeleteTab method when the added window is destroyed.

Lasterror is set.

WindowsTaskbarListMBS.DeleteTab(WindowHandle as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Deletes an item from the taskbar.

WindowsTaskbarListMBS.MarkFullscreenWindow(WindowHandle as Integer, Fullscreen as Boolean)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Marks a window as full-screen.

Fullscreen: A Boolean value marking the desired full-screen status of the window.

Setting the value of fFullscreen to TRUE, the Shell treats this window as a full-screen window, and the taskbar is moved to the bottom of the z-order when this window is active. Setting the value of fFullscreen to FALSE removes the full-screen marking, but does not cause the Shell to treat the window as though it were definitely not full-screen. With a FALSEfFullscreen value, the Shell depends on its automatic detection facility to specify how the window should be treated, possibly still flagging the window as full-screen.

Requires Windows XP or Windows Server 2003 or newer.
Lasterror is set.

WindowsTaskbarListMBS.RegisterTab(TabWindowHandle as Integer, MDIWindowHandle as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Informs the taskbar that a new tab or document thumbnail has been provided for display in an application's taskbar group flyout.

Requires Windows 7 or Windows Server 2008 R2 or newer.
Lasterror is set.
By itself, registering a tab thumbnail alone will not result in its being displayed. You must also call SetTabOrder to instruct the group where to display it.

WindowsTaskbarListMBS.SetActiveAlt(WindowHandle as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Marks a taskbar item as active but does not visually activate it.

SetActiveAlt marks the item associated with hwnd as the currently active item for the window's process without changing the pressed state of any item. Any user action that would activate a different tab in that process will activate the tab associated with hwnd instead. The active state of the window's item is not guaranteed to be preserved when the process associated with this window is not active. To ensure that a given tab is always active, call SetActiveAlt whenever any of your windows are activated. Calling SetActiveAlt with a nil window handle clears this state.

WindowsTaskbarListMBS.SetOverlayIcon(TabWindowHandle as Integer, IconHandle as Integer, Description as string)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Applies an overlay to a taskbar button to indicate application status or a notification to the user.

Requires Windows 7 or Windows Server 2008 R2 or newer.
Lasterror is set.

TabWindowHandle:
The handle of the window whose associated taskbar button receives the overlay. This handle must belong to a calling process associated with the button's application and must be a valid HWND or the call is ignored.

IconHandle:
The handle of an icon to use as the overlay. This should be a small icon, measuring 16x16 pixels at 96 dpi. If an overlay icon is already applied to the taskbar button, that existing overlay is replaced.

This value can be 0. How a 0 value is handled depends on whether the taskbar button represents a single window or a group of windows.

  • If the taskbar button represents a single window, the overlay icon is removed from the display.
  • If the taskbar button represents a group of windows and a previous overlay is still available (received earlier than the current overlay, but not yet freed by a 0 value), then that previous overlay is displayed in place of the current overlay.

It is the responsibility of the calling application to free hIcon when it is no longer needed. This can generally be done after you've called SetOverlayIcon because the taskbar makes and uses its own copy of the icon.

Description:
A string that provides an alt text version of the information conveyed by the overlay, for accessibility purposes.


In versions of Windows earlier than Windows 7, applications often used icons in the notification area of the taskbar to display application status and notifications to the user. The Windows 7 taskbar allows an application to provide that same sort of user feedback through its taskbar button, centralizing more of the application information in one place. These overlays are similar to existing overlays used for shortcut icons or security notifications, displayed at the lower-right corner of the button.

The following illustration shows an overlay (the small, green square that indicates the user status as "Available") applied to the far-right taskbar button.

Windows Messenger taskbar button with an overlay to indicate an Available status.

Icon overlays serve as a contextual notification of status, and are intended to negate the need for a separate notification area status icon to communicate that information to the user. The application designer must decide during the development cycle which method—icon overlay or notification area status icon—best serves that application. Overlay icons are intended to supply important, long-standing status or notifications such as network status, messenger status, or new mail. They should not be frequently changed, nor should they be animated.

To display an overlay icon, the taskbar must be in the default large icon mode. If the taskbar is configured through Taskbar and Start Menu Properties to show small icons, overlays cannot be applied and calls to this method are ignored.

Because a single overlay is applied to the taskbar button instead of to the individual window thumbnails, this is a per-group feature rather than per-window. Requests for overlay icons can be received from individual windows in a taskbar group, but they do not queue. The last overlay received is the overlay shown. If the last overlay received is removed, the overlay that it replaced is restored so long as it is still active. As an example, windows 1, 2, and 3 set, in order, overlays A, B, and C. Because overlay C was received last, it is shown on the taskbar button. Window 2 calls SetOverlayIcon with a 0 value to remove overlay B. Window 3 then does the same to remove overlay C. Because window 1's overlay A is still active, that overlay is then displayed on the taskbar button.

If Windows Explorer shuts down unexpectedly, overlays are not restored when Windows Explorer is restored. The application should wait to receive the TaskbarButtonCreated message that indicates that Windows Explorer has restarted and the taskbar button has been re-created, and then call SetOverlayIcon again to reapply the overlay.

WindowsTaskbarListMBS.SetProgressState(WindowHandle as Integer, Flags as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Sets the type and state of the progress indicator displayed on a taskbar button.

Use the ProgressStateFlag* constants. Flags that control the current state of the progress button. Specify only one of the following flags; all states are mutually exclusive of all others.

Requires Windows 7 or Windows Server 2008 R2 or newer.
Lasterror is set.

Progress bar information is not shown in high contrast color schemes to guarantee that no accessibility needs are compromised.

Developers accustomed to the existing progress bar control should find the taskbar button progress indicator to be a similar experience both in concept and visuals. Here, the taskbar button itself becomes a progress bar. A taskbar button's progress indicator should be a reflection of a more detailed progress bar in the associated window. This allows the user to see specifics, such as the percentage number and the amount of time remaining, that cannot be shown in a taskbar button. Also, because a taskbar button can show the progress of only a single window in a group, it allows the user to check the progress of individual windows. It also provides progress information to the user when the taskbar button cannot, such as in a high-contrast color scheme.

Note that a taskbar button progress bar is not intended for use with normally peripheral actions such as the loading of a Web page or the printing of a document. That type of progress should continue to be shown in a window's status bar.

The progress indicator is displayed between the taskbar button's icon or text and the background. If progress is shown for both the active taskbar button and an inactive button, shading in the respective progress bars is such that the active button is still obvious to the user. Also, button functionality such as the display of thumbnails continues to work normally when the button is being used to display progress.

When exiting an error or paused state, call this method again with the ProgressStateFlagNormal or ProgressStateFlagIndeterminate flag to continue in the original state or TBPF_NOPROGRESS if the operation is cancelled.

How the Taskbar Button Chooses the Progress Indicator for a Group

The taskbar button can show a progress indicator for only one window at a time. This includes the situation where the taskbar button represents a group and more than one window in that group is broadcasting progress information. In that case, the taskbar button chooses its progress display based on state priority. State priority is shown in the following table with priority 1 being the highest.

PriorityState
1ProgressStateFlagError
2ProgressStateFlagPaused
3ProgressStateFlagNormal
4ProgressStateFlagIndeterminate

Changing a window's state changes its priority in relation to other windows in the group which in turn might change which window in a group is used for the progress indicator in the taskbar button.

In the case of a priority collision between two windows that are broadcasting determinate progress, the window with the least progress is used.

Based on this priority, the indeterminate progress indicator can be displayed in the taskbar button only in these cases:

  • The taskbar button does not represent a group and the single window that it represents has set ProgressStateFlagIndeterminate.
  • The taskbar button represents a group, only one window in that group is broadcasting progress information, and that window has set ProgressStateFlagIndeterminate.
  • The taskbar button represents a group, multiple windows in that group are broadcasting progress information, and all of those windows have set ProgressStateFlagIndeterminate.

A determinate progress indicator can be displayed in these cases:

  • The taskbar button does not represent a group and the single window that it represents is broadcasting determinate progress information.
  • The taskbar button represents a group, only one window in that group is broadcasting progress information, and that window is broadcasting determinate progress information.
  • The taskbar button represents a group, multiple windows in that group are broadcasting progress information, at least one of those windows is broadcasting determinate progress information, and no window has set ProgressStateFlagError or ProgressStateFlagPaused.

Note that a call to SetProgressValue will switch a progress indicator currently in an indeterminate mode (ProgressStateFlagIndeterminate) to a normal (determinate) display and clear the ProgressStateFlagIndeterminate flag.

If the handle is a ptr, you need to cast it with Integer(YourPtr) to pass it.

Some examples using this method:

WindowsTaskbarListMBS.SetProgressValue(WindowHandle as Integer, Completed as UInt64, Total as UInt64)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Displays or updates a progress bar hosted in a taskbar button to show the specific percentage completed of the full operation.

Completed: An application-defined value that indicates the proportion of the operation that has been completed at the time the method is called.
Total: An application-defined value that specifies the value ullCompleted will have when the operation is complete.

Requires Windows 7 or Windows Server 2008 R2 or newer.
Lasterror is set.

Determinate Progress Bar Lifecycle

An application first calls SetProgressValue to begin the display of a determinate progress bar, and then calls it again as needed to update the bar as the progress changes. When progress is complete, the application must call SetProgressState with the TBPF_NOPROGRESS flag to dismiss the progress bar.

How the Taskbar Button Chooses the Progress Indicator for a Group

The taskbar button can show a progress indicator for only one window at a time. When the taskbar button represents a group and more than one of the windows in that group are broadcasting progress information, the taskbar button chooses its progress display based on the following state priority.

PriorityState
1ProgressStateFlagError
2ProgressStateFlagPaused
3ProgressStateFlagNormal
4ProgressStateFlagIndeterminate

Unless SetProgressState has set a blocking state (ProgressStateFlagError or ProgressStateFlagPaused) for the window, a call to SetProgressValue assumes the ProgressStateFlagNormal state even if it is not explicitly set. A call to SetProgressValue overrides and clears the ProgressStateFlagIndeterminate state.

In the case of a priority collision where two windows are broadcasting determinate progress, the window with the least progress is used.

Based on that priority, this determinate (specific percentage) progress indicator can be displayed in these cases:

  • The taskbar button does not represent a group and the single window that it represents is broadcasting determinate progress information through this method.
  • The taskbar button represents a group, only one window in that group is broadcasting progress information, and that window is broadcasting determinate progress information through this method.
  • The taskbar button represents a group, multiple windows in that group are broadcasting progress information, at least one of those windows is broadcasting progress information through this method, and none of those windows has set the ProgressStateFlagError or ProgressStateFlagPaused state.

If a window in the group has set ProgressStateFlagError or ProgressStateFlagPaused, that state will be used for the button display. However, you can still make calls to SetProgressValue on other, unblocked windows in the group to update their progress in the background.

If the handle is a ptr, you need to cast it with Integer(YourPtr) to pass it.

Some examples using this method:

WindowsTaskbarListMBS.SetTabActive(TabWindowHandle as Integer, MDIWindowHandle as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Informs the taskbar that a tab or document window has been made the active window.

Requires Windows 7 or Windows Server 2008 R2 or newer.
Lasterror is set.

TabWindowHandle: Handle of the active tab window. This handle must already be registered through RegisterTab. This value can be 0 if no tab is active.

MDIWindowHandle: Handle of the application's main window. This value tells the taskbar which group the thumbnail is a member of. This value is required and cannot be 0.

WindowsTaskbarListMBS.SetTabOrder(TabWindowHandle as Integer, InsertBeforeWindowHandle as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
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.

TabWindowHandle: The handle of the tab window whose thumbnail is being placed. This value is required, must already be registered through RegisterTab, and cannot be 0.
InsertBeforeWindowHandle: The handle of the tab window whose thumbnail that hwndTab is inserted to the left of. This handle must already be registered through RegisterTab. If this value is 0, the new thumbnail is added to the end of the list.

WindowsTaskbarListMBS.SetTabProperties(TabWindowHandle as Integer, flags as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Allows a tab to specify whether the main application frame window or the tab window should be used as a thumbnail or in the peek feature under certain circumstances.

An application might want to use the thumbnail or peek representation of its associated parent window if the application cannot generate its own thumbnail for a tab or for its active tab content (such as an animation) to appear live.

flags: One of the TabPropertyFlag* constants.
Available on Windows 7 or Windows Server 2008 R2 or newer.

WindowsTaskbarListMBS.SetThumbnailClip(TabWindowHandle as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Selects a portion of a window's client area to display as that window's thumbnail in the taskbar.

This variant of the method clears the clip that is already in place and return to the default display of the thumbnail.

Requires Windows 7 or Windows Server 2008 R2 or newer.
Lasterror is set.

See also:

WindowsTaskbarListMBS.SetThumbnailClip(TabWindowHandle as Integer, x as Integer, y as Integer, w as Integer, h as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Selects a portion of a window's client area to display as that window's thumbnail in the taskbar.

Requires Windows 7 or Windows Server 2008 R2 or newer.
Lasterror is set.

See also:

WindowsTaskbarListMBS.SetThumbnailTooltip(TabWindowHandle as Integer, tip as string)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
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.

Requires Windows 7 or Windows Server 2008 R2 or newer.
Lasterror is set.

TabWindowHandle: The handle to the window whose thumbnail displays the tooltip. This handle must belong to the calling process.

tip: The text to be displayed in the tooltip. This value can be empty, in which case the title of the window specified by WindowHandle is used as the tooltip.

WindowsTaskbarListMBS.UnregisterTab(TabWindowHandle as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows MBS Win Plugin 10.2 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Removes a thumbnail from an application's preview group when that tab or document is closed in the application.

It is the responsibility of the calling application to free hwndTab through DestroyWindow. UnregisterTab must be called before the handle is freed.
Requires Windows 7 or Windows Server 2008 R2 or newer.
Lasterror is set.

The items on this page are in the following plugins: MBS Win Plugin.


The biggest plugin in space...