ITaskbarList3::ThumbBarAddButtons-Methode (shobjidl_core.h)

Artikel
08/26/2023

Fügt dem Miniaturansichtsbild eines Fensters in einem Taskleistenschaltflächen-Flyout eine Miniaturansicht mit einem angegebenen Satz von Schaltflächen hinzu.

Syntax

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

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 von Schaltflächen, die im Array definiert sind, auf das von pButton verwiesen wird. Die maximal zulässige Anzahl von Schaltflächen ist 7.

[in] pButton

Typ: LPTHUMBBUTTON

Ein Zeiger auf ein Array von THUMBBUTTON-Strukturen . Jeder 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 es sich um den vollständig definierten Satz handelt. Schaltflächen können auch nicht neu sortiert werden, sodass ihre Reihenfolge im Array, also die Reihenfolge, in der sie von links nach rechts angezeigt werden, ihre permanente Reihenfolge ist.

Rückgabewert

Typ: HRESULT

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

Rückgabecode	Beschreibung
E_INVALIDARG	Der hwnd-Parameter gibt kein Handle an, das zum Prozess gehört, oder gibt kein Fenster an, das einer Taskleistenschaltfläche zugeordnet ist. Dieser Wert wird auch zurückgegeben, wenn pButton kleiner als 1 oder größer als 7 ist.

Hinweise

Mit dieser Methode kann eine Anwendung Schaltflächen für ein aktives Symbolleistensteuerelement definieren, das in die Miniaturansicht der Taskleiste eines Fensters eingebettet ist. Dadurch erhalten Sie Zugriff auf die wichtigsten Befehle des Fensters, ohne dass der Benutzer das Fenster wiederherstellen oder aktivieren muss. Beispielsweise können Windows Medienwiedergabe Standardsteuerelemente für den Medientransport wie Wiedergabe, Anhalten, Stummschalten und Beenden bieten.

Die in der Miniaturansicht verwendete Symbolleiste ist im Wesentlichen ein Standardmäßiges Symbolleistensteuerelement . Es verfügt über maximal sieben Schaltflächen, und es ist mittig ausgerichtet, transparent und in einem Bereich unter der Miniaturansicht angezeigt, 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 in der Miniaturansichtssymbolleiste nach Bedarf anzeigen, ändern oder ausblenden, indem sie ITaskbarList3::ThumbBarUpdateButtons aufruft.

Wenn auf eine Schaltfläche in einer Miniaturansichtssymbolleiste geklickt wird, wird dem dieser Miniaturansicht zugeordneten Fenster eine WM_COMMAND Nachricht gesendet, wobei der HIWORD-Parameter des wParam-Parameters auf THBN_CLICKED und der LOWORD an die Schaltflächen-ID festgelegt ist.

Nachdem einer Miniaturansicht eine Symbolleiste 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 nach 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 Speicherplatz für die Anzeige von Miniaturansichten sowie eine sich ständig ändernde Anzahl von Miniaturansichten gibt, die angezeigt werden sollen, ist für Anwendungen keine bestimmte Symbolleistengröße garantiert. Wenn der Anzeigeraum gering 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 für instance eine Taskleistenschaltfläche eine Gruppe mit mehr geöffneten Fenstern darstellt, als es Platz zum Anzeigen von Miniaturansichten gibt, wird die Benutzeroberfläche zu einem Legacymenü und nicht zu Miniaturansichten zurückgesetzt.

Beispiele

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

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shobjidl_core.h (einschließlich Shobjidl.h)
Bibliothek	Explorerframe.lib
DLL	Explorerframe.dll