ITaskbarList3：：ThumbBarAddButtons 方法 (shobjidl_core.h)

项目
03/02/2024

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

语法

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 ，否则返回错误值，包括：

返回代码	说明
E_INVALIDARG	hwnd 参数不指定属于进程的句柄，也不指定与任务栏按钮关联的窗口。如果 pButton 小于 1 或大于 7，也会返回此值。

注解

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

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

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

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

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

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

示例

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

HRESULT AddThumbarButtons(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;
}

要求

要求	值
最低受支持的客户端	Windows 7 [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 R2 [仅限桌面应用]
目标平台	Windows
标头	shobjidl_core.h (包括 Shobjidl.h)
Library	Explorerframe.lib
DLL	Explorerframe.dll