Struttura NOTIFYICONDATAA (shellapi.h)
Contiene informazioni che il sistema deve visualizzare le notifiche nell'area di notifica. Usato da Shell_NotifyIcon.
Sintassi
typedef struct _NOTIFYICONDATAA {
DWORD cbSize;
HWND hWnd;
UINT uID;
UINT uFlags;
UINT uCallbackMessage;
HICON hIcon;
#if ...
CHAR szTip[64];
#else
CHAR szTip[128];
#endif
DWORD dwState;
DWORD dwStateMask;
CHAR szInfo[256];
union {
UINT uTimeout;
UINT uVersion;
} DUMMYUNIONNAME;
CHAR szInfoTitle[64];
DWORD dwInfoFlags;
GUID guidItem;
HICON hBalloonIcon;
} NOTIFYICONDATAA, *PNOTIFYICONDATAA;
Members
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 richiamato Shell_NotifyIcon . È possibile avere più icone associate a un singolo hWnd assegnando ogni uID diverso. Se si specifica guidItem , uID viene ignorato.
uFlags
Tipo: UINT
Flag che indicano quale degli altri membri della struttura contengono dati validi o forniscono informazioni aggiuntive alla descrizione comando per la modalità di visualizzazione. Questo membro può essere una combinazione dei valori seguenti:
NIF_MESSAGE (0x00000001)
0x00000001. Il membro uCallbackMessage è valido.
NIF_ICON (0x00000002)
0x00000002. Il membro hIcon è valido.
NIF_TIP (0x00000004)
0x00000004. Il membro szTip è valido.
NIF_STATE (0x00000008)
0x00000008. I membri dwState e dwStateMask sono validi.
NIF_INFO (0x00000010)
0x00000010. Visualizzare una notifica di fumetto. I membri szInfo, szInfoTitle, dwInfoFlags e uTimeout sono validi. Si noti che uTimeout è valido solo in Windows 2000 e Windows XP.
- Per visualizzare la notifica balloon, specificare NIF_INFO e specificare il testo in szInfo.
- Per rimuovere una notifica balloon, specificare NIF_INFO e fornire 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: guidItem valido.
- Windows Vista e versioni precedenti: riservato.
NIF_REALTIME (0x00000040)
0x00000040. Windows Vista e versioni successive. Se la notifica del fumetto non può essere visualizzata immediatamente, eliminarla. Usare questo flag per le notifiche che rappresentano informazioni in tempo reale che sarebbero senza significato o fuorvianti se visualizzate in un secondo momento. Ad esempio, un messaggio che indica che "Il telefono sta squillando". 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 del fumetto.
Quando il membro uVersion è 0 o NOTIFYICON_VERSION, il parametro wParam del messaggio contiene l'identificatore dell'icona della barra delle applicazioni in cui si è verificato l'evento. Questo identificatore può essere di lunghezza pari a 32 bit. Il parametro lParam contiene il messaggio del mouse o della tastiera associato all'evento. Ad esempio, quando il puntatore si sposta su un'icona della barra delle applicazioni, lParam è impostato su WM_MOUSEMOVE.
Quando il membro uVersion è NOTIFYICON_VERSION_4, le applicazioni continuano a ricevere eventi di notifica sotto forma di messaggi definiti dall'applicazione tramite il membro uCallbackMessage , ma l'interpretazione dei parametri lParam e wParam di tale messaggio viene modificata nel modo seguente:
- 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 di ancoraggio 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 fino a una dimensione maggiore in un sistema impostato su un valore DPI elevato. Ciò può portare a un risultato non interessante. È consigliabile specificare sia un'icona a 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 è condivisa tra più icone.
dwStateMask
Tipo: DWORD
Windows 2000 e versioni successive. Valore che specifica i bit del membro dwState recuperati o modificati. I valori possibili sono uguali a quelli di dwState. Ad esempio, impostando questo membro su NIS_HIDDEN viene modificato solo lo stato nascosto dell'elemento mentre il bit di condivisione delle icone viene ignorato indipendentemente dal relativo valore.
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 balloon dall'interfaccia utente, eliminare l'icona (con NIM_DELETE) o 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 è di lunghezza zero, l'icona non viene visualizzata.
NIIF_NONE (0x00000000)
0x00000000. Nessuna icona.
NIIF_INFO (0x00000001)
0x00000001. Icona informativa.
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 predefinite.
- Le applicazioni che usano icone personalizzate meno recenti (NIIF_USER con hIcon) devono fornire una nuova versione SM_CXICON x SM_CYICON nell'icona della barra delle applicazioni (hIcon). Queste icone vengono ridimensionate quando vengono visualizzate nell'area di controllo di sistema o nell'area di controllo del sistema.
- 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 del fumetto se l'utente corrente è in tempo non interattiva, 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. In questo modo un utente diventa abituato a un nuovo sistema informatico senza distrazioni. Il tempo di inattività 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; è semplicemente ignorato. L'applicazione può inviare di nuovo la notifica in un secondo momento, se è ancora valida in quel momento.
Poiché un'applicazione non può prevedere quando potrebbe verificarsi un tempo di inattività, è consigliabile impostare sempre questo flag su tutte le notifiche appropriate da qualsiasi applicazione che significa rispettare il tempo di inattività.
Durante il periodo di quiete, 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 di 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 chiamate Shell_NotifyIcon successive 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 utilizzata indipendentemente dall'icona dell'area di notifica. Se questo membro è diverso da NULL e il flag NIIF_USER è impostato nel membro dwInfoFlags , questa icona viene usata come icona di notifica. Se questo membro è NULL, viene eseguito il comportamento legacy.
Commenti
Per altre informazioni sulle procedure consigliate per l'interfaccia utente e il contenuto di notifica, 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, vedi Descrizioni 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 è visibile per almeno la lunghezza minima del timeout del sistema, indipendentemente dal valore uTimeout della notifica originale. Se l'utente non sembra utilizzare il computer, il sistema non conta questo tempo per il timeout.
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 le 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 versioni dei controlli comuni). 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 pur utilizzando i file di intestazione correnti impostando le dimensioni della struttura NOTIFYICONDATA in modo appropriato. 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 a 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.
L'esempio di codice seguente mostra il controllo della versione che consente l'abilitazione di 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 TRUE, il membro guidItem deve essere impostato su 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);
}
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 relativi
Se si usa il membro guidItem per identificare l'icona e tale icona non viene visualizzata o alcune chiamate a Shell_NotifyIcon hanno esito negativo, uno dei casi seguenti è la causa probabile:- 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 tutte le chiamate Shell_NotifyIcon successive che gestiscono la stessa icona.
-
Il file binario contenente 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 tali 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 usa 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 firmati da Authenticode 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Intestazione | shellapi.h |