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

Weitere Informationen

ITaskbarList

ITaskbarList2

ITaskbarList3

Taskleistenerweiterungen