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

Applique une superposition à un bouton de barre des tâches pour indiquer l’status de l’application ou une notification à l’utilisateur.

Syntaxe

HRESULT SetOverlayIcon(
  [in] HWND    hwnd,
  [in] HICON   hIcon,
  [in] LPCWSTR pszDescription
);

Paramètres

[in] hwnd

Type : HWND

Handle de la fenêtre dont le bouton de barre des tâches associé reçoit la superposition. Ce handle doit appartenir à un processus d’appel associé à l’application du bouton et doit être un HWND valide ou l’appel est ignoré.

[in] hIcon

Type : HICON

Handle d’une icône à utiliser comme superposition. Il doit s’agir d’une petite icône, mesurant 16 x 16 pixels à 96 ppp. Si une icône de superposition est déjà appliquée au bouton de la barre des tâches, cette superposition existante est remplacée.

Cette valeur peut être NULL. La façon dont une valeur NULL est gérée dépend du fait que le bouton de la barre des tâches représente une fenêtre unique ou un groupe de fenêtres.

• Si le bouton de la barre des tâches représente une seule fenêtre, l’icône de superposition est supprimée de l’affichage.
• Si le bouton de la barre des tâches représente un groupe de fenêtres et qu’une superposition précédente est toujours disponible (reçue avant la superposition actuelle, mais pas encore libérée par une valeur NULL ), cette superposition précédente s’affiche à la place de la superposition actuelle.

Il incombe à l’application appelante de libérer hIcon lorsqu’il n’est plus nécessaire. Cela peut généralement être effectué après avoir appelé SetOverlayIcon , car la barre des tâches crée et utilise sa propre copie de l’icône.

[in] pszDescription

Type : LPCWSTR

Pointeur vers une chaîne qui fournit une version de texte de remplacement des informations transmises par la superposition, à des fins d’accessibilité.

Valeur retournée

Type : HRESULT

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

Remarques

Dans les versions de Windows antérieures à Windows 7, les applications utilisaient souvent des icônes dans la zone de notification de la barre des tâches pour afficher les status d’application et les notifications à l’utilisateur. La barre des tâches windows 7 permet à une application de fournir le même type de commentaires utilisateur via son bouton de barre des tâches, centralisant davantage d’informations sur l’application dans un même emplacement. Ces superpositions sont similaires aux superpositions existantes utilisées pour les icônes de raccourci ou les notifications de sécurité, affichées dans le coin inférieur droit du bouton.

L’illustration suivante montre une superposition (le petit carré vert qui indique que l’utilisateur status comme « Disponible ») appliquée au bouton de la barre des tâches à droite.

superposition d’icône de status disponible sert de notification contextuelle de status et est destinée à annuler la nécessité d’une zone de notification distincte status icône pour communiquer ces informations à l’utilisateur. Le concepteur d’application doit décider pendant le cycle de développement de la méthode (superposition d’icône ou zone de notification status icône) qui convient le mieux à cette application. Les icônes de superposition sont destinées à fournir des status ou des notifications importantes et de longue date, telles que les status réseau, les status de messagerie ou les nouveaux messages électroniques. Ils ne doivent pas être fréquemment modifiés, et ils ne doivent pas être animés.

Pour afficher une icône de superposition, la barre des tâches doit être en mode icône grande par défaut. Si la barre des tâches est configurée via la barre des tâches et les propriétés du menu Démarrer pour afficher de petites icônes, les superpositions ne peuvent pas être appliquées et les appels à cette méthode sont ignorés.

Étant donné qu’une seule superposition est appliquée au bouton de la barre des tâches au lieu des miniatures de fenêtre individuelles, il s’agit d’une fonctionnalité par groupe plutôt que par fenêtre. Les demandes d’icônes de superposition peuvent être reçues à partir de fenêtres individuelles d’un groupe de barre des tâches, mais elles ne sont pas en file d’attente. La dernière superposition reçue est la superposition affichée. Si la dernière superposition reçue est supprimée, la superposition qu’elle a remplacée est restaurée tant qu’elle est toujours active. Par exemple, windows 1, 2 et 3 définissent, dans l’ordre, les superpositions A, B et C. Étant donné que la superposition C a été reçue en dernier, elle s’affiche sur le bouton de la barre des tâches. La fenêtre 2 appelle SetOverlayIcon avec une valeur NULL pour supprimer la superposition B. La fenêtre 3 fait de même pour supprimer la superposition C. Étant donné que la superposition A de la fenêtre 1 est toujours active, cette superposition s’affiche ensuite sur le bouton de la barre des tâches.

Si Windows Explorer s’arrête de manière inattendue, les superpositions ne sont pas restaurées lorsque Windows Explorer est restauré. L’application doit attendre de recevoir le message TaskbarButtonCreated qui indique que Windows Explorer a redémarré et que le bouton de barre des tâches a été recréé, puis appeler à nouveau SetOverlayIcon pour réappliquer la superposition.

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 (inclure Shobjidl.h)
Bibliothèque	Explorerframe.lib
DLL	Explorerframe.dll

Voir aussi

ITaskbarList

ITaskbarList2

ITaskbarList3

Extensions de la barre des tâches