Metodo ITaskbarList3::ThumbBarAddButtons (shobjidl_core.h)

Articolo
03/02/2024

Aggiunge una barra degli strumenti di anteprima con un set specificato di pulsanti all'immagine di anteprima di una finestra in un riquadro a comparsa della barra delle applicazioni.

Sintassi

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

Parametri

[in] hwnd

Tipo: HWND

Handle della finestra la cui rappresentazione di anteprima riceverà la barra degli strumenti. Questo handle deve appartenere al processo di chiamata.

[in] cButtons

Tipo: UINT

Numero di pulsanti definiti nella matrice a cui fa riferimento pButton. Il numero massimo di pulsanti consentiti è 7.

[in] pButton

Tipo: LPTHUMBBUTTON

Puntatore a una matrice di strutture THUMBBUTTON . Ogni THUMBBUTTON definisce un singolo pulsante da aggiungere alla barra degli strumenti. I pulsanti non possono essere aggiunti o eliminati in un secondo momento, quindi questo deve essere il set completo definito. I pulsanti non possono essere riordinati, quindi l'ordine nella matrice, ovvero l'ordine in cui vengono visualizzati a destra, sarà il loro ordine permanente.

Valore restituito

Tipo: HRESULT

Restituisce S_OK se ha esito positivo o un valore di errore in caso contrario, incluso quanto segue:

Codice restituito	Descrizione
E_INVALIDARG	Il parametro hwnd non specifica un handle che appartiene al processo o non specifica una finestra associata a un pulsante della barra delle applicazioni. Questo valore viene restituito anche se pButton è minore di 1 o maggiore di 7.

Commenti

Questo metodo consente a un'applicazione di definire pulsanti per un controllo della barra degli strumenti attivo incorporato nell'anteprima della barra delle applicazioni di una finestra. In questo modo viene fornito l'accesso ai comandi essenziali della finestra senza eseguire il ripristino dell'utente o attivare la finestra. Ad esempio, Lettore multimediale Windows può offrire controlli di trasporto multimediali standard, ad esempio riprodurre, sospendere, disattivare e arrestare.

La barra degli strumenti usata nell'anteprima è essenzialmente un controllo della barra degli strumenti standard. Ha un massimo di sette pulsanti ed è allineato al centro, trasparente e visualizzato in un'area sotto l'anteprima anziché coprire qualsiasi parte di esso. L'ID, l'immagine, la descrizione comando e lo stato di ogni pulsante vengono definiti in una struttura THUMBBUTTON , che viene quindi passata alla barra delle applicazioni. L'applicazione può quindi visualizzare, modificare o nascondere i pulsanti dalla barra degli strumenti di anteprima, come richiesto dallo stato corrente chiamando ITaskbarList3::ThumbBarUpdateButtons.

Quando viene fatto clic su un pulsante in una barra degli strumenti di anteprima, la finestra associata a tale anteprima viene inviata una WM_COMMAND messaggio con hiWORD del parametro wParam impostato su THBN_CLICKED e loWORD sull'ID pulsante.

Dopo l'aggiunta di una barra degli strumenti a un'anteprima, i pulsanti possono essere modificati solo tramite ITaskbarList3::ThumbBarUpdateButtons. Anche se i singoli pulsanti non possono essere aggiunti o rimossi, possono essere visualizzati e nascosti tramite ThumbBarUpdateButtons in base alle esigenze. La barra degli strumenti stessa non può essere rimossa senza creare nuovamente la finestra stessa.

Poiché esiste una quantità limitata di spazio in cui visualizzare le anteprime, nonché un numero costante di anteprime da visualizzare, le applicazioni non garantiscono una dimensione specifica della barra degli strumenti. Se lo spazio visualizzato è basso, i pulsanti nella barra degli strumenti vengono troncati da destra a sinistra in base alle esigenze. Pertanto, un'applicazione deve definire la priorità dei comandi associati ai relativi pulsanti per garantire che quelli di priorità più alta siano a sinistra e quindi meno probabile che vengano troncati.

Le barre degli strumenti di anteprima vengono visualizzate solo quando vengono visualizzate le anteprime. Ad esempio, se un pulsante della barra delle applicazioni rappresenta un gruppo con finestre più aperte rispetto alle anteprime per visualizzare le anteprime, l'interfaccia utente esegue il ripristino di un menu legacy anziché le anteprime.

Esempio

Nell'esempio seguente viene illustrato come usare ThumbBarAddButtons per aggiungere una barra degli strumenti contenente due pulsanti a un'anteprima sulla barra delle applicazioni estesa.

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shobjidl_core.h (include Shobjidl.h)
Libreria	Explorerframe.lib
DLL	Explorerframe.dll