ITaskbarList3：：ThumbBarAddButtons 方法（shobjidl_core.h）

将具有指定按钮集的缩略图工具栏添加到任务栏按钮浮出控件中窗口的缩略图图像。

Syntax

HRESULT ThumbBarAddButtons(
  [in] HWND          hwnd,
  [in] UINT          cButtons,
  [in] LPTHUMBBUTTON pButton
);

参数

[in] hwnd

类型：HWND

其缩略图表示形式将接收工具栏的窗口的句柄。 此句柄必须属于调用进程。

[in] cButtons

类型： UINT

pButton 指向的数组中定义的按钮数。 允许的最大按钮数为 7。

[in] pButton

类型： LPTHUMBBUTTON

指向 THUMBBUTTON 结构的数组的指针。 每个 THUMBBUTTON 定义要添加到工具栏中的单个按钮。 以后无法添加或删除按钮，因此必须是完整的定义集。 按钮也不能重新排序，因此它们在数组中的顺序（即它们从左到右显示的顺序）将是其永久顺序。

返回值

类型：HRESULT

如果成功，则返回 S_OK ;否则返回错误值，包括以下内容：

注解

此方法允许应用程序为嵌入在窗口的任务栏缩略图预览中的活动工具栏控件定义按钮。 这样即可访问窗口的基本命令，而无需用户还原或激活窗口。 例如，Windows Media Player 可能提供标准媒体传输控件，例如播放、暂停、静音和停止。

缩略图中使用的工具栏实质上是标准 工具栏 控件。 它最多有七个按钮，它居中对齐、透明，并显示在缩略图下方的区域，而不是覆盖其任何部分。 每个按钮的 ID、图像、工具提示和状态都在 THUMBBUTTON 结构中定义，然后传递给任务栏。 然后，应用程序可以通过调用 ITaskbarList3：：ThumbBarUpdateButtons，根据需要从缩略图工具栏中显示、更改或隐藏按钮。

单击缩略图工具栏中的按钮时，与该缩略图关联的窗口将发送一条WM_COMMAND消息，其中 wParam 参数的 HIWORD 设置为THBN_CLICKED，LOWORD 设置为按钮 ID。

将工具栏添加到缩略图后，只能通过 ITaskbarList3：：ThumbBarUpdateButtons 更改按钮。 虽然无法添加或删除单个按钮，但可以根据需要通过 ThumbBarUpdateButton 显示和隐藏它们。 如果不重新创建窗口本身，则无法删除工具栏本身。

由于显示缩略图的空间有限，以及要显示的缩略图数量不断变化，因此应用程序不能保证特定的工具栏大小。 如果显示空间较低，工具栏中的按钮会根据需要从右到左截断。 因此，应用程序应确定与其按钮关联的命令的优先级，以确保优先级最高的命令位于左侧，因此不太可能被截断。

仅当显示缩略图时，才会显示缩略图工具栏。 例如，如果任务栏按钮表示一个窗口比显示缩略图空间更大的组，UI 将还原为旧菜单而不是缩略图。

Accessibility

有关拇指栏按钮图像中的辅助功能的信息，请参阅 ThumbBarSetImageList 的“备注”部分。

例子

以下示例演示如何使用 ThumbBarAddButtons 将包含两个按钮的工具栏添加到扩展任务栏上的缩略图。

HRESULT AddThumbBarButtons(HWND hwnd, HIMAGELIST himl, HIMAGELIST himlHot)
{
    // Define an array of two buttons. These buttons provide images through an 
    // image list and also provide tooltips.
    DWORD dwMask = THB_BITMAP | THB_TOOLTIP | THB_FLAGS;
    
    THUMBBUTTON thbButtons[2];
    thbButtons[0].dwMask = dwMask;
    thbButtons[0].iId = 0;
    thbButtons[0].iBitmap = 0;
    thbButtons[0].pszTip = TEXT("Button 1");
    thbButtons[0].dwFlags = THBF_DISMISSONCLICK;

    dwMask = THB_BITMAP | THB_TOOLTIP;
    thbButtons[1].dwMask = dwMask;
    thbButtons[1].iId = 1;
    thbButtons[1].iBitmap = 1;
    thbButtons[1].pszTip = TEXT("Button 2");
    
    // Create an instance of ITaskbarList3
    ITaskBarList3 *ptbl;
    HRESULT hr = CoCreateInstance(CLSID_TaskbarList, 
                                  NULL, 
                                  CLSCTX_INPROC_SERVER, 
                                  IID_PPV_ARGS(&ptbl);

    if (SUCCEEDED(hr))
    {
        // Declare the image list that contains the button images.
        hr = ptbl->ThumbBarSetImageList(hwnd, himl);

        if (SUCCEEDED(hr))
        {
            // Attach the toolbar to the thumbnail.
            hr = ptbl->ThumbBarAddButtons(hwnd, ARRAYSIZE(thbButtons), &thbButtons);
        }
        ptbl->Release();
    }
    return hr;
}

要求

另请参阅

ITaskbarList

ITaskbarList2

ITaskbarList3

ITaskbarList3：：ThumbBarSetImageList

ITaskbarList3：：ThumbBarUpdateButtons

任务栏扩展