ITaskbarList3：：ThumbBarAddButtons 方法 (shobjidl_core.h)

發行項
03/05/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 ，否則傳回錯誤值，包括下列專案：

傳回碼	Description
E_INVALIDARG	hwnd 參數不會指定屬於進程的句柄，或未指定與任務欄按鈕相關聯的視窗。如果 pButton 小於 1 或大於 7，也會傳回此值。

備註

這個方法可讓應用程式定義內嵌在視窗任務列縮圖預覽的作用中工具列控件按鈕。這可讓您存取視窗的基本命令，而不需要讓使用者還原或啟用視窗。例如，Windows 媒體播放器可能會提供標準媒體傳輸控制件，例如播放、暫停、靜音和停止。

縮圖中使用的工具列基本上是標準工具列控件。它最多有七個按鈕，而且是置中對齊、透明且顯示在縮圖下方的區域，而不是涵蓋其任何部分。每個按鈕的標識碼、影像、工具提示和狀態都會定義在 THUMBBUTTON 結構中，然後傳遞給任務列。接著，應用程式可以呼叫 ITaskbarList3：：ThumbBarUpdateButtons，從縮圖工具列顯示、改變或隱藏其目前狀態所需的按鈕。

按兩下縮圖工具列中的按鈕時，與該縮圖相關聯的視窗會傳送WM_COMMAND訊息，其中其 wParam 參數的 HIWORD 設定為 THBN_CLICKED，並將 LOWORD 傳送至按鈕標識符。

將工具列新增至縮圖之後，只能透過 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)
程式庫	Explorerframe.lib
Dll	Explorerframe.dll