ITaskbarList3::ThumbBarAddButtons-Methode (shobjidl_core.h)

Fügt der Miniaturansicht eines Fensters in einem Taskleisten-Flyout eine Miniaturansicht mit einer bestimmten Gruppe von Schaltflächen hinzu.

Syntax

HRESULT ThumbBarAddButtons(
  [in] HWND          hwnd,
  [in] UINT          cButtons,
  [in] LPTHUMBBUTTON pButton
);

Die Parameter

[in] hwnd

Typ: HWND-

Das Handle des Fensters, dessen Miniaturansicht die Symbolleiste erhält. Dieses Handle muss zum aufrufenden Prozess gehören.

[in] cButtons

Typ: UINT

Die Anzahl der im Array definierten Schaltflächen, auf die von pButton verwiesen wird. Die maximale Anzahl zulässiger Schaltflächen beträgt 7.

[in] pButton

Typ: LPTHUMBBUTTON

Ein Zeiger auf ein Array von THUMBBUTTON-Strukturen . Jedes THUMBBUTTON definiert eine einzelne Schaltfläche, die der Symbolleiste hinzugefügt werden soll. Schaltflächen können später nicht hinzugefügt oder gelöscht werden, daher muss dies der vollständige definierte Satz sein. Schaltflächen können auch nicht neu angeordnet werden, sodass ihre Reihenfolge im Array, also die Reihenfolge, in der sie von links nach rechts angezeigt werden, ihre dauerhafte Reihenfolge ist.

Rückgabewert

Typ: HRESULT-

Gibt S_OK bei erfolgreicher Ausführung oder andernfalls einen Fehlerwert zurück, einschließlich der folgenden:

Bemerkungen

Mit dieser Methode kann eine Anwendung Schaltflächen für ein aktives Symbolleistensteuerelement definieren, das in die Miniaturansicht eines Fensters eingebettet ist. Dadurch erhalten Sie Zugriff auf die wesentlichen Befehle des Fensters, ohne dass der Benutzer das Fenster wiederherstellen oder aktivieren muss. Beispielsweise bietet Windows Media Player standardmäßige Medientransportsteuerelemente wie Wiedergabe, Pause, Stummschaltung und Beenden.

Die in der Miniaturansicht verwendete Symbolleiste ist im Wesentlichen ein Standardsymbolleisten-Steuerelement . Es verfügt über maximal sieben Schaltflächen, die zentriert, transparent und in einem Bereich unterhalb der Miniaturansicht angezeigt werden, anstatt einen Teil davon abzudecken. Die ID, das Bild, die QuickInfo und der Zustand jeder Schaltfläche werden in einer THUMBBUTTON-Struktur definiert, die dann an die Taskleiste übergeben wird. Anschließend kann die Anwendung Schaltflächen auf der Miniaturansichtssymbolleiste nach Bedarf anzeigen, ändern oder ausblenden, indem sie ITaskbarList3::ThumbBarUpdateButtons aufrufen.

Wenn auf eine Schaltfläche in einer Miniaturansichtssymbolleiste geklickt wird, wird das fenster, das dieser Miniaturansicht zugeordnet ist, eine WM_COMMAND Nachricht gesendet, wobei das HIWORD des wParam-Parameters auf THBN_CLICKED und die LOWORD-Schaltflächen-ID festgelegt ist.

Nachdem eine Symbolleiste zu einer Miniaturansicht hinzugefügt wurde, können Schaltflächen nur über ITaskbarList3::ThumbBarUpdateButtons geändert werden. Während einzelne Schaltflächen nicht hinzugefügt oder entfernt werden können, können sie bei Bedarf über ThumbBarUpdateButtons angezeigt und ausgeblendet werden. Die Symbolleiste selbst kann nicht entfernt werden, ohne das Fenster selbst neu zu erstellen.

Da es einen begrenzten Platz gibt, in dem Miniaturansichten angezeigt werden sollen, sowie eine ständig ändernde Anzahl von Miniaturansichten, die angezeigt werden sollen, werden Anwendungen nicht garantiert eine bestimmte Symbolleistengröße. Wenn der Anzeigebereich niedrig ist, werden die Schaltflächen in der Symbolleiste nach Bedarf von rechts nach links abgeschnitten. Daher sollte eine Anwendung die Befehle priorisieren, die ihren Schaltflächen zugeordnet sind, um sicherzustellen, dass die Befehle mit der höchsten Priorität links liegen und daher am wenigsten abgeschnitten werden.

Miniaturansichtssymbolleisten werden nur angezeigt, wenn Miniaturansichten angezeigt werden. Wenn beispielsweise eine Taskleistenschaltfläche eine Gruppe mit mehr geöffneten Fenstern darstellt, als Platz zum Anzeigen von Miniaturansichten vorhanden ist, wird die Benutzeroberfläche auf ein Legacymenü und nicht auf Miniaturansichten zurückgesetzt.

Accessibility

Informationen zur Barrierefreiheit in Miniaturleisten-Schaltflächenbildern finden Sie im Abschnitt "Hinweise" von ThumbBarSetImageList.

Examples

Das folgende Beispiel zeigt, wie Sie ThumbBarAddButtons verwenden, um eine Symbolleiste hinzuzufügen, die zwei Schaltflächen zu einer Miniaturansicht auf der erweiterten Taskleiste enthält.

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;
}

Anforderungen

Siehe auch

ITaskbarList

ITaskbarList2

ITaskbarList3

ITaskbarList3::ThumbBarSetImageList

ITaskbarList3::ThumbBarUpdateButtons

Taskleistenerweiterungen