Struttura NOTIFYICONDATAW (shellapi.h)
Contiene informazioni che il sistema deve visualizzare le notifiche nell'area di notifica. Usato da Shell_NotifyIcon.
Sintassi
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;
Membri
cbSize
Tipo: DWORD
Dimensioni di questa struttura, in byte.
hWnd
Tipo: HWND
Handle per la finestra che riceve le notifiche associate a un'icona nell'area di notifica.
uID
Tipo: UINT
Identificatore definito dall'applicazione dell'icona della barra delle applicazioni. Shell usa (hWnd più uID) o guidItem per identificare l'icona da utilizzare quando viene richiamata Shell_NotifyIcon. È possibile associare più icone a un singolo hWnd assegnando a ogni diversouID . Se viene specificato guidItem, uID viene ignorato.
uFlags
Tipo: UINT
Flag che indicano quali degli altri membri della struttura contengono dati validi o forniscono informazioni aggiuntive alla descrizione comando su come deve essere visualizzato. Questo membro può essere una combinazione dei valori seguenti:
NIF_MESSAGE (0x00000001)
0x00000001. Il membro uCallbackMessage
NIF_ICON (0x00000002)
0x00000002. Il membro hIcon
NIF_TIP (0x00000004)
0x00000004. Il membro szTip
NIF_STATE (0x00000008)
0x00000008. I membri dwState e dwStateMask sono validi.
NIF_INFO (0x00000010)
0x00000010. Visualizzare una notifica balloon. I membri di szInfo, szInfoTitle, dwInfoFlagse uTimeout sono validi. Si noti che uTimeout è valido solo in Windows 2000 e Windows XP.
- Per visualizzare la notifica balloon, specificare NIF_INFO e fornire testo in szInfo.
- Per rimuovere una notifica balloon, specificare NIF_INFO e specificare una stringa vuota tramite szInfo.
- Per aggiungere un'icona dell'area di notifica senza visualizzare una notifica, non impostare il flag di NIF_INFO.
NIF_GUID (0x00000020)
0x00000020.
Windows 7 e versioni successive : l' guidItemè valido. - Windows Vista e versioni precedenti: riservato.
NIF_REALTIME (0x00000040)
0x00000040. Windows Vista e versioni successive. Se non è possibile visualizzare immediatamente la notifica balloon, eliminarla. Usa questo flag per le notifiche che rappresentano informazioni in tempo reale che sarebbero inutili o fuorvianti se visualizzate in un secondo momento. Ad esempio, un messaggio che indica che il telefono sta suonando. NIF_REALTIME è significativo solo se combinato con il flag di NIF_INFO.
NIF_SHOWTIP (0x00000080)
0x00000080. Windows Vista e versioni successive. Usare la descrizione comando standard. In genere, quando uVersion è impostato su NOTIFYICON_VERSION_4, la descrizione comando standard viene eliminata e può essere sostituita dall'interfaccia utente popup disegnata dall'applicazione. Se l'applicazione vuole visualizzare la descrizione comando standard con NOTIFYICON_VERSION_4, può specificare NIF_SHOWTIP per indicare che la descrizione comando standard deve essere comunque visualizzata.
uCallbackMessage
Tipo: UINT
Identificatore di messaggio definito dall'applicazione. Il sistema usa questo identificatore per inviare messaggi di notifica alla finestra identificata in hWnd. Questi messaggi di notifica vengono inviati quando si verifica un evento del mouse o il passaggio del mouse nel rettangolo di delimitazione dell'icona, quando l'icona viene selezionata o attivata con la tastiera o quando tali azioni si verificano nella notifica di fumetto.
Quando il membro
Quando il membro uVersion
- LOWORD(lParam) contiene eventi di notifica, ad esempio NIN_BALLOONSHOW, NIN_POPUPOPEN o WM_CONTEXTMENU.
- HIWORD(lParam) contiene l'ID icona. Gli ID icona sono limitati a una lunghezza di 16 bit.
-
GET_X_LPARAM(wParam) restituisce la coordinata X per gli eventi di notifica NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT e tutti i messaggi del mouse tra WM_MOUSEFIRST e WM_MOUSELAST. Se uno di questi messaggi viene generato dalla tastiera, wParam viene impostato sull'angolo superiore sinistro dell'icona di destinazione. Per tutti gli altri messaggi, wParam non è definito. - GET_Y_LPARAM(wParam) restituisce la coordinata di ancoraggio Y per gli eventi di notifica e i messaggi definiti per l'ancoraggio X.
hIcon
Tipo: hicon
Handle per l'icona da aggiungere, modificare o eliminare. Windows XP e versioni successive supportano icone fino a 32 BPP.
Se viene fornita solo un'icona di 16x16 pixel, viene ridimensionata a dimensioni maggiori in un sistema impostato su un valore DPI elevato. Questo può portare a un risultato non interessante. È consigliabile specificare sia un'icona da 16x16 pixel che un'icona 32x32 nel file di risorse. Usare LoadIconMetric per assicurarsi che l'icona corretta venga caricata e ridimensionata in modo appropriato. Per un esempio di codice, vedere La sezione Osservazioni.
szTip[64]
Tipo: TCHAR[64]
Stringa con terminazione Null che specifica il testo per una descrizione comando standard. Può avere un massimo di 64 caratteri, incluso il carattere Null di terminazione.
Per Windows 2000 e versioni successive, szTip può avere un massimo di 128 caratteri, incluso il carattere Null di terminazione.
szTip[128]
Tipo: TCHAR[64]
Stringa con terminazione Null che specifica il testo per una descrizione comando standard. Può avere un massimo di 64 caratteri, incluso il carattere Null di terminazione.
Per Windows 2000 e versioni successive, szTip può avere un massimo di 128 caratteri, incluso il carattere Null di terminazione.
dwState
Tipo: DWORD
Windows 2000 e versioni successive. Stato dell'icona. Uno o entrambi i valori seguenti:
NIS_HIDDEN (0x00000001)
0x00000001. L'icona è nascosta.
NIS_SHAREDICON (0x00000002)
0x00000002. La risorsa icona viene condivisa tra più icone.
dwStateMask
Tipo: DWORD
Windows 2000 e versioni successive. Valore che specifica i bit del membro
szInfo[256]
Tipo: TCHAR[256]
Windows 2000 e versioni successive. Stringa con terminazione Null che specifica il testo da visualizzare in una notifica di fumetto. Può avere un massimo di 256 caratteri, incluso il carattere Null di terminazione, ma deve essere limitato a 200 caratteri in inglese per supportare la localizzazione. Per rimuovere la notifica di fumetto dall'interfaccia utente, eliminare l'icona (con NIM_DELETE) oppure impostare il flag NIF_INFO in uFlags e impostare szInfo su una stringa vuota.
DUMMYUNIONNAME
DUMMYUNIONNAME.uTimeout
Tipo: UINT
Windows 2000 e versioni successive.
DUMMYUNIONNAME.uVersion
Tipo: UINT
Windows 2000 e versioni successive. Unione con uTimeout (deprecato a partire da Windows Vista). Specifica la versione dell'interfaccia dell'icona di notifica della shell da usare. Per altre informazioni sulle differenze in queste versioni, vedere Shell_NotifyIcon. Questo membro viene utilizzato solo quando si utilizza Shell_NotifyIcon per inviare un messaggio di NIM_SETVERSION.
szInfoTitle[64]
Tipo: TCHAR[64]
Windows 2000 e versioni successive. Stringa con terminazione Null che specifica un titolo per una notifica di fumetto. Questo titolo viene visualizzato in un tipo di carattere più grande immediatamente sopra il testo. Può avere un massimo di 64 caratteri, incluso il carattere Null di terminazione, ma deve essere limitato a 48 caratteri in inglese per supportare la localizzazione.
dwInfoFlags
Tipo: DWORD
Windows 2000 e versioni successive. Flag che possono essere impostati per modificare il comportamento e l'aspetto di una notifica di fumetto. L'icona viene posizionata a sinistra del titolo. Se il membro szInfoTitle
NIIF_NONE (0x00000000)
0x00000000. Nessuna icona.
NIIF_INFO (0x00000001)
0x00000001. Icona informazioni.
NIIF_WARNING (0x00000002)
0x00000002. Icona di avviso.
NIIF_ERROR (0x00000003)
0x00000003. Icona di errore.
NIIF_USER (0x00000004)
0x00000004. Windows XP SP2 e versioni successive.
- windows XP: usare l'icona identificata in hIcon come icona del titolo dell'area di notifica.
- Windows Vista e versioni successive: usare l'icona identificata in hBalloonIcon come icona del titolo dell'area di notifica.
NIIF_NOSOUND (0x00000010)
0x00000010. Windows XP e versioni successive. Non riprodurre il suono associato. Si applica solo alle notifiche.
NIIF_LARGE_ICON (0x00000020)
0x00000020. Windows Vista e versioni successive. La versione grande dell'icona deve essere usata come icona di notifica. Corrisponde all'icona con dimensioni SM_CXICON x SM_CYICON. Se questo flag non è impostato, viene utilizzata l'icona con dimensioni SM_CXSMICON x SM_CYSMICON.
- Questo flag può essere usato con tutte le icone stock.
- Le applicazioni che usano icone personalizzate meno recenti (NIIF_USER con hIcon) devono fornire una nuova versione SM_CXICON x SM_CYICON nell'icona del vassoio (hIcon). Queste icone vengono ridimensionate quando vengono visualizzate nella barra di sistema o nell'area sca (System Control Area).
- Le nuove icone personalizzate (NIIF_USER con hBalloonIcon) devono fornire una versione SM_CXICON x SM_CYICON nell'icona fornita (hBalloonIcon).
NIIF_RESPECT_QUIET_TIME (0x00000080)
0x00000080. Windows 7 e versioni successive. Non visualizzare la notifica balloon se l'utente corrente è in "tempo di silenzio", ovvero la prima ora dopo che un nuovo utente accede al suo account per la prima volta. Durante questo periodo, la maggior parte delle notifiche non deve essere inviata o visualizzata. Ciò consente a un utente di diventare abituato a un nuovo sistema informatico senza distrazioni. Il tempo di quiete si verifica anche per ogni utente dopo un aggiornamento o un'installazione pulita del sistema operativo. Una notifica inviata con questo flag durante il tempo non è in coda; viene semplicemente ignorato. L'applicazione può inviare nuovamente la notifica in un secondo momento se è ancora valida in quel momento.
Poiché un'applicazione non è in grado di prevedere quando potrebbe verificarsi un tempo di inattività, è consigliabile impostare questo flag sempre su tutte le notifiche appropriate da parte di qualsiasi applicazione che significa rispettare il tempo di quiete.
Durante il tempo di silenzio, alcune notifiche devono comunque essere inviate perché sono previste dall'utente come feedback in risposta a un'azione dell'utente, ad esempio quando collega un dispositivo USB o stampa un documento.
Se l'utente corrente non è in modalità non interattiva, questo flag non ha alcun effetto.
NIIF_ICON_MASK (0x0000000F)
0x0000000F. Windows XP e versioni successive. Riservato.
guidItem
Tipo: GUID
Windows XP e versioni successive.
-
Windows 7 e versioni successive: GUID registrato che identifica l'icona. Questo valore esegue l'override uID ed è il metodo consigliato per identificare l'icona. Il flag NIF_GUID deve essere impostato nel membro
uFlags. - Windows XP e Windows Vista: riservato; deve essere impostato su 0.
Se si identifica l'icona di notifica con un GUID in una chiamata a Shell_NotifyIcon, è necessario usare lo stesso GUID per identificare l'icona in tutte le successive Shell_NotifyIcon chiamate che gestiscono la stessa icona.
Per generare un GUID da usare in questo membro, usare uno strumento di generazione GUID, ad esempio Guidgen.exe.
hBalloonIcon
Tipo: hicon
Windows Vista e versioni successive. Handle di un'icona di notifica personalizzata fornita dall'applicazione che deve essere usata indipendentemente dall'icona dell'area di notifica. Se questo membro è diverso da NULL e il flag NIIF_USER viene impostato nel membro dwInfoFlags, questa icona viene usata come icona di notifica. Se questo membro è NULL, viene eseguito il comportamento legacy.
Osservazioni
Per altre informazioni sulle procedure consigliate per l'interfaccia utente e il contenuto, vedere Notifiche nelle Linee guida per l'interazione dell'esperienza utente di Windows.
Se si imposta il flag NIF_INFO nel membro uFlags, viene usata la notifica in stile fumetto. Per altre informazioni su queste notifiche, vedere descrizione comando Balloon.
Non è possibile visualizzare più notifiche di fumetto alla volta per la barra delle applicazioni. Se un'applicazione tenta di visualizzare una notifica quando ne viene già visualizzata una, la nuova notifica viene accodata e visualizzata quando la notifica precedente viene rimossa. Nelle versioni di Windows precedenti a Windows Vista, la nuova notifica non viene visualizzata fino a quando la notifica esistente non è stata visibile per almeno la durata minima del timeout di sistema, indipendentemente dal valore di
Diversi membri di questa struttura sono supportati solo per Windows 2000 e versioni successive. Per abilitare questi membri, includere una delle righe seguenti nell'intestazione:
// 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
Si noti che è necessario inizializzare la struttura con le relative dimensioni. Se si usano le dimensioni della struttura attualmente definita, l'applicazione potrebbe non essere eseguita con versioni precedenti di Shell32.dll, che prevedono una struttura più piccola. È possibile eseguire l'applicazione in versioni precedenti di Shell32.dll definendo il numero di versione appropriato .vedere Shell e Common Controls Versions). Tuttavia, questo potrebbe causare problemi se l'applicazione deve essere eseguita anche in sistemi più recenti.
È possibile mantenere la compatibilità delle applicazioni con tutte le versioni Shell32.dll mentre si usano ancora i file di intestazione correnti impostando in modo appropriato le dimensioni della struttura NOTIFYICONDATA. Prima di inizializzare la struttura, usare dllGetVersion per determinare quale versione Shell32.dll è installata nel sistema e inizializzare cbSize con uno di questi valori:
| versione Shell32.dll | cbSize |
|---|---|
| 6.0.6 o versione successiva (Windows Vista e versioni successive) | sizeof(NOTIFYICONDATA) |
| 6.0 (Windows XP) | NOTIFYICONDATA_V3_SIZE |
| 5.0 (Windows 2000) | NOTIFYICONDATA_V2_SIZE |
| Versioni inferiori alla 5.0 | NOTIFYICONDATA_V1_SIZE |
L'uso di questo valore per cbSize consente all'applicazione di usare NOTIFYICONDATA in un metodo compatibile con le versioni precedenti di Shell32.dll.
Nell'esempio di codice seguente viene illustrato il controllo della versione che consente di abilitare un'applicazione che usa il membro guidItem per l'esecuzione sia in Windows Vista che in Windows 7. Fornisce una funzione booleana che restituisce TRUE se il sistema operativo è Windows 7. A meno che questo membro non restituisca
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);
}
Nell'esempio di codice seguente viene illustrato l'uso di LoadIconMetric per caricare un'icona da usare con valori DPI elevati.
// 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;
risoluzione dei problemi di
Se si usa il membro guidItem- Il flag NIF_GUID non è stato impostato in ogni chiamata a Shell_NotifyIcon. Dopo aver identificato l'icona di notifica con un GUID in una chiamata a Shell_NotifyIcon, è necessario usare lo stesso GUID per identificare l'icona in qualsiasi Shell_NotifyIcon chiamate successive che gestiscono la stessa icona.
-
Il file binario che contiene l'icona è stato spostato. Il percorso del file binario è incluso nella registrazione del GUID dell'icona e non può essere modificato. Le impostazioni associate all'icona vengono mantenute tramite un aggiornamento solo se il percorso del file e il GUID sono invariati. Se il percorso deve essere modificato, l'applicazione deve rimuovere tutte le informazioni GUID aggiunte al momento della registrazione dell'icona esistente. Dopo aver rimosso le informazioni, è possibile spostare il file binario in un nuovo percorso e registrarlo nuovamente con un nuovo GUID. Tutte le impostazioni associate alla registrazione GUID originale andranno perse.
Ciò si verifica anche nel caso di un'installazione side-by-side. Quando si tratta di un'installazione side-by-side, le nuove versioni dell'applicazione devono aggiornare il GUID del file binario.
Nota L'unica eccezione a un file spostato si verifica quando i file binari originali e spostati sono Authenticodefirmato dalla stessa società. In tal caso, le impostazioni vengono mantenute tramite lo spostamento.
Nota
L'intestazione shellapi.h definisce NOTIFYICONDATA come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [solo app desktop] |
| server minimo supportato | Windows 2000 Server [solo app desktop] |
| intestazione |
shellapi.h |