Méthode ITaskbarList3 ::ThumbBarUpdateButtons (shobjidl_core.h)

Article
03/02/2024

Affiche, active, désactive ou masque les boutons dans une barre d’outils miniatures en fonction de l’état actuel de la fenêtre. Une barre d’outils de miniatures est une barre d’outils incorporée dans une image miniature d’une fenêtre dans un menu volant de bouton de barre des tâches.

Syntaxe

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

Paramètres

[in] hwnd

Type : HWND

Handle de la fenêtre dont la représentation miniature contient la barre d’outils.

[in] cButtons

Type : UINT

Nombre de boutons définis dans le tableau pointé par pButton. Le nombre maximal de boutons autorisés est de 7. Ce tableau contient uniquement des structures qui représentent des boutons existants en cours de mise à jour.

[in] pButton

Type : LPTHUMBBUTTON

Pointeur vers un tableau de structures THUMBBUTTON . Chaque bouton THUMBBUTTON définit un bouton individuel. Si le bouton existe déjà (la valeur iId est déjà définie), ce bouton existant est mis à jour avec les informations fournies dans la structure.

Valeur retournée

Type : HRESULT

Si cette méthode réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Étant donné qu’il existe une quantité limitée d’espace dans laquelle afficher les miniatures, ainsi qu’un nombre en constante évolution de miniatures à afficher, les applications ne sont pas garanties d’une taille de barre d’outils spécifique. Si l’espace d’affichage est faible, les boutons de la barre d’outils sont tronqués de droite à gauche en fonction des besoins. Par conséquent, une application doit hiérarchiser les commandes associées à ses boutons pour s’assurer que celles de priorité la plus élevée se trouvent à gauche et sont donc moins susceptibles d’être tronquées.

Les barres d’outils de miniatures sont affichées uniquement lorsque des miniatures sont affichées dans la barre des tâches. Par instance, si un bouton de barre des tâches représente un groupe avec plus de fenêtres ouvertes qu’il n’y a de place pour afficher des miniatures, l’interface utilisateur revient à un menu hérité plutôt qu’à des miniatures.

Exemples

L’exemple suivant montre comment utiliser ThumbBarUpdateButtons pour modifier le texte et l’image d’un bouton existant dans une barre d’outils miniatures de la barre d’outils étendue.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shobjidl_core.h (incluez Shobjidl.h)
Bibliothèque	Explorerframe.lib
DLL	Explorerframe.dll