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 を返し、それ以外の場合は次のようなエラー値を返します。

注釈

このメソッドを使用すると、アプリケーションは、ウィンドウのタスク バーのサムネイル プレビューに埋め込まれているアクティブなツール バー コントロールのボタンを定義できます。 これにより、ユーザーがウィンドウを復元またはアクティブ化することなく、ウィンドウの重要なコマンドにアクセスできます。 たとえば、Windows Media Player では、再生、一時停止、ミュート、停止などの標準的なメディア トランスポート コントロールが提供される場合があります。

サムネイルで使用されるツール バーは、基本的に標準 のツール バー コントロールです 。 最大 7 つのボタンがあり、中央揃え、透明、サムネイルの下の領域に表示され、その一部を覆うのではなく表示されます。 各ボタンの ID、画像、ヒント、および状態は THUMBBUTTON 構造体で定義され、タスク バーに渡されます。 その後、アプリケーションは、 ITaskbarList3::ThumbBarUpdateButtons を呼び出すことによって、現在の状態で必要に応じてサムネイル ツール バーのボタンの表示、変更、非表示を切り替えることができます。

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

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

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

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

Accessibility

サム バー ボタンの画像でのアクセシビリティの詳細については、 ThumbBarSetImageList の「解説」セクションを参照してください。

例示

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

HRESULT AddThumbBarButtons(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;
}

Requirements

こちらも参照ください

ITaskbarList

ITaskbarList2

ITaskbarList3

ITaskbarList3::ThumbBarSetImageList

ITaskbarList3::ThumbBarUpdateButtons

タスク バーの拡張機能