SHMessageBoxCheckW-Funktion (shlwapi.h)

  • Artikel

[SHMessageBoxCheck ist für die Verwendung in den im Abschnitt Anforderungen angegebenen Betriebssystemen verfügbar. Sie kann in nachfolgenden Versionen geändert oder nicht verfügbar sein.]

Zeigt ein Meldungsfeld an, das dem Benutzer die Möglichkeit gibt, weitere Vorkommen zu unterdrücken. Wenn der Benutzer bereits entschieden hat, das Meldungsfeld zu unterdrücken, zeigt die Funktion kein Dialogfeld an und gibt stattdessen einfach den Standardwert zurück.

Syntax

int SHMessageBoxCheckW(
  [in, optional] HWND    hwnd,
  [in]           LPCWSTR pszText,
  [in]           LPCWSTR pszCaption,
                 UINT    uType,
                 int     iDefault,
  [in]           LPCWSTR pszRegVal
);

Parameter

[in, optional] hwnd

Typ: HWND

Das Fensterhandle für den Besitzer des Meldungsfelds. Dieser Wert kann NULL sein.

[in] pszText

Typ: LPCTSTR

Ein Zeiger auf eine NULL-endende Zeichenfolge, die die anzuzeigende Meldung enthält.

[in] pszCaption

Typ: LPCTSTR

Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Titel des Meldungsfelds enthält. Wenn dieser Parameter auf NULL festgelegt ist, wird der Titel auf Error! festgelegt.

uType

Typ: UINT

Die Flags, die den Inhalt und das Verhalten des Meldungsfelds angeben. Diese Funktion unterstützt nur eine Teilmenge der von MessageBox unterstützten Flags. Wenn Sie Flags verwenden, die unten nicht aufgeführt sind, ist das Verhalten der Funktion nicht definiert.

Sie müssen die anzuzeigenden Schaltflächen angeben, indem Sie nur eins der folgenden Flags festlegen.

MB_OKCANCEL

Zeigt ein Meldungsfeld mit den Schaltflächen OK und Abbrechen an.

MB_YESNO

Anzeigen eines Meldungsfelds mit den Schaltflächen "Ja " und " Nein ".

MB_OK

Zeigt ein Meldungsfeld mit der Schaltfläche OK an.

Sie können ein optionales Symbol anzeigen, indem Sie nur eines der folgenden Flags festlegen.

MB_ICONHAND

Zeigt ein Stoppzeichensymbol an.

MB_ICONQUESTION

Zeigt ein Fragezeichensymbol an.

MB_ICONEXCLAMATION

Zeigt ein Ausrufezeichen an.

MB_ICONINFORMATION

Zeigt ein Symbol mit einem Kleinbuchstaben "i" in einem Kreis an.

iDefault

Typ: int

Der Wert, den die Funktion zurückgibt, wenn der Benutzer sich entschieden hat, dass das Meldungsfeld nicht erneut angezeigt wird. Wenn der Benutzer das Meldungsfeld nicht unterdrückt hat, wird das Meldungsfeld angezeigt, und die Funktion ignoriert iDefault.

[in] pszRegVal

Typ: LPCTSTR

Ein Zeiger auf eine NULL-endende Zeichenfolge, die einen eindeutigen Zeichenfolgenwert enthält, der dieser Nachricht zugeordnet werden soll. Um Konflikte mit von Microsoft verwendeten Werten zu vermeiden, sollte diese Zeichenfolge eine GUID enthalten. Diese Zeichenfolge darf REGSTR_MAX_VALUE_LENGTH Zeichen nicht überschreiten, einschließlich des abschließenden NULL-Zeichens.

Rückgabewert

Typ: int

Wenn der Benutzer bereits ausgewählt hat, das Meldungsfeld zu unterdrücken, gibt die Funktion sofort den iDefault zugewiesenen Wert zurück.

Wenn der Benutzer auf die Schaltfläche OK, Abbrechen, Ja oder Nein klickt, gibt die Funktion IDOK, IDCANCEL, IDYES oder IDNO zurück.

Wenn der Benutzer das Meldungsfeld durch Klicken auf die Schaltfläche X im Untertitel schließt, gibt die Funktion IDCANCEL zurück. Dieser Wert wird in diesem Fall auch dann zurückgegeben, wenn das flag MB_OKCANCEL nicht festgelegt wurde.

Wenn ein Fehler auftritt, lautet der Rückgabewert normalerweise –1. Unter bestimmten Bedingungen mit wenig Arbeitsspeicher kann die Funktion jedoch iDefault zurückgeben.

Hinweise

Sicherheitswarnung: Führen Sie keine gefährlichen Aktionen aus, wenn die Funktion entweder –1 oder iDefault zurückgibt. Wenn beim Versuch, das Meldungsfeld anzuzeigen, ein Fehler auftritt, gibt SHMessageBoxCheck –1 oder in einigen Fällen iDefault zurück. Solche Fehler können durch unzureichenden Arbeitsspeicher oder ressourcen verursacht werden. Wenn Sie einen dieser Rückgabewerte erhalten, sollten Sie sich darüber im Klaren sein, dass der Benutzer das Dialogfeld nicht unbedingt angezeigt hat und folglich keiner Aktion positiv zugestimmt hat.

Verwechseln Sie "Dieses Dialogfeld nicht anzeigen" nicht mit "Diese Antwort speichern". SHMessageBoxCheck bietet keine "Diese Antwort speichern"-Funktionalität. Wenn der Benutzer das Meldungsfeld erneut unterdrücken möchte, behält die Funktion nicht bei, auf welche Schaltfläche er geklickt hat. Stattdessen geben nachfolgende Aufrufe von SHMessageBoxCheck einfach den von iDefault angegebenen Wert zurück. Betrachten Sie das folgende Beispiel.


int iResult = SHMessageBoxCheck(hwnd, 
                                TEXT("Do you want to exit without saving?"),
                                TEXT("Warning"), 
                                MB_YESNO, 
                                IDNO,
                                TEXT("{d9108ba3-9a61-4398-bfbc-b02102c77e8a}");

Wenn der Benutzer In the future( In the future) auswählt, zeigen Sie mir dieses Dialogfeld nicht an, und klicken Sie auf die Schaltfläche Ja , SHMessageBoxCheck gibt IDYES zurück. Wenn dieser Code das nächste Mal ausgeführt wird, gibt SHMessageBoxCheck jedoch keine IDYES zurück, obwohl der Benutzer ursprünglich Ja ausgewählt hat. Stattdessen wird IDNO zurückgegeben, da dies der von iDefault angegebene Wert ist.

Die im Meldungsfeld angezeigte Standardschaltfläche sollte mit Ihrem iDefault-Wert übereinstimmen. Die fehlende Unterstützung für das MB_DEFBUTTON2-Flag bedeutet, dass iDefault auf IDOK festgelegt werden sollte, wenn Sie das MB_OK- oder MB_OKCANCEL-Flag angegeben haben. Der iDefault-Wert sollte auf IDYES festgelegt werden, wenn Sie das flag MB_YESNO festgelegt haben.

SHMessageBoxCheck zeichnet die Meldungsfelder auf, die der Benutzer unter dem folgenden Registrierungsschlüssel unterdrückt hat.

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  LowRegistry
                     DontShowMeThisDialogAgain

Hinweis

Der shlwapi.h-Header definiert SHMessageBoxCheck 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 Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile shlwapi.h
DLL Shlwapi.dll (Version 5.0 oder höher)