ITaskbarList3::SetOverlayIcon-Methode (shobjidl_core.h)
Wendet eine Überlagerung auf eine Taskleistenschaltfläche an, um die Anwendung status oder eine Benachrichtigung für den Benutzer anzugeben.
Syntax
HRESULT SetOverlayIcon(
[in] HWND hwnd,
[in] HICON hIcon,
[in] LPCWSTR pszDescription
);
Parameter
[in] hwnd
Typ: HWND
Das Handle des Fensters, dessen zugehörige Taskleistenschaltfläche die Überlagerung empfängt. Dieses Handle muss zu einem aufrufenden Prozess gehören, der der Anwendung der Schaltfläche zugeordnet ist, und muss ein gültiger HWND sein, sonst wird der Aufruf ignoriert.
[in] hIcon
Typ: HICON
Das Handle eines Symbols, das als Überlagerung verwendet werden soll. Dies sollte ein kleines Symbol mit einer Größe von 16 x 16 Pixeln bei 96 dpi sein. Wenn bereits ein Overlaysymbol auf die Taskleistenschaltfläche angewendet wurde, wird dieses vorhandene Overlay ersetzt.
Dieser Wert kann NULL sein. Wie ein NULL-Wert behandelt wird, hängt davon ab, ob die Taskleistenschaltfläche ein einzelnes Fenster oder eine Gruppe von Fenstern darstellt.
- Wenn die Taskleistenschaltfläche ein einzelnes Fenster darstellt, wird das Überlagerungssymbol aus der Anzeige entfernt.
- Wenn die Taskleistenschaltfläche eine Gruppe von Fenstern darstellt und eine vorherige Überlagerung weiterhin verfügbar ist (die vor der aktuellen Überlagerung empfangen wurde, aber noch nicht durch einen NULL-Wert freigegeben wurde), wird diese vorherige Überlagerung anstelle des aktuellen Overlays angezeigt.
Es liegt in der Verantwortung der aufrufenden Anwendung , hIcon frei zu geben, wenn es nicht mehr benötigt wird. Dies kann in der Regel nach dem Aufruf von SetOverlayIcon erfolgen, da die Taskleiste eine eigene Kopie des Symbols erstellt und verwendet.
[in] pszDescription
Typ: LPCWSTR
Ein Zeiger auf eine Zeichenfolge, die zu Barrierefreiheitszwecken eine Alternativtextversion der von der Überlagerung übermittelten Informationen bereitstellt.
Rückgabewert
Typ: HRESULT
Wenn diese Methode erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.
Hinweise
In Versionen von Windows vor Windows 7 verwendeten Anwendungen häufig Symbole im Benachrichtigungsbereich der Taskleiste, um dem Benutzer anwendungsseitig status und Benachrichtigungen anzuzeigen. Die Windows 7-Taskleiste ermöglicht es einer Anwendung, dieselbe Art von Benutzerfeedback über die Taskleistenschaltfläche bereitzustellen, wodurch mehr Anwendungsinformationen an einem Ort zentralisiert werden. Diese Überlagerungen ähneln vorhandenen Überlagerungen, die für Tastenkombinationen oder Sicherheitsbenachrichtigungen verwendet werden und in der unteren rechten Ecke der Schaltfläche angezeigt werden.
Die folgende Abbildung zeigt eine Überlagerung (das kleine, grüne Quadrat, das angibt, dass der Benutzer als "Verfügbar" status), das auf die ganz rechts angebrachte Taskleistenschaltfläche angewendet wird.
Symbolüberlagerungen dienen als kontextbezogene Benachrichtigung über status und sollen die Notwendigkeit eines separaten Benachrichtigungsbereichs status Symbols für die Kommunikation dieser Informationen an den Benutzer aufheben. Der Anwendungs-Designer muss während des Entwicklungszyklus entscheiden, welche Methode – Symbolüberlagerung oder Benachrichtigungsbereich status Symbol – für diese Anwendung am besten geeignet ist. Overlaysymbole sollen wichtige, langjährige status oder Benachrichtigungen wie Netzwerk-status, Messenger-status oder neue E-Mails bereitstellen. Sie sollten nicht häufig geändert und auch nicht animiert werden.
Um ein Überlagerungssymbol anzuzeigen, muss sich die Taskleiste im Standardmodus für große Symbole befinden. Wenn die Taskleiste über Taskleisten- und Startmenüeigenschaften so konfiguriert ist, dass kleine Symbole angezeigt werden, können Überlagerungen nicht angewendet werden, und Aufrufe dieser Methode werden ignoriert.
Da eine einzelne Überlagerung auf die Taskleistenschaltfläche anstelle der Miniaturansichten einzelner Fenster angewendet wird, ist dies ein Feature pro Gruppe und nicht pro Fenster. Anforderungen für Überlagerungssymbole können von einzelnen Fenstern in einer Taskleistengruppe empfangen werden, aber nicht in der Warteschlange. Das letzte empfangene Overlay ist das angezeigte Overlay. Wenn das zuletzt empfangene Overlay entfernt wird, wird das ersetzte Overlay wiederhergestellt, solange es noch aktiv ist. Als Beispiel legen Windows 1, 2 und 3 in der Reihenfolge die Überlagerungen A, B und C fest. Da Overlay C zuletzt empfangen wurde, wird es auf der Taskleistenschaltfläche angezeigt. Fenster 2 ruft SetOverlayIcon mit einem NULL-Wert auf, um Overlay B zu entfernen. Fenster 3 tut dann das gleiche, um Overlay C zu entfernen. Da die Überlagerung A von Fenster 1 weiterhin aktiv ist, wird dieses Overlay dann auf der Taskleistenschaltfläche angezeigt.
Wenn Windows Explorer unerwartet heruntergefahren wird, werden Überlagerungen nicht wiederhergestellt, wenn Windows Explorer wiederhergestellt wird. Die Anwendung sollte warten, bis die TaskbarButtonCreated-Meldung empfangen wird, die angibt, dass Windows Explorer neu gestartet und die Taskleistenschaltfläche neu erstellt wurde, und dann SetOverlayIcon erneut aufrufen, um das Overlay erneut anzufügen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 7 [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 R2 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | shobjidl_core.h (einschließlich Shobjidl.h) |
| Bibliothek | Explorerframe.lib |
| DLL | Explorerframe.dll |