Partager via


Shell_NotifyIconA, fonction (shellapi.h)

Envoie un message à la zone status de la barre des tâches.

Syntaxe

BOOL Shell_NotifyIconA(
  [in] DWORD            dwMessage,
  [in] PNOTIFYICONDATAA lpData
);

Paramètres

[in] dwMessage

Type : DWORD

Valeur qui spécifie l’action à effectuer par cette fonction. Elle peut avoir l’une des valeurs suivantes :

NIM_ADD (0x00000000)

0x00000000. Ajoute une icône à la zone status. L’icône reçoit un identificateur dans la structure NOTIFYICONDATA pointée vers lpdata, par le biais de son uID ou de son membre guidItem . Cet identificateur est utilisé dans les appels suivants à Shell_NotifyIcon pour effectuer des actions ultérieures sur l’icône.

NIM_MODIFY (0x00000001)

0x00000001. Modifie une icône dans la zone status. La structure NOTIFYICONDATA pointée vers lpdata utilise l’ID attribué à l’origine à l’icône lors de son ajout à la zone de notification (NIM_ADD) pour identifier l’icône à modifier.

NIM_DELETE (0x00000002)

0x00000002. Supprime une icône de la zone status. La structure NOTIFYICONDATA pointée par lpdata utilise l’ID attribué à l’origine à l’icône lors de son ajout à la zone de notification (NIM_ADD) pour identifier l’icône à supprimer.

NIM_SETFOCUS (0x00000003)

0x00000003. Shell32.dll version 5.0 et ultérieures uniquement. Retourne le focus sur la zone de notification de la barre des tâches. Les icônes de zone de notification doivent utiliser ce message lorsqu’elles ont terminé leur opération d’interface utilisateur. Par exemple, si l’icône affiche un menu contextuel, mais que l’utilisateur appuie sur Échap pour l’annuler, utilisez NIM_SETFOCUS pour revenir au focus sur la zone de notification.

NIM_SETVERSION (0x00000004)

0x00000004. Shell32.dll version 5.0 et ultérieures uniquement. Indique à la zone de notification de se comporter en fonction du numéro de version spécifié dans le membre uVersion de la structure pointée par lpdata. Le numéro de version spécifie les membres qui sont reconnus.

NIM_SETVERSION doivent être appelées chaque fois qu’une icône de zone de notification est ajoutée (NIM_ADD). Il n’a pas besoin d’être appelé avec NIM_MODIFY. Le paramètre de version n’est pas conservé une fois qu’un utilisateur se déconnecte.

Pour plus d'informations, consultez la section Notes.

[in] lpData

Type : PNOTIFYICONDATA

Pointeur vers une structure NOTIFYICONDATA . Le contenu de la structure dépend de la valeur de dwMessage. Il peut définir une icône à ajouter à la zone de notification, faire afficher une notification ou identifier une icône à modifier ou supprimer.

Valeur retournée

Type : BOOL

Retourne TRUE en cas de réussite, ou FALSE dans le cas contraire. Si dwMessage est défini sur NIM_SETVERSION, la fonction retourne TRUE si la version a été correctement modifiée, ou FALSE si la version demandée n’est pas prise en charge.

Remarques

À partir de Windows 2000 (Shell32.dll version 5.0), si vous définissez le membre uVersion de la structure NOTIFYICONDATA pointé par lpdata sur NOTIFYICON_VERSION_4 ou version ultérieure, Shell_NotifyIcon événements de souris et de clavier sont gérés différemment par rapport aux versions antérieures de Windows. Les différences sont les suivantes :

  • Si un utilisateur sélectionne le menu contextuel d’une icône de notification avec le clavier, l’interpréteur de commandes envoie maintenant à l’application associée un message WM_CONTEXTMENU . Les versions antérieures envoient des messages WM_RBUTTONDOWN et WM_RBUTTONUP .
  • Si un utilisateur sélectionne une icône de notification avec le clavier et l’active avec la touche SPACEBAR ou ENTRÉE, l’interpréteur de commandes version 5.0 envoie à l’application associée une notification NIN_KEYSELECT. Les versions antérieures envoient des messages WM_RBUTTONDOWN et WM_RBUTTONUP .
  • Si un utilisateur sélectionne une icône de notification avec la souris et l’active avec la touche Entrée, l’interpréteur de commandes envoie maintenant à l’application associée une notification NIN_SELECT. Les versions antérieures envoient des messages WM_RBUTTONDOWN et WM_RBUTTONUP .
À compter de Windows XP (Shell32.dll version 6.0), si un utilisateur passe le pointeur de la souris sur une icône à laquelle une notification bulle est associée, l’interpréteur de commandes envoie les messages suivants :
  • NIN_BALLOONSHOW. Envoyé lorsque la bulle est affichée (les bulles sont mises en file d’attente).
  • NIN_BALLOONHIDE. Envoyé lorsque le ballon disparaît. Par exemple, lorsque l’icône est supprimée. Ce message n’est pas envoyé si la bulle est ignorée en raison d’un délai d’expiration ou si l’utilisateur clique sur la souris.

    À compter de Windows 7, NIN_BALLOONHIDE est également envoyé lorsqu’une notification avec l’indicateur NIIF_RESPECT_QUIET_TIME défini tente de s’afficher pendant le temps calme (première heure d’un utilisateur sur un nouvel ordinateur). Dans ce cas, le ballon n’est jamais affiché.

  • NIN_BALLOONTIMEOUT. Envoyé lorsque la bulle est ignorée en raison d’un délai d’expiration.
  • NIN_BALLOONUSERCLICK. Envoyé lorsque la bulle est ignorée parce que l’utilisateur a cliqué sur la souris.
En plus de ces messages, à compter de Windows Vista (Shell32.dll version 6.0.6), si un utilisateur passe le pointeur de la souris sur une icône à laquelle une notification bulle est associée, l’interpréteur de commandes Windows Vista ajoute également les messages suivants :
  • NIN_POPUPOPEN. Envoyé lorsque l’utilisateur place le curseur sur une icône pour indiquer que l’interface utilisateur contextuelle plus riche doit être utilisée à la place d’une info-bulle textuelle standard.
  • NIN_POPUPCLOSE. Envoyé lorsqu’un curseur ne pointe plus sur une icône pour indiquer que l’interface utilisateur contextuelle enrichie doit être fermée.
Quelle que soit la version du système d’exploitation, vous pouvez sélectionner la façon dont l’interpréteur de commandes doit se comporter en appelant Shell_NotifyIcon avec dwMessage défini sur NIM_SETVERSION. Définissez le membre uVersion de la structure NOTIFYICONDATA pointée vers lpdata pour indiquer si vous souhaitez un comportement Windows 2000, Windows Vista ou préversion 5.0 (Windows 95).
Note Les messages décrits ci-dessus ne sont pas des messages Windows classiques. Ils sont envoyés en tant que valeur lParam du message défini par l’application spécifié dans le membre uCallbackMessage de la structure NOTIFYICONDATA pointée par lpdata, quand Shell_NotifyIcon est appelée avec l’indicateur NIM_ADD défini dans dwMessage.
 
À partir de Windows XP Service Pack 2 (SP2), une icône personnalisée peut être affichée dans la bulle de notification. Cela permet au processus appelant de personnaliser la notification au-delà des options précédemment disponibles d’informations, d’avertissement et d’erreur, et de la distinguer des autres types de notification pour l’utilisateur.

Notes

L’en-tête shellapi.h définit Shell_NotifyIcon en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête shellapi.h
Bibliothèque Shell32.lib
DLL Shell32.dll (version 4.0 ou ultérieure)
Ensemble d’API ext-ms-win-shell-shell32-l1-2-1 (introduit dans Windows 10, version 10.0.10240)

Voir aussi

Notifications et zone de notification