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. L'icona viene assegnato un identificatore nella struttura NOTIFYICONDATA a cui fa riferimento lpdata, tramite il relativo membro uID o 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. La struttura NOTIFYICONDATA puntata da lpdata usa l'ID originariamente assegnato all'icona quando è stata aggiunta all'area di notifica (NIM_ADD) per identificare l'icona da modificare.

NIM_DELETE (0x00000002)

0x00000002. Elimina un'icona dall'area di stato. La struttura NOTIFYICONDATA puntata da 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 successiva solo. Restituisce lo stato attivo nell'area di notifica della barra delle applicazioni. Le icone dell'area di notifica devono usare questo messaggio al termine dell'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 successiva solo. Indica all'area di notifica di comportarsi in base al numero di versione specificato nel membro uVersion 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 mantenuta una volta 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, causare la visualizzazione di una notifica o l'identificazione di un'icona da modificare o eliminare.

Valore restituito

Tipo: BOOL

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

Commenti

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

  • 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 di WM_RBUTTONDOWN e WM_RBUTTONUP .
  • Se un utente seleziona un'icona di notifica con la tastiera e la attiva con il tasto SPACEBAR o INVIO, shell versione 5.0 invia all'applicazione associata una notifica NIN_KEYSELECT. Le versioni precedenti inviano messaggi di WM_RBUTTONDOWN e WM_RBUTTONUP .
  • Se un utente seleziona un'icona di notifica con il mouse e la attiva con la chiave INVIO, shell invia ora all'applicazione associata una notifica NIN_SELECT. Le versioni precedenti inviano messaggi di 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 a palloncini, shell invia i messaggi seguenti:
  • NIN_BALLOONSHOW. Inviato quando viene visualizzato il palloncino (i palloncini vengono accodati).
  • NIN_BALLOONHIDE. Inviato quando il palloncino scompare. Ad esempio, quando l'icona viene eliminata. Questo messaggio non viene inviato se il palloncino 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 set di flag NIIF_RESPECT_QUIET_TIME tenta di visualizzare durante l'ora di silenzio (la prima ora di un utente in un nuovo computer). In questo caso, il palloncino non viene mai visualizzato.

  • NIN_BALLOONTIMEOUT. Inviato quando il palloncino viene ignorato a causa di un timeout.
  • NIN_BALLOONUSERCLICK. Inviato quando il palloncino viene ignorato perché l'utente ha fatto clic sul mouse.
Oltre a questi messaggi, a partire da Windows Vista (Shell32.dll versione 6.0.6), se un utente passa il puntatore del mouse su un'icona con cui è associata una notifica a forma di palloncino, Windows Vista Shell aggiunge anche i messaggi seguenti:
  • NIN_POPUPOPEN. Inviato quando l'utente passa il puntatore del mouse 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 modo in cui shell deve comportarsi chiamando Shell_NotifyIcon con dwMessage impostato su NIM_SETVERSION. Impostare il membro uVersion della struttura NOTIFYICONDATA a cui punta lpdata per indicare se si vuole il comportamento di Windows 2000, Windows Vista o versione pre-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 nel palloncino di notifica. In questo modo, il processo chiamante consente di personalizzare la notifica oltre alle opzioni disponibili in precedenza di informazioni, avvisi ed errori 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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito Valore
Client minimo supportato Windows XP [solo app desktop]
Server minimo supportato Windows 2000 Server [solo app desktop]
Piattaforma di destinazione Windows
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)

Vedi anche

Notifiche e area di notifica