ITaskbarList3：：ThumbBarUpdateButtons 方法 (shobjidl_core.h)

项目
08/26/2023

根据窗口当前状态的要求，在缩略图工具栏中显示、启用、禁用或隐藏按钮。缩略图工具栏是嵌入任务栏按钮浮出控件中窗口缩略图中的工具栏。

语法

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

参数

[in] hwnd

类型：HWND

其缩略图表示包含工具栏的窗口的句柄。

[in] cButtons

类型： UINT

pButton 指向的数组中定义的按钮数。允许的最大按钮数为 7。此数组仅包含表示正在更新的现有按钮的结构。

[in] pButton

类型： LPTHUMBBUTTON

指向 THUMBBUTTON 结构数组的指针。每个 THUMBBUTTON 定义单个按钮。如果按钮已存在 (iId 值已在) 定义，则使用结构中提供的信息更新该现有按钮。

返回值

类型： HRESULT

如果该方法成功，则返回 S_OK。否则，将返回 HRESULT 错误代码。

注解

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

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

示例

以下示例演示如何使用 ThumbBarUpdateButtons 更改扩展任务栏上缩略图工具栏中现有按钮上的文本和图像。

HRESULT UpdateThumbarButton(HWND hwnd)
{
    // Define a single structure for the button to update. The ID is that
    // of an existing button, so the other information (bitmap index and 
    // tooltip) overwrites the existing values, updating the button.
    THUMBBUTON thbButton;
    thbButton.dwMask = THB_BITMAP | THB_TOOLTIP;
    thbButtons[0].iId = 1;
    thbButton.iBitmap = 3;
    thbButton.pszTip = TEXT("Different Text");
    
    // Create an instance of ITaskbarList3
    ITaskBarList3 *ptbl;
    HRESULT hr = CoCreateInstance(CLSID_TaskbarList, 
                                  NULL, 
                                  CLSCTX_INPROC_SERVER, 
                                  IID_PPV_ARGS(&ptbl);

    if (SUCCEEDED(hr))
    {
        // Update the toolbar. In this case, only the single button is updated.
        hr = ptbl->ThumbBarUpdateButtons(hwnd, 1, &thbButton);
        ptbl->Release();
    }
    return hr;
}

要求

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