Shell_NotifyIconA-Funktion (shellapi.h)

  • Artikel

Sendet eine Nachricht an den status Bereich der Taskleiste.

Syntax

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

Parameter

[in] dwMessage

Art: DWORD

Ein -Wert, der die aktion angibt, die von dieser Funktion ausgeführt werden soll. Die Variable muss einen der folgenden Werte aufweisen:

NIM_ADD (0x00000000)

0x00000000. Fügt dem bereich status ein Symbol hinzu. Das Symbol erhält einen Bezeichner in der NOTIFYICONDATA-Struktur , auf die von lpdata verwiesen wird– entweder über sein uID - oder guidItem-Element . Dieser Bezeichner wird in nachfolgenden Aufrufen von Shell_NotifyIcon verwendet, um spätere Aktionen auf dem Symbol auszuführen.

NIM_MODIFY (0x00000001)

0x00000001. Ändert ein Symbol im bereich status. Die NOTIFYICONDATA-Struktur , auf die von lpdata verwiesen wird, verwendet die ID, die dem Symbol ursprünglich zugewiesen wurde, als es dem Infobereich (NIM_ADD) hinzugefügt wurde, um das zu ändernde Symbol zu identifizieren.

NIM_DELETE (0x00000002)

0x00000002. Löscht ein Symbol aus dem bereich status. Die NOTIFYICONDATA-Struktur , auf die von lpdata verwiesen wird, verwendet die ID, die dem Symbol ursprünglich zugewiesen wurde, als es dem Infobereich (NIM_ADD) hinzugefügt wurde, um das zu löschende Symbol zu identifizieren.

NIM_SETFOCUS (0x00000003)

0x00000003. Shell32.dll nur Version 5.0 und höher. Gibt den Fokus auf den Infobereich der Taskleiste zurück. Benachrichtigungsbereichssymbole sollten diese Meldung verwenden, wenn sie ihren Ui-Vorgang abgeschlossen haben. Wenn z. B. auf dem Symbol ein Kontextmenü angezeigt wird, der Benutzer jedoch ESC drückt, um es abzubrechen, verwenden Sie NIM_SETFOCUS , um den Fokus auf den Infobereich zurückzugeben.

NIM_SETVERSION (0x00000004)

0x00000004. Shell32.dll nur Version 5.0 und höher. Weist den Infobereich an, sich entsprechend der Versionsnummer zu verhalten, die im uVersion-Member der Struktur angegeben ist, auf die von lpdata verwiesen wird. Die Versionsnummer gibt an, welche Member erkannt werden.

NIM_SETVERSION muss jedes Mal aufgerufen werden, wenn ein Benachrichtigungsbereichssymbol hinzugefügt wird (NIM_ADD). Es muss nicht mit NIM_MODIFY aufgerufen werden. Die Versionseinstellung wird nicht beibehalten, sobald sich ein Benutzer abmeldet.

Weitere Informationen finden Sie im Abschnitt Hinweise.

[in] lpData

Typ: PNOTIFYICONDATA

Ein Zeiger auf eine NOTIFYICONDATA-Struktur . Der Inhalt der Struktur hängt vom Wert von dwMessage ab. Es kann ein Symbol definieren, das dem Infobereich hinzugefügt werden soll, bewirkt, dass dieses Symbol eine Benachrichtigung anzeigt oder ein Symbol identifiziert, das geändert oder gelöscht werden soll.

Rückgabewert

Typ: BOOL

Gibt TRUE zurück, wenn erfolgreich, andernfalls FALSE . Wenn dwMessage auf NIM_SETVERSION festgelegt ist, gibt die Funktion TRUE zurück, wenn die Version erfolgreich geändert wurde, oder FALSE , wenn die angeforderte Version nicht unterstützt wird.

Hinweise

Wenn Sie ab Windows 2000 (Shell32.dll Version 5.0) den uVersion-Member der NOTIFYICONDATA-Struktur , auf die von lpdata verwiesen wird, auf NOTIFYICON_VERSION_4 oder höher festlegen, werden Shell_NotifyIcon Maus- und Tastaturereignisse anders behandelt als in früheren Versionen von Windows. Zu den Unterschieden gehören die folgenden:

  • Wenn ein Benutzer das Kontextmenü eines Benachrichtigungssymbols mit der Tastatur auswählt, sendet die Shell der zugehörigen Anwendung jetzt eine WM_CONTEXTMENU Nachricht. Frühere Versionen senden WM_RBUTTONDOWN und WM_RBUTTONUP Nachrichten.
  • Wenn ein Benutzer ein Benachrichtigungssymbol mit der Tastatur auswählt und es mit der LEERTASTE oder DER EINGABETASTE aktiviert, sendet die Shell der Version 5.0 der zugehörigen Anwendung eine NIN_KEYSELECT Benachrichtigung. Frühere Versionen senden WM_RBUTTONDOWN und WM_RBUTTONUP Nachrichten.
  • Wenn ein Benutzer mit der Maus ein Benachrichtigungssymbol auswählt und es mit der EINGABETASTE aktiviert, sendet die Shell der zugeordneten Anwendung nun eine NIN_SELECT Benachrichtigung. Frühere Versionen senden WM_RBUTTONDOWN und WM_RBUTTONUP Nachrichten.
Ab Windows XP (Shell32.dll Version 6.0) sendet die Shell die folgenden Meldungen, wenn ein Benutzer den Mauszeiger auf ein Symbol übergibt, dem eine Sprechblasebenachrichtigung zugeordnet ist:
  • NIN_BALLOONSHOW. Wird gesendet, wenn die Sprechblase angezeigt wird (Sprechblasen werden in die Warteschlange eingereiht).
  • NIN_BALLOONHIDE. Wird gesendet, wenn der Sprechblasen verschwindet. Beispielsweise, wenn das Symbol gelöscht wird. Diese Nachricht wird nicht gesendet, wenn die Sprechblase aufgrund eines Timeouts geschlossen wird oder wenn der Benutzer mit der Maus klickt.

    Ab Windows 7 wird NIN_BALLOONHIDE auch gesendet, wenn eine Benachrichtigung mit dem NIIF_RESPECT_QUIET_TIME flag set versucht, während der ruhen Zeit (die erste Stunde eines Benutzers auf einem neuen Computer) anzuzeigen. In diesem Fall wird der Sprechblasen niemals angezeigt.

  • NIN_BALLOONTIMEOUT. Wird gesendet, wenn die Sprechblase aufgrund eines Timeouts geschlossen wird.
  • NIN_BALLOONUSERCLICK. Wird gesendet, wenn die Sprechblase geschlossen wird, weil der Benutzer mit der Maus geklickt hat.
Zusätzlich zu diesen Meldungen fügt die Windows Vista-Shell ab Windows Vista (Shell32.dll Version 6.0.6) die folgenden Meldungen hinzu, wenn ein Benutzer den Mauszeiger über ein Symbol zeigt, dem eine Sprechblasebenachrichtigung zugeordnet ist:
  • NIN_POPUPOPEN. Wird gesendet, wenn der Benutzer den Cursor über ein Symbol bewegt, um anzugeben, dass die umfangreichere Popup-Benutzeroberfläche anstelle einer standardmäßigen Text-QuickInfo verwendet werden soll.
  • NIN_POPUPCLOSE. Wird gesendet, wenn ein Cursor nicht mehr über ein Symbol bewegt wird, um anzugeben, dass die umfangreiche Popup-Benutzeroberfläche geschlossen werden soll.
Unabhängig von der Betriebssystemversion können Sie auswählen, wie sich die Shell verhalten soll, indem Sie Shell_NotifyIcon aufrufen, wobei dwMessage auf NIM_SETVERSION festgelegt ist. Legen Sie den uVersion-Member der NOTIFYICONDATA-Struktur fest, auf die von lpdata verwiesen wird, um anzugeben, ob Windows 2000, Windows Vista oder Vorversion 5.0 (Windows 95) verhalten soll.
Hinweis Bei den oben beschriebenen Nachrichten handelt es sich nicht um herkömmliche Windows-Nachrichten. Sie werden als lParam-Wert der anwendungsdefinierten Nachricht gesendet, die im uCallbackMessage-Member der NOTIFYICONDATA-Struktur angegeben ist, auf die von lpdata verwiesen wird, wenn Shell_NotifyIcon mit dem in dwMessage festgelegten NIM_ADD-Flag aufgerufen wird.
 
Ab Windows XP Service Pack 2 (SP2) kann ein benutzerdefiniertes Symbol in der Benachrichtigungssprechblase angezeigt werden. Dadurch kann der aufrufende Prozess die Benachrichtigung über die zuvor verfügbaren Optionen für Informationen, Warnungen und Fehler hinaus anpassen und von anderen Benachrichtigungstypen für den Benutzer unterscheiden.

Hinweis

Der Shellapi.h-Header definiert Shell_NotifyIcon als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile shellapi.h
Bibliothek Shell32.lib
DLL Shell32.dll (Version 4.0 oder höher)
APIs ext-ms-win-shell-shell32-l1-2-1 (eingeführt in Windows 10, Version 10.0.10240)

Weitere Informationen

Benachrichtigungen und der Benachrichtigungsbereich