Structure NOTIFYICONDATAW (shellapi.h)
Contient les informations dont le système a besoin pour afficher des notifications dans la zone de notification. Utilisé par Shell_NotifyIcon.
Syntaxe
typedef struct _NOTIFYICONDATAW {
DWORD cbSize;
HWND hWnd;
UINT uID;
UINT uFlags;
UINT uCallbackMessage;
HICON hIcon;
#if ...
WCHAR szTip[64];
#else
WCHAR szTip[128];
#endif
DWORD dwState;
DWORD dwStateMask;
WCHAR szInfo[256];
union {
UINT uTimeout;
UINT uVersion;
} DUMMYUNIONNAME;
WCHAR szInfoTitle[64];
DWORD dwInfoFlags;
GUID guidItem;
HICON hBalloonIcon;
} NOTIFYICONDATAW, *PNOTIFYICONDATAW;
Membres
cbSize
Type : DWORD
Taille de cette structure, en octets.
hWnd
Type : HWND
Handle de la fenêtre qui reçoit des notifications associées à une icône dans la zone de notification.
uID
Type : UINT
Identificateur défini par l’application de l’icône de la barre des tâches. L’interpréteur de commandes utilise (hWnd plus uID) ou guidItem pour identifier l’icône sur laquelle opérer lorsque Shell_NotifyIcon est appelé. Vous pouvez avoir plusieurs icônes associées à un seul hWnd en affectant à chacune un uID différent. Si guidItem est spécifié, uID est ignoré.
uFlags
Type : UINT
Indicateurs qui indiquent quels autres membres de la structure contiennent des données valides ou fournissent des informations supplémentaires à l’info-bulle sur la façon dont elle doit s’afficher. Ce membre peut être une combinaison des valeurs suivantes :
NIF_MESSAGE (0x00000001)
0x00000001. Le membre uCallbackMessage est valide.
NIF_ICON (0x00000002)
0x00000002. Le membre hIcon est valide.
NIF_TIP (0x00000004)
0x00000004. Le membre szTip est valide.
NIF_STATE (0x00000008)
0x00000008. Les membres dwState et dwStateMask sont valides.
NIF_INFO (0x00000010)
0x00000010. Afficher une notification de bulle. Les membres szInfo, szInfoTitle, dwInfoFlags et uTimeout sont valides. Notez que uTimeout est valide uniquement dans Windows 2000 et Windows XP.
- Pour afficher la notification de bulle, spécifiez NIF_INFO et fournissez du texte dans szInfo.
- Pour supprimer une notification de bulle, spécifiez NIF_INFO et fournissez une chaîne vide via szInfo.
- Pour ajouter une icône de zone de notification sans afficher de notification, ne définissez pas l’indicateur NIF_INFO.
NIF_GUID (0x00000020)
0x00000020.
- Windows 7 et versions ultérieures : guidItem est valide.
- Windows Vista et versions antérieures : réservé.
NIF_REALTIME (0x00000040)
0x00000040. Windows Vista et versions ultérieures. Si la notification de bulle ne peut pas être affichée immédiatement, ignorez-la. Utilisez cet indicateur pour les notifications qui représentent des informations en temps réel qui seraient inutiles ou trompeuses si elles s’affichaient ultérieurement. Par exemple, un message indiquant « Votre téléphone sonne ». NIF_REALTIME est significatif uniquement lorsqu’elle est combinée avec l’indicateur NIF_INFO.
NIF_SHOWTIP (0x00000080)
0x00000080. Windows Vista et versions ultérieures. Utilisez l’info-bulle standard. Normalement, lorsque uVersion est défini sur NOTIFYICON_VERSION_4, l’info-bulle standard est supprimée et peut être remplacée par l’interface utilisateur contextuelle dessinée par l’application. Si l’application souhaite afficher l’info-bulle standard avec NOTIFYICON_VERSION_4, elle peut spécifier NIF_SHOWTIP pour indiquer que l’info-bulle standard doit toujours être affichée.
uCallbackMessage
Type : UINT
Identificateur de message défini par l’application. Le système utilise cet identificateur pour envoyer des messages de notification à la fenêtre identifiée dans hWnd. Ces messages de notification sont envoyés lorsqu’un événement de souris ou un pointage se produit dans le rectangle englobant de l’icône, lorsque l’icône est sélectionnée ou activée avec le clavier, ou lorsque ces actions se produisent dans la notification bulle.
Lorsque le membre uVersion est 0 ou NOTIFYICON_VERSION, le paramètre wParam du message contient l’identificateur de l’icône de barre des tâches dans laquelle l’événement s’est produit. Cet identificateur peut avoir une longueur de 32 bits. Le paramètre lParam contient le message de souris ou de clavier associé à l’événement. Par exemple, lorsque le pointeur se déplace sur une icône de barre des tâches, lParam est défini sur WM_MOUSEMOVE.
Lorsque le membre uVersion est NOTIFYICON_VERSION_4, les applications continuent de recevoir des événements de notification sous la forme de messages définis par l’application via le membre uCallbackMessage , mais l’interprétation des paramètres lParam et wParam de ce message est modifiée comme suit :
- LOWORD(lParam) contient des événements de notification, tels que NIN_BALLOONSHOW, NIN_POPUPOPEN ou WM_CONTEXTMENU.
- HIWORD(lParam) contient l’ID d’icône. Les ID d’icône sont limités à une longueur de 16 bits.
- GET_X_LPARAM(wParam) retourne la coordonnée d’ancre X pour les événements de notification NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT et tous les messages de souris entre WM_MOUSEFIRST et WM_MOUSELAST. Si l’un de ces messages est généré par le clavier, wParam est défini sur le coin supérieur gauche de l’icône cible. Pour tous les autres messages, wParam n’est pas défini.
- GET_Y_LPARAM(wParam) retourne la coordonnée d’ancre Y pour les événements et messages de notification tels que définis pour l’ancre X.
hIcon
Type : HICON
Handle de l’icône à ajouter, modifier ou supprimer. Windows XP et les versions ultérieures prennent en charge les icônes allant jusqu’à 32 BPP.
Si seule une icône de 16 x 16 pixels est fournie, elle est mise à l’échelle vers une plus grande taille dans un ensemble système vers une valeur ppp élevée. Cela peut entraîner un résultat peu attrayant. Il est recommandé de fournir une icône de 16 x 16 pixels et une icône 32 x 32 dans votre fichier de ressources. Utilisez LoadIconMetric pour vous assurer que l’icône correcte est chargée et mise à l’échelle de manière appropriée. Pour obtenir un exemple de code, consultez Remarques.
szTip[64]
Type : TCHAR[64]
Chaîne terminée par null qui spécifie le texte d’une info-bulle standard. Il peut comporter un maximum de 64 caractères, y compris le caractère null de fin.
Pour Windows 2000 et versions ultérieures, szTip peut avoir un maximum de 128 caractères, y compris le caractère null de fin.
szTip[128]
Type : TCHAR[64]
Chaîne terminée par null qui spécifie le texte d’une info-bulle standard. Il peut comporter un maximum de 64 caractères, y compris le caractère null de fin.
Pour Windows 2000 et versions ultérieures, szTip peut avoir un maximum de 128 caractères, y compris le caractère null de fin.
dwState
Type : DWORD
Windows 2000 et versions ultérieures. État de l’icône. Une ou les deux valeurs suivantes :
NIS_HIDDEN (0x00000001)
0x00000001. L’icône est masquée.
NIS_SHAREDICON (0x00000002)
0x00000002. La ressource icône est partagée entre plusieurs icônes.
dwStateMask
Type : DWORD
Windows 2000 et versions ultérieures. Valeur qui spécifie les bits du membre dwState qui sont récupérés ou modifiés. Les valeurs possibles sont les mêmes que celles pour dwState. Par exemple, la définition de ce membre sur NIS_HIDDEN entraîne uniquement la modification de l’état masqué de l’élément tandis que le bit de partage d’icône est ignoré, quelle que soit sa valeur.
szInfo[256]
Type : TCHAR[256]
Windows 2000 et versions ultérieures. Chaîne terminée par null qui spécifie le texte à afficher dans une notification de bulle. Il peut avoir un maximum de 256 caractères, y compris le caractère null de fin, mais doit être limité à 200 caractères en anglais pour prendre en charge la localisation. Pour supprimer la notification de bulle de l’interface utilisateur, supprimez l’icône (avec NIM_DELETE) ou définissez l’indicateur NIF_INFO dans uFlags et définissez szInfo sur une chaîne vide.
DUMMYUNIONNAME
DUMMYUNIONNAME.uTimeout
Type : UINT
Windows 2000 et versions ultérieures.
DUMMYUNIONNAME.uVersion
Type : UINT
Windows 2000 et versions ultérieures. Union avec uTimeout (déconseillé à partir de Windows Vista). Spécifie la version de l’interface d’icône de notification Shell à utiliser. Pour plus d’informations sur les différences entre ces versions, consultez Shell_NotifyIcon. Ce membre est utilisé uniquement lors de l’utilisation de Shell_NotifyIcon pour envoyer un message NIM_SETVERSION .
szInfoTitle[64]
Type : TCHAR[64]
Windows 2000 et versions ultérieures. Chaîne terminée par null qui spécifie un titre pour une notification de bulle. Ce titre apparaît dans une police plus grande juste au-dessus du texte. Il peut avoir un maximum de 64 caractères, y compris le caractère null de fin, mais doit être limité à 48 caractères en anglais pour prendre en charge la localisation.
dwInfoFlags
Type : DWORD
Windows 2000 et versions ultérieures. Indicateurs qui peuvent être définis pour modifier le comportement et l’apparence d’une notification de bulle. L’icône est placée à gauche du titre. Si le membre szInfoTitle est de longueur nulle, l’icône n’est pas affichée.
NIIF_NONE (0x00000000)
0x00000000. Pas d'icône.
NIIF_INFO (0x00000001)
0x00000001. Icône d'information.
NIIF_WARNING (0x00000002)
0x00000002. Icône d'avertissement.
NIIF_ERROR (0x00000003)
0x00000003. Icône d’erreur.
NIIF_USER (0x00000004)
0x00000004. Windows XP SP2 et versions ultérieures.
- Windows XP : utilisez l’icône identifiée dans hIcon comme icône de titre de la bulle de notification.
- Windows Vista et versions ultérieures : utilisez l’icône identifiée dans hBalloonIcon comme icône de titre de la bulle de notification.
NIIF_NOSOUND (0x00000010)
0x00000010. Windows XP et versions ultérieures. Ne lisez pas le son associé. S’applique uniquement aux notifications.
NIIF_LARGE_ICON (0x00000020)
0x00000020. Windows Vista et versions ultérieures. La version volumineuse de l’icône doit être utilisée comme icône de notification. Cela correspond à l’icône avec des dimensions SM_CXICON x SM_CYICON. Si cet indicateur n’est pas défini, l’icône avec des dimensions SM_CXSMICON x SM_CYSMICON est utilisée.
- Cet indicateur peut être utilisé avec toutes les icônes de stock.
- Les applications qui utilisent d’anciennes icônes personnalisées (NIIF_USER avec hIcon) doivent fournir une nouvelle version SM_CXICON x SM_CYICON dans l’icône de la barre d’état (hIcon). Ces icônes sont mises à l’échelle quand elles sont affichées dans la barre d’état système ou la zone de contrôle système (SCA).
- Les nouvelles icônes personnalisées (NIIF_USER avec hBalloonIcon) doivent fournir une version SM_CXICON x SM_CYICON dans l’icône fournie (hBalloonIcon).
NIIF_RESPECT_QUIET_TIME (0x00000080)
0x00000080. Windows 7 et versions ultérieures. N’affichez pas la notification de bulle si l’utilisateur actuel est en « temps calme », c’est-à-dire la première heure après qu’un nouvel utilisateur se connecte à son compte pour la première fois. Pendant ce temps, la plupart des notifications ne doivent pas être envoyées ou affichées. Cela permet à un utilisateur de s’habituer à un nouveau système informatique sans ces distractions. Le temps de silence se produit également pour chaque utilisateur après une mise à niveau du système d’exploitation ou une installation propre. Une notification envoyée avec cet indicateur pendant le temps de silence n’est pas mise en file d’attente ; il est simplement rejeté sans montrer. L’application peut renvoyer la notification ultérieurement si elle est toujours valide à ce moment-là.
Étant donné qu’une application ne peut pas prédire quand elle peut rencontrer une heure de silence, nous recommandons que cet indicateur soit toujours défini sur toutes les notifications appropriées par toute application qui signifie respecter le temps de silence.
Pendant le temps calme, certaines notifications doivent toujours être envoyées, car elles sont attendues par l’utilisateur comme des commentaires en réponse à une action de l’utilisateur, par exemple lorsqu’il connecte un périphérique USB ou imprime un document.
Si l’utilisateur actuel n’est pas en temps calme, cet indicateur n’a aucun effet.
NIIF_ICON_MASK (0x0000000F)
0x0000000F. Windows XP et versions ultérieures. Réservé.
guidItem
Type : GUID
Windows XP et versions ultérieures.
- Windows 7 et versions ultérieures : GUID inscrit qui identifie l’icône. Cette valeur remplace l’uID et est la méthode recommandée pour identifier l’icône. L’indicateur NIF_GUID doit être défini dans le membre uFlags .
- Windows XP et Windows Vista : réservé ; doit avoir la valeur 0.
Si vous identifiez l’icône de notification avec un GUID dans un appel à Shell_NotifyIcon, vous devez utiliser ce même GUID pour identifier l’icône dans les appels Shell_NotifyIcon suivants qui traitent de cette même icône.
Pour générer un GUID à utiliser dans ce membre, utilisez un outil de génération de GUID tel que Guidgen.exe.
hBalloonIcon
Type : HICON
Windows Vista et versions ultérieures. Handle d’une icône de notification personnalisée fournie par l’application qui doit être utilisée indépendamment de l’icône de zone de notification. Si ce membre n’est pas NULL et que l’indicateur NIIF_USER est défini dans le membre dwInfoFlags , cette icône est utilisée comme icône de notification. Si ce membre a la valeur NULL, le comportement hérité est effectué.
Remarques
Pour plus d’informations sur les meilleures pratiques relatives à l’interface utilisateur et au contenu, consultez Notifications dans les Instructions d’interaction de l’expérience utilisateur Windows.
Si vous définissez l’indicateur NIF_INFO dans le membre uFlags , la notification de type bulle est utilisée. Pour plus d’informations sur ces notifications, consultez Info-bulles.
Il n’est pas possible d’afficher plus d’une notification de bulle à la fois pour la barre des tâches. Si une application tente d’afficher une notification alors qu’elle est déjà affichée, la nouvelle notification est mise en file d’attente et affichée lorsque l’ancienne notification disparaît. Dans les versions de Windows antérieures à Windows Vista, la nouvelle notification n’apparaît pas tant que la notification existante n’a pas été visible pendant au moins la durée minimale du système, quelle que soit la valeur uTimeout de la notification d’origine. Si l’utilisateur ne semble pas utiliser l’ordinateur, le système ne compte pas cette fois dans le délai d’expiration.
Plusieurs membres de cette structure sont uniquement pris en charge pour Windows 2000 et versions ultérieures. Pour activer ces membres, incluez l’une des lignes suivantes dans votre en-tête :
// Windows Vista and later:
#define NTDDI_VERSION NTDDI_WIN2K
#define NTDDI_VERSION NTDDI_WINXP
#define NTDDI_VERSION NTDDI_VISTA
// Windows XP and earlier:
#define _WIN32_IE 0x0500
Notez que vous devez initialiser la structure avec sa taille. Si vous utilisez la taille de la structure actuellement définie, l’application risque de ne pas s’exécuter avec les versions antérieures de Shell32.dll, qui s’attendent à une structure plus petite. Vous pouvez exécuter votre application sur des versions antérieures de Shell32.dll en définissant le numéro de version approprié (voir Versions de l’interpréteur de commandes et des contrôles communs). Toutefois, cela peut entraîner des problèmes si votre application doit également s’exécuter sur des systèmes plus récents.
Vous pouvez maintenir la compatibilité de l’application avec toutes les versions Shell32.dll tout en utilisant les fichiers d’en-tête actuels en définissant la taille de la structure NOTIFYICONDATA de manière appropriée. Avant d’initialiser la structure, utilisez DllGetVersion pour déterminer quelle version Shell32.dll est installée sur le système et initialiser cbSize avec l’une des valeurs suivantes :
| version Shell32.dll | cbSize |
|---|---|
| 6.0.6 ou version ultérieure (Windows Vista et versions ultérieures) | sizeof(NOTIFYICONDATA) |
| 6.0 (Windows XP) | NOTIFYICONDATA_V3_SIZE |
| 5.0 (Windows 2000) | NOTIFYICONDATA_V2_SIZE |
| Versions inférieures à 5.0 | NOTIFYICONDATA_V1_SIZE |
L’utilisation de cette valeur pour cbSize permet à votre application d’utiliser NOTIFYICONDATA dans une méthode compatible avec les versions Shell32.dll antérieures.
L’exemple de code suivant montre la vérification de version qui peut permettre à une application qui utilise le membre guidItem de s’exécuter sur Windows Vista et Windows 7. Il fournit une fonction booléenne qui retourne TRUE si le système d’exploitation est Windows 7. Sauf si ce membre retourne TRUE, le membre guidItem doit être défini sur 0.
BOOL IsWin7OrLater()
{
// Initialize the OSVERSIONINFOEX structure.
OSVERSIONINFOEX osvi;
ZeroMemory(&osvi, sizeof(OSVERSIONINFOEX));
osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);
osvi.dwMajorVersion = 6;
osvi.dwMinorVersion = 1;
// Initialize the condition mask.
DWORDLONG dwlConditionMask = 0;
VER_SET_CONDITION(dwlConditionMask, VER_MAJORVERSION, VER_GREATER_EQUAL);
VER_SET_CONDITION(dwlConditionMask, VER_MINORVERSION, VER_GREATER_EQUAL);
// Perform the test.
return VerifyVersionInfo(&osvi,
VER_MAJORVERSION | VER_MINORVERSION,
dwlConditionMask);
}
L’exemple de code suivant montre l’utilisation de LoadIconMetric pour charger une icône pour une utilisation avec un DPI élevé.
// Declare NOTIFYICONDATA details.
// Error handling is omitted here for brevity. Do not omit it in your code.
NOTIFYICONDATA nid = {};
nid.cbSize = sizeof(nid);
nid.hWnd = hWnd;
nid.uFlags = NIF_ICON | NIF_TIP | NIF_GUID;
// Note: This is an example GUID only and should not be used.
// Normally, you should use a GUID-generating tool to provide the value to
// assign to guidItem.
static const GUID myGUID =
{0x23977b55, 0x10e0, 0x4041, {0xb8, 0x62, 0xb1, 0x95, 0x41, 0x96, 0x36, 0x69}};
nid.guidItem = myGUID;
// This text will be shown as the icon's tooltip.
StringCchCopy(nid.szTip, ARRAYSIZE(nid.szTip), L"Test application");
// Load the icon for high DPI.
LoadIconMetric(hInst, MAKEINTRESOURCE(IDI_SMALL), LIM_SMALL, &(nid.hIcon));
// Show the notification.
Shell_NotifyIcon(NIM_ADD, &nid) ? S_OK : E_FAIL;
Dépannage
Si vous utilisez le membre guidItem pour identifier l’icône, que cette icône ne s’affiche pas ou que certains appels à Shell_NotifyIcon échouent, l’une des causes probables est l’un des cas suivants :- L’indicateur NIF_GUID n’a pas été défini dans chaque appel sur Shell_NotifyIcon. Une fois que vous avez identifié l’icône de notification avec un GUID dans un appel à Shell_NotifyIcon, vous devez utiliser ce même GUID pour identifier l’icône dans tous les appels Shell_NotifyIcon suivants qui traitent cette même icône.
-
Le fichier binaire qui contient l’icône a été déplacé. Le chemin d’accès du fichier binaire est inclus dans l’inscription du GUID de l’icône et ne peut pas être modifié. Les paramètres associés à l’icône sont conservés via une mise à niveau uniquement si le chemin d’accès du fichier et le GUID sont inchangés. Si le chemin d’accès doit être modifié, l’application doit supprimer toutes les informations GUID ajoutées lors de l’inscription de l’icône existante. Une fois ces informations supprimées, vous pouvez déplacer le fichier binaire vers un nouvel emplacement et le réinscrire avec un nouveau GUID. Tous les paramètres associés à l’inscription GUID d’origine seront perdus.
Cela se produit également dans le cas d’une installation côte à côte. Lors d’une installation côte à côte, les nouvelles versions de l’application doivent mettre à jour le GUID du fichier binaire.
Note La seule exception à un fichier déplacé se produit lorsque les fichiers binaires d’origine et déplacés sont signés Authenticode par la même société. Dans ce cas, les paramètres sont conservés pendant le déplacement.
Notes
L’en-tête shellapi.h définit NOTIFYICONDATA comme un 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. Le mélange 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
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| En-tête | shellapi.h |