Share via

SHMessageBoxCheckA-Funktion (shlwapi.h)

  • Artikel

[SHMessageBoxCheck ist für die Verwendung in den Betriebssystemen verfügbar, die im Abschnitt Anforderungen angegeben sind. 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 SHMessageBoxCheckA(
  [in, optional] HWND   hwnd,
  [in]           LPCSTR pszText,
  [in]           LPCSTR pszCaption,
                 UINT   uType,
                 int    iDefault,
  [in]           LPCSTR 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-Zeichenfolge, die die anzuzeigende Nachricht enthält.

[in] pszCaption

Typ: LPCTSTR

Ein Zeiger auf eine NULL-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 und nur eines der folgenden Flags festlegen.

MB_OKCANCEL

Anzeigen eines Meldungsfelds mit den Schaltflächen OK und Abbrechen .

MB_YESNO

Zeigt ein Meldungsfeld mit den Schaltflächen Ja und Nein an.

MB_OK

Zeigt ein Meldungsfeld mit der Schaltfläche OK an.

Sie können ein optionales Symbol anzeigen, indem Sie nur eins und 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

Zeigen Sie ein Symbol mit einem Kleinbuchstaben "i" in einem Kreis an.

iDefault

Typ: int

Der Wert, den die Funktion zurückgibt, wenn der Benutzer sich dafür entschieden hat, dass das Meldungsfeld nicht erneut angezeigt wird. Wenn der Benutzer sich nicht für die Unterdrückung des Meldungsfelds entschieden hat, wird das Meldungsfeld angezeigt, und die Funktion ignoriert iDefault.

[in] pszRegVal

Typ: LPCTSTR

Ein Zeiger auf eine NULL-Zeichenfolge, die einen eindeutigen Zeichenfolgenwert enthält, der dieser Nachricht zugeordnet werden soll. Um Kollisionen 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 endenden 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 bzw. 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 zurückgegeben, auch wenn das MB_OKCANCEL-Flag nicht festgelegt wurde.

Wenn ein Fehler auftritt, ist 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 Anzeigen des Meldungsfelds 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 bewusst sein, dass der Benutzer das Dialogfeld nicht unbedingt angezeigt hat und daher keiner Aktion positiv zustimmte.

Verwechseln Sie "Dieses Dialogfeld nicht anzeigen" nicht mit "Diese Antwort merken". SHMessageBoxCheck bietet keine Funktion "Diese Antwort merken". Wenn der Benutzer das Meldungsfeld erneut unterdrückt, 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 zukunft 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 MB_YESNO-Flag 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
                  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 nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

   
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)