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

Article
03/02/2024

Ajoute une barre d’outils de miniatures avec un ensemble spécifié de boutons à l’image miniature d’une fenêtre dans un menu volant de bouton de la barre des tâches.

Syntaxe

HRESULT ThumbBarAddButtons(
  [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 recevra la barre d’outils. Ce handle doit appartenir au processus appelant.

[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.

[in] pButton

Type : LPTHUMBBUTTON

Pointeur vers un tableau de structures THUMBBUTTON . Chaque bouton THUMBBUTTON définit un bouton individuel à ajouter à la barre d’outils. Les boutons ne pouvant pas être ajoutés ou supprimés ultérieurement, il doit s’agir de l’ensemble défini complet. Les boutons ne peuvent pas non plus être réorganisés, de sorte que leur ordre dans le tableau, qui est l’ordre dans lequel ils sont affichés de gauche à droite, sera leur ordre permanent.

Valeur retournée

Type : HRESULT

Retourne S_OK en cas de réussite, ou une valeur d’erreur dans le cas contraire, y compris les éléments suivants :

Code de retour	Description
E_INVALIDARG	Le paramètre hwnd ne spécifie pas de handle qui appartient au processus ou ne spécifie pas de fenêtre associée à un bouton de barre des tâches. Cette valeur est également retournée si pButton est inférieur à 1 ou supérieur à 7.

Remarques

Cette méthode permet à une application de définir des boutons pour un contrôle de barre d’outils actif incorporé dans l’aperçu miniature de la barre des tâches d’une fenêtre. Cela permet d’accéder aux commandes essentielles de la fenêtre sans que l’utilisateur restaure ou active la fenêtre. Par exemple, Lecteur multimédia Windows peuvent proposer des contrôles de transport de média standard, tels que la lecture, la pause, le son et l’arrêt.

La barre d’outils utilisée dans la miniature est essentiellement un contrôle de barre d’outils standard. Il a un maximum de sept boutons, et il est aligné sur le centre, transparent et affiché dans une zone sous la miniature au lieu de couvrir n’importe quelle partie de celle-ci. L’ID, l’image, l’info-bulle et l’état de chaque bouton sont définis dans une structure THUMBBUTTON , qui est ensuite passée à la barre des tâches. L’application peut ensuite afficher, modifier ou masquer les boutons de la barre d’outils miniatures en fonction de son état actuel en appelant ITaskbarList3 ::ThumbBarUpdateButtons.

Lorsque l’utilisateur clique sur un bouton dans une barre d’outils de miniatures, la fenêtre associée à cette miniature reçoit un message WM_COMMAND avec hiword de son paramètre wParam défini sur THBN_CLICKED et loWORD sur l’ID de bouton.

Une fois qu’une barre d’outils a été ajoutée à une miniature, les boutons peuvent être modifiés uniquement via ITaskbarList3 ::ThumbBarUpdateButtons. Bien que des boutons individuels ne puissent pas être ajoutés ou supprimés, ils peuvent être affichés et masqués via ThumbBarUpdateButtons si nécessaire. La barre d’outils elle-même ne peut pas être supprimée sans recréer la fenêtre elle-même.

É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. 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 ThumbBarAddButtons pour ajouter une barre d’outils contenant deux boutons à une miniature de la barre des tâches étendue.

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

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