THUMBBUTTON structure (shobjidl_core.h)

Article
09/01/2022

Used by methods of the ITaskbarList3 interface to define buttons used in a toolbar embedded in a window's thumbnail representation.

Syntax

typedef struct THUMBBUTTON {
  THUMBBUTTONMASK  dwMask;
  UINT             iId;
  UINT             iBitmap;
  HICON            hIcon;
  WCHAR            szTip[260];
  THUMBBUTTONFLAGS dwFlags;
} THUMBBUTTON, *LPTHUMBBUTTON;

Members

dwMask

Type: THUMBBUTTONMASK

A combination of THUMBBUTTONMASK values that specify which members of this structure contain valid data; other members are ignored, with the exception of iId, which is always required.

iId

Type: UINT

The application-defined identifier of the button, unique within the toolbar.

iBitmap

Type: UINT

The zero-based index of the button image within the image list set through ITaskbarList3::ThumbBarSetImageList.

hIcon

Type: HICON

The handle of an icon to use as the button image.

szTip[260]

Type: WCHAR[260]

A wide character array that contains the text of the button's tooltip, displayed when the mouse pointer hovers over the button.

dwFlags

Type: THUMBBUTTONFLAGS

A combination of THUMBBUTTONFLAGS values that control specific states and behaviors of the button.

Remarks

When a button is clicked, a WM_COMMAND message that contains the button ID is sent to the associated application window. The application handles whatever action it has assigned to the button.

Button Images

When using an icon, specified through the hIcon member, the taskbar makes its own copy of the icon. It is the caller's responsibility to free the handle it passed in hIcon when it is no longer needed.

If both an icon and an image list are specified for a button's image, the icon is used if possible. If for some reason the attempt to retrieve the icon fails, the image from the image list is used.

Applications must provide these button images:

The button in its default active state.
Images suitable for use with high-dpi (dots per inch) displays.

Images must be 32-bit and of dimensions GetSystemMetrics(SM_CXICON) x GetSystemMetrics(SM_CYICON). The toolbar itself provides visuals for a button's clicked, disabled, and hover states.

Requirements

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