Metodo ITaskbarList3::ThumbBarUpdateButtons (shobjidl_core.h)

Articolo
03/02/2024

Mostra, abilita, disabilita o nasconde i pulsanti in una barra degli strumenti di anteprima, come richiesto dallo stato corrente della finestra. Una barra degli strumenti di anteprima è una barra degli strumenti incorporata in un'immagine di anteprima di una finestra in un riquadro a comparsa del pulsante della barra delle applicazioni.

Sintassi

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

Parametri

[in] hwnd

Tipo: HWND

Handle della finestra la cui rappresentazione di anteprima contiene la barra degli strumenti.

[in] cButtons

Tipo: UINT

Numero di pulsanti definiti nella matrice a cui fa riferimento pButton. Il numero massimo di pulsanti consentiti è 7. Questa matrice contiene solo strutture che rappresentano pulsanti esistenti che vengono aggiornati.

[in] pButton

Tipo: LPTHUMBBUTTON

Puntatore a una matrice di strutture THUMBBUTTON . Ogni THUMBBUTTON definisce un singolo pulsante. Se il pulsante esiste già (il valore iId è già definito), il pulsante esistente viene aggiornato con le informazioni fornite nella struttura.

Valore restituito

Tipo: HRESULT

Se questo metodo ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

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 le anteprime vengono visualizzate sulla barra delle applicazioni. 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 ThumbBarUpdateButtons per modificare il testo e l'immagine in un pulsante esistente in una barra degli strumenti di anteprima sulla barra delle applicazioni estesa.

HRESULT UpdateThumbarButton(HWND hwnd)
{
    // Define a single structure for the button to update. The ID is that
    // of an existing button, so the other information (bitmap index and 
    // tooltip) overwrites the existing values, updating the button.
    THUMBBUTON thbButton;
    thbButton.dwMask = THB_BITMAP | THB_TOOLTIP;
    thbButtons[0].iId = 1;
    thbButton.iBitmap = 3;
    thbButton.pszTip = TEXT("Different Text");
    
    // Create an instance of ITaskbarList3
    ITaskBarList3 *ptbl;
    HRESULT hr = CoCreateInstance(CLSID_TaskbarList, 
                                  NULL, 
                                  CLSCTX_INPROC_SERVER, 
                                  IID_PPV_ARGS(&ptbl);

    if (SUCCEEDED(hr))
    {
        // Update the toolbar. In this case, only the single button is updated.
        hr = ptbl->ThumbBarUpdateButtons(hwnd, 1, &thbButton);
        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