Thumbnail Toolbars

Thumbnail toolbars, also known as task toolbars, are a powerful feature of the Windows Shell that allows you to provide immediate access to common actions for a specific item directly within its thumbnail preview. This enhances user experience by enabling quick interactions without the need to open the full application.

Introduction

When a user hovers over a thumbnail preview of a file (e.g., in Windows Explorer or a jump list), a toolbar can appear overlaying the thumbnail, offering a set of buttons that represent actions. Clicking these buttons triggers specific commands associated with the file type or the application that manages it.

Core Concepts

  • Interface: The primary interface for implementing thumbnail toolbars is ITaskbarList3. This interface provides methods to manage the taskbar's appearance, including adding and removing thumbnail toolbars.
  • Buttons: Each button on the thumbnail toolbar is defined by a THUMBBARBUTTON structure. This structure holds information such as the button's icon, tooltip, unique ID, and flags that control its state (e.g., enabled, visible, or dismissed).
  • Event Handling: When a user clicks a button on the thumbnail toolbar, the Shell sends a message (TB_BUTTONCREATED) to your application's window. You need to handle this message to process the button click and execute the corresponding action.

Implementation Steps

1. Implementing ITaskbarList3

Your application must obtain an instance of the ITaskbarList3 interface. This is typically done using CoCreateInstance.


// Example in C++
#include <ShObjIdl.h>

ITaskbarList3 *pTbl = NULL;
HRESULT hr = CoCreateInstance(CLSID_TaskbarList, NULL, CLSCTX_INPROC_SERVER, IID_ITaskbarList3, (void**)&pTbl);
if (SUCCEEDED(hr)) {
    // Use pTbl
}

2. Defining Toolbar Buttons

Create an array of THUMBBARBUTTON structures, each representing a button on your toolbar. You'll need to provide valid HICON handles for the button icons.


// Example defining buttons
THUMBBARBUTTON buttons[2];
ZeroMemory(buttons, sizeof(buttons));

buttons[0].cbSize = sizeof(THUMBBARBUTTON);
buttons[0].lpID = (LPVOID)1; // Unique ID for the button
buttons[0].iBitmap = 0; // Index into a system image list or custom resource
buttons[0].fsState = THUMBBARSTATE_ENABLED;
buttons[0].fsStyle = THUMBBARBUTTONSTYLE_NORMAL;
buttons[0].pszTip = L"Play Video"; // Tooltip text

buttons[1].cbSize = sizeof(THUMBBARBUTTON);
buttons[1].lpID = (LPVOID)2;
buttons[1].iBitmap = 1;
buttons[1].fsState = THUMBBARSTATE_ENABLED;
buttons[1].fsStyle = THUMBBARBUTTONSTYLE_NORMAL;
buttons[1].pszTip = L"Pause Video";

3. Displaying the Toolbar

Use the ITaskbarList3::ThumbBarSetButtons method to add the defined buttons to the thumbnail toolbar for a specific window handle.


// Assuming 'hwnd' is the window handle of your application
if (pTbl) {
    HRESULT hr = pTbl->ThumbBarSetButtons(hwnd, 2, buttons);
    if (SUCCEEDED(hr)) {
        // Toolbar buttons are now visible on hover
    }
}

4. Handling Button Clicks

Your application's main message loop needs to handle the TB_BUTTONCREATED message. The wParam of this message will contain the unique ID of the clicked button.


// Inside your window procedure
case WM_COMMAND:
    if (LOWORD(wParam) == TB_BUTTONCREATED) {
        UINT buttonId = (UINT)lParam; // Or access through THUMBBARBUTTON structure if available
        switch (buttonId) {
            case 1: // Play button clicked
                // Implement Play logic
                break;
            case 2: // Pause button clicked
                // Implement Pause logic
                break;
        }
    }
    break;

Best Practices

  • Clear Icons: Use distinct and easily recognizable icons for your toolbar buttons. Consider using SVG or high-resolution PNGs for scalability.
  • Informative Tooltips: Provide concise and descriptive tooltips for each button to clarify its function.
  • State Management: Update button states (enabled/disabled) dynamically based on the item's current state to guide user interaction.
  • Performance: Ensure that the actions triggered by toolbar buttons are fast and responsive.
  • Accessibility: Follow Windows accessibility guidelines for icons and text labels.
Compatibility Note: Thumbnail toolbars are supported on Windows 7 and later versions. Ensure your application targets the appropriate Windows versions.

Example Scenario: Media Player

A media player application can use a thumbnail toolbar to allow users to play, pause, stop, and seek through media files directly from the taskbar preview. This significantly improves the user experience for media consumption.

Conceptual example of a thumbnail toolbar

Further Reading