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