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

Ajoute une barre d’outils miniatures avec un ensemble de boutons spécifié à l’image miniature d’une fenêtre dans un menu volant de bouton de 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 reçoit 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 THUMBBUTTON définit un bouton individuel à ajouter à la barre d’outils. Les boutons ne peuvent pas être ajoutés ou supprimés ultérieurement. Il doit donc s’agir de l’ensemble défini complet. Les boutons ne peuvent pas également ê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 si elle réussit ou une valeur d’erreur sinon, y compris les éléments suivants :

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 permettre à l’utilisateur de restaurer ou d’activer la fenêtre. Par exemple, le lecteur Windows Media peut offrir des contrôles de transport multimédia standard tels que lecture, pause, désactivation et 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é au centre, transparent et affiché dans une zone sous la miniature plutôt que de couvrir n’importe quelle partie de celui-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.

Lorsqu’un bouton dans une barre d’outils miniatures est cliqué, la fenêtre associée à cette miniature est envoyée à 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 les boutons individuels ne puissent pas être ajoutés ou supprimés, ils peuvent être affichés et masqués via ThumbBarUpdateButtons selon les besoins. 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 lequel afficher des miniatures, ainsi qu’un nombre constant 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 sont à gauche et sont donc moins susceptibles d’être tronquées.

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

Accessibilité

Pour plus d’informations sur l’accessibilité dans les images de bouton de barre numérique, consultez la section Notes de ThumbBarSetImageList.

Examples

L’exemple suivant montre comment utiliser ThumbBarAddButtons pour ajouter une barre d’outils qui contient deux boutons à une miniature de la barre des tâches étendues.

HRESULT AddThumbBarButtons(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;
}

Spécifications

Voir aussi

ITaskbarList

ITaskbarList2

ITaskbarList3

ITaskbarList3 ::ThumbBarSetImageList

ITaskbarList3 ::ThumbBarUpdateButtons

Extensions de la barre des tâches