Condividi tramite

funzione Shell_NotifyIconA (shellapi.h)

  • Articolo

Invia un messaggio all'area di stato della barra delle applicazioni.

Sintassi

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

Parametri

[in] dwMessage

Tipo: DWORD

Valore che specifica l'azione da eseguire da questa funzione. Può avere uno dei valori seguenti:

NIM_ADD (0x00000000)

0x00000000. Aggiunge un'icona all'area di stato. All'icona viene assegnato un identificatore nella struttura NOTIFYICONDATA a cui punta lpdata, tramite il relativo uID o membro guidItem. Questo identificatore viene usato nelle chiamate successive a Shell_NotifyIcon per eseguire azioni successive sull'icona.

NIM_MODIFY (0x00000001)

0x00000001. Modifica un'icona nell'area di stato. struttura di NOTIFYICONDATA a cui punta lpdata usa l'ID originariamente assegnato all'icona quando è stato aggiunto all'area di notifica (NIM_ADD) per identificare l'icona da modificare.

NIM_DELETE (0x00000002)

0x00000002. Elimina un'icona dall'area di stato. struttura di NOTIFYICONDATA a cui punta lpdata usa l'ID originariamente assegnato all'icona quando è stato aggiunto all'area di notifica (NIM_ADD) per identificare l'icona da eliminare.

NIM_SETFOCUS (0x00000003)

0x00000003. Shell32.dll versione 5.0 e successive solo. Restituisce lo stato attivo sull'area di notifica della barra delle applicazioni. Le icone dell'area di notifica devono usare questo messaggio quando hanno completato l'operazione dell'interfaccia utente. Ad esempio, se l'icona visualizza un menu di scelta rapida, ma l'utente preme ESC per annullarlo, usare NIM_SETFOCUS per restituire lo stato attivo all'area di notifica.

NIM_SETVERSION (0x00000004)

0x00000004. Shell32.dll versione 5.0 e successive solo. Indica all'area di notifica di comportarsi in base al numero di versione specificato nel uVersion membro della struttura a cui punta lpdata. Il numero di versione specifica i membri riconosciuti.

NIM_SETVERSION deve essere chiamato ogni volta che viene aggiunta un'icona dell'area di notifica (NIM_ADD). Non è necessario chiamare con NIM_MODIFY. L'impostazione della versione non viene salvata in modo permanente dopo che un utente si disconnette.

Per informazioni dettagliate, vedere la sezione Osservazioni.

[in] lpData

Tipo: PNOTIFYICONDATA

Puntatore a una struttura NOTIFYICONDATA. Il contenuto della struttura dipende dal valore di dwMessage. Può definire un'icona da aggiungere all'area di notifica, fare in modo che l'icona visualizzi una notifica o identificare un'icona da modificare o eliminare.

Valore restituito

Tipo: bool

Restituisce TRUE in caso di esito positivo oppure FALSE in caso contrario. Se dwMessage è impostato su NIM_SETVERSION, la funzione restituisce TRUE se la versione è stata modificata correttamente oppure FALSE se la versione richiesta non è supportata.

Osservazioni

A partire da Windows 2000 (Shell32.dll versione 5.0), se si imposta il membro della struttura NOTIFYICONDATA a cui punta lpdata su NOTIFYICON_VERSION_4 o versione successiva, Shell_NotifyIcon gli eventi del mouse e della tastiera vengono gestiti in modo diverso rispetto alle versioni precedenti di Windows. Le differenze includono:

  • Se un utente seleziona un menu di scelta rapida dell'icona di notifica con la tastiera, shell invia ora all'applicazione associata un messaggio di WM_CONTEXTMENU. Le versioni precedenti inviano messaggi WM_RBUTTONDOWN e WM_RBUTTONUP.
  • Se un utente seleziona un'icona di notifica con la tastiera e la attiva con la BARRA SPAZIATRICE o IL tasto INVIO, la shell della versione 5.0 invia all'applicazione associata una notifica di NIN_KEYSELECT. Le versioni precedenti inviano messaggi WM_RBUTTONDOWN e WM_RBUTTONUP.
  • Se un utente seleziona un'icona di notifica con il mouse e la attiva con il tasto INVIO, shell invia ora all'applicazione associata una notifica di NIN_SELECT. Le versioni precedenti inviano messaggi WM_RBUTTONDOWN e WM_RBUTTONUP.
A partire da Windows XP (Shell32.dll versione 6.0), se un utente passa il puntatore del mouse su un'icona con cui è associata una notifica di fumetto, la shell invia i messaggi seguenti:
  • NIN_BALLOONSHOW. Inviato quando viene visualizzato il fumetto (le palloncini vengono accodate).
  • NIN_BALLOONHIDE. Inviato quando il palloncino scompare. Ad esempio, quando l'icona viene eliminata. Questo messaggio non viene inviato se il fumetto viene ignorato a causa di un timeout o se l'utente fa clic sul mouse.

    A partire da Windows 7, NIN_BALLOONHIDE viene inviato anche quando una notifica con il flag NIIF_RESPECT_QUIET_TIME impostato tenta di visualizzare durante l'ora non interattiva (la prima ora di un utente in un nuovo computer). In tal caso, il fumetto non viene mai visualizzato affatto.

  • NIN_BALLOONTIMEOUT. Inviato quando il fumetto viene ignorato a causa di un timeout.
  • NIN_BALLOONUSERCLICK. Inviato quando il fumetto viene ignorato perché l'utente ha fatto clic sul mouse.
Oltre a tali messaggi, a partire da Windows Vista (Shell32.dll versione 6.0.6), se un utente passa il puntatore del mouse su un'icona a cui è associata una notifica di fumetto, la shell di Windows Vista aggiunge anche i messaggi seguenti:
  • NIN_POPUPOPEN. Inviato quando l'utente passa il cursore su un'icona per indicare che l'interfaccia utente popup più avanzata deve essere usata al posto di una descrizione comando testuale standard.
  • NIN_POPUPCLOSE. Inviato quando un cursore non passa più sopra un'icona per indicare che l'interfaccia utente popup avanzata deve essere chiusa.
Indipendentemente dalla versione del sistema operativo, è possibile selezionare il comportamento della shell chiamando Shell_NotifyIcon con dwMessage impostato su NIM_SETVERSION. Impostare il membro uVersion della struttura NOTIFYICONDATA a cui punta lpdata per indicare se si desidera che si desideri il comportamento di Windows 2000, Windows Vista o versione precedente alla versione 5.0 (Windows 95).
Nota I messaggi descritti in precedenza non sono messaggi di Windows convenzionali. Vengono inviati come valore lParam del messaggio definito dall'applicazione specificato nel membro uCallbackMessage della struttura NOTIFYICONDATA a cui punta lpdata, quando Shell_NotifyIcon viene chiamato con il flag NIM_ADD impostato in dwMessage.
 
A partire da Windows XP Service Pack 2 (SP2), è possibile visualizzare un'icona personalizzata nell'area di notifica. In questo modo il processo chiamante consente di personalizzare la notifica oltre le opzioni disponibili in precedenza di info, avviso ed errore e distinguerla da altri tipi di notifica per l'utente.

Nota

L'intestazione shellapi.h definisce Shell_NotifyIcon 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]
piattaforma di destinazione Finestre
intestazione shellapi.h
libreria Shell32.lib
dll Shell32.dll (versione 4.0 o successiva)
set di API ext-ms-win-shell-shell32-l1-2-1 (introdotto in Windows 10, versione 10.0.10240)

Vedere anche

Notifiche e area di notifica