Metodo ITaskbarList3::SetOverlayIcon (shobjidl_core.h)

Applica una sovrimpressione a un pulsante della barra delle applicazioni per indicare lo stato dell'applicazione o una notifica all'utente.

Sintassi

HRESULT SetOverlayIcon(
  [in] HWND    hwnd,
  [in] HICON   hIcon,
  [in] LPCWSTR pszDescription
);

Parametri

[in] hwnd

Tipo: HWND

Handle della finestra il cui pulsante della barra delle applicazioni associato riceve la sovrimpressione. Questo handle deve appartenere a un processo chiamante associato all'applicazione del pulsante e deve essere un HWND valido o la chiamata viene ignorata.

[in] hIcon

Tipo: HICON

Handle di un'icona da usare come sovrimpressione. Dovrebbe essere un'icona piccola, misurando 16x16 pixel a 96 dpi. Se un'icona di sovrimpressione è già applicata al pulsante della barra delle applicazioni, tale sovrimpressione esistente viene sostituita.

Questo valore può essere NULL. Il modo in cui viene gestito un valore NULL dipende dal fatto che il pulsante della barra delle applicazioni rappresenti una singola finestra o un gruppo di finestre.

• Se il pulsante della barra delle applicazioni rappresenta una singola finestra, l'icona di sovrapposizione viene rimossa dalla visualizzazione.
• Se il pulsante della barra delle applicazioni rappresenta un gruppo di finestre e una sovrimpressione precedente è ancora disponibile (ricevuta prima della sovrimpressione corrente, ma non ancora liberata da un valore NULL ), tale sovrimpressione precedente viene visualizzata al posto della sovrimpressione corrente.

È responsabilità dell'applicazione chiamante liberare hIcon quando non è più necessaria. Questa operazione può essere eseguita in genere dopo aver chiamato SetOverlayIcon perché la barra delle applicazioni crea e usa la propria copia dell'icona.

[in] pszDescription

Tipo: LPCWSTR

Puntatore a una stringa che fornisce una versione di testo alternativo delle informazioni trasmesse dalla sovrimpressione, a scopo di accessibilità.

Valore restituito

Tipo: HRESULT

Se questo metodo ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

Nelle versioni di Windows precedenti a Windows 7, le applicazioni spesso utilizzavano icone nell'area di notifica della barra delle applicazioni per visualizzare lo stato e le notifiche dell'applicazione all'utente. La barra delle applicazioni di Windows 7 consente a un'applicazione di fornire lo stesso tipo di feedback degli utenti tramite il pulsante della barra delle applicazioni, centralizzando più informazioni sull'applicazione in un'unica posizione. Queste sovrimpressioni sono simili alle sovrimpressioni esistenti usate per le icone di scelta rapida o le notifiche di sicurezza, visualizzate nell'angolo inferiore destro del pulsante.

La figura seguente mostra una sovrimpressione (il piccolo quadrato verde che indica lo stato dell'utente come "Disponibile") applicato al pulsante della barra delle applicazioni all'estrema destra.

Le sovrimpressioni delle icone fungono da notifica contestuale dello stato e hanno lo scopo di negare la necessità di un'icona di stato separata dell'area di notifica per comunicare tali informazioni all'utente. La finestra di progettazione dell'applicazione deve decidere durante il ciclo di sviluppo quale metodo, ovvero l'icona sovrapposta o l'icona di stato dell'area di notifica, serve meglio a tale applicazione. Le icone di sovrapposizione sono destinate a fornire notifiche o stato importanti, di lunga durata, ad esempio lo stato della rete, lo stato del messenger o la nuova posta. Non devono essere modificati frequentemente, né devono essere animati.

Per visualizzare un'icona di sovrimpressione, la barra delle applicazioni deve essere nella modalità icona grande predefinita. Se la barra delle applicazioni è configurata tramite la barra delle applicazioni e le proprietà del menu Start per visualizzare icone di piccole dimensioni, le sovrimpressioni non possono essere applicate e le chiamate a questo metodo vengono ignorate.

Poiché una singola sovrimpressione viene applicata al pulsante della barra delle applicazioni anziché alle singole anteprime della finestra, si tratta di una funzionalità per gruppo anziché per finestra. Le richieste di icone di sovrimpressione possono essere ricevute da singole finestre in un gruppo della barra delle applicazioni, ma non in coda. L'ultima sovrimpressione ricevuta è la sovrimpressione visualizzata. Se l'ultima sovrimpressione ricevuta viene rimossa, la sovrimpressione sostituita viene ripristinata purché sia ancora attiva. Ad esempio, windows 1, 2 e 3 impostati, in ordine, sovrappone A, B e C. Poiché la sovrimpressione C è stata ricevuta per ultima, viene visualizzata sul pulsante della barra delle applicazioni. Window 2 chiama SetOverlayIcon con un valore NULL per rimuovere la sovrimpressione B. Finestra 3 quindi esegue la stessa operazione per rimuovere la sovrimpressione C. Poiché la sovrimpressione della finestra 1 È ancora attiva, tale sovrimpressione viene quindi visualizzata sul pulsante della barra delle applicazioni.

Se Esplora risorse viene arrestato in modo imprevisto, le sovrimpressioni non vengono ripristinate al ripristino di Esplora risorse. L'applicazione deve attendere di ricevere il messaggio TaskbarButtonCreated che indica che Esplora risorse è stato riavviato e che il pulsante della barra delle applicazioni è stato ricreato e quindi chiamare nuovamente SetOverlayIcon per riapplicare la sovrimpressione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shobjidl_core.h (include Shobjidl.h)
Libreria	Explorerframe.lib
DLL	Explorerframe.dll

Vedi anche

ITaskbarList

ITaskbarList2

ITaskbarList3

Estensioni della barra delle applicazioni