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

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

構文

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 パラメーターの HIWORDTHBN_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

こちらもご覧ください

ITaskbarList

ITaskbarList2

ITaskbarList3

ITaskbarList3::ThumbBarSetImageList

ITaskbarList3::ThumbBarUpdateButtons

タスク バーの拡張機能