ITaskbarList3::ThumbBarAddButtons メソッド (shobjidl_core.h)

[アーティクル]
08/26/2023

タスクバーボタンポップアップ内のウィンドウのサムネイル画像に、指定したボタンのセットを含むサムネイルツールバーを追加します。

構文

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 を呼び出すことによって、現在の状態で必要に応じてサムネイルツールバーのボタンを表示、変更、または非表示にすることができます。

サムネイルツールバーのボタンをクリックすると、そのサムネイルに関連付けられているウィンドウに、wParam パラメーターの HIWORD が THBN_CLICKED に設定され、LOWORD がボタン ID に設定されたWM_COMMAND メッセージが送信されます。

ツールバーをサムネイルに追加した後は、 ITaskbarList3::ThumbBarUpdateButtons を使用してのみボタンを変更できます。個々のボタンは追加または削除できませんが、必要に応じて ThumbBarUpdateButtons を使用して表示および非表示にできます。ツールバー自体は、ウィンドウ自体を再作成しないと削除できません。

サムネイルを表示する領域が限られているだけでなく、表示するサムネイルの数も絶えず変化するため、アプリケーションでは特定のツールバーサイズが保証されません。表示領域が小さい場合、ツールバーのボタンは、必要に応じて右から左に切り捨てられます。そのため、アプリケーションでは、最も優先度の高いコマンドが左側にあり、切り捨てられる可能性が最も低いことを確認するために、そのボタンに関連付けられているコマンドに優先順位を付ける必要があります。

サムネイルツールバーは、サムネイルが表示されている場合にのみ表示されます。たとえば、タスクバーボタンが、サムネイルを表示するスペースよりもウィンドウが開いているグループを表している場合、UI はサムネイルではなくレガシメニューに戻ります。

例

次の例では、 ThumbBarAddButtons を使用して、拡張タスクバーのサムネイルに 2 つのボタンを含むツールバーを追加する方法を示します。

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