ITaskbarList3：：ThumbBarUpdateButtons 方法 (shobjidl_core.h)

發行項
03/05/2024

顯示、啟用、停用或隱藏視窗目前狀態所需的縮圖工具列中的按鈕。縮圖工具列是在任務欄按鈕飛出視窗的縮圖影像中內嵌的工具列。

語法

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)
程式庫	Explorerframe.lib
Dll	Explorerframe.dll