Funzione SHMessageBoxCheckA (shlwapi.h)

[SHMessageBoxCheck è disponibile per l'uso nei sistemi operativi specificati nella sezione Requisiti. Potrebbe essere modificato o non disponibile nelle versioni successive.]

Visualizza una finestra di messaggio che consente all'utente di eliminare altre occorrenze. Se l'utente ha già scelto di eliminare la finestra di messaggio, la funzione non visualizza una finestra di dialogo e restituisce semplicemente il valore predefinito.

Sintassi

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

Parametri

[in, optional] hwnd

Tipo: HWND

Handle della finestra per il proprietario della finestra di messaggio. Questo valore può essere NULL.

[in] pszText

Tipo: LPCTSTR

Puntatore a una stringa con terminazione Null contenente il messaggio da visualizzare.

[in] pszCaption

Tipo: LPCTSTR

Puntatore a una stringa con terminazione Null contenente il titolo della finestra di messaggio. Se questo parametro è impostato su NULL, il titolo è impostato su Error!.

uType

Tipo: UINT

Flag che specificano il contenuto e il comportamento della finestra di messaggio. Questa funzione supporta solo un subset dei flag supportati da MessageBox. Se si usano flag non elencati di seguito, il comportamento della funzione non è definito.

È necessario specificare i pulsanti da visualizzare impostando uno e solo uno dei flag seguenti.

MB_OKCANCEL

Visualizzare una finestra di messaggio con OK e pulsanti Annulla.

MB_YESNO

Visualizzare una finestra di messaggio con Sì e nessun pulsante di.

MB_OK

Visualizzare una finestra di messaggio con un pulsante OK .

È possibile visualizzare un'icona facoltativa impostando uno e solo uno dei flag seguenti.

MB_ICONHAND

Visualizzare un'icona con segno di arresto.

MB_ICONQUESTION

Visualizzare un'icona punto interrogativo.

MB_ICONEXCLAMATION

Visualizzare un'icona punto esclamativo.

MB_ICONINFORMATION

Visualizzare un'icona con un "i" minuscolo in un cerchio.

iDefault

Tipo: int

Valore restituito dalla funzione quando l'utente ha scelto di non visualizzare nuovamente la finestra di messaggio. Se l'utente non ha scelto di eliminare la finestra di messaggio, viene visualizzata la finestra di messaggio e la funzione ignora iDefault.

[in] pszRegVal

Tipo: LPCTSTR

Puntatore a una stringa con terminazione Null contenente un valore stringa univoco da associare al messaggio. Per evitare conflitti con i valori usati da Microsoft, questa stringa deve includere un GUID. Questa stringa non deve superare REGSTR_MAX_VALUE_LENGTH caratteri di lunghezza, incluso il carattere Null di terminazione.

Valore restituito

Tipo: int

Se l'utente ha già scelto di eliminare la finestra di messaggio, la funzione restituisce immediatamente il valore assegnato a iDefault.

Se l'utente fa clic sull'OK, Annulla, Sìo Pulsante No, la funzione restituisce rispettivamente IDOK, IDCANCEL, IDYES o IDNO.

Se l'utente chiude la finestra di messaggio facendo clic sul pulsante X nella didascalia, la funzione restituisce IDCANCEL. Questo valore viene restituito in questo caso anche se il flag MB_OKCANCEL non è stato impostato.

Se si verifica un errore, il valore restituito è in genere –1. Tuttavia, in determinate condizioni di memoria insufficiente, la funzione potrebbe restituire iDefault.

Osservazioni

Avviso di sicurezza: Non eseguire azioni pericolose se la funzione restituisce –1 o iDefault. Se si verifica un errore quando si tenta di visualizzare la finestra di messaggio, SHMessageBoxCheck restituisce –1 o, in alcuni casi, iDefault. Tali errori possono essere causati da memoria o risorse insufficienti. Se si ottiene uno di questi valori restituiti, è necessario tenere presente che l'utente non ha necessariamente visualizzato la finestra di dialogo e di conseguenza non ha accettato positivamente alcuna azione.

Non confondere "Non visualizzare questa finestra di dialogo" con "Ricorda questa risposta". SHMessageBoxCheck non fornisce la funzionalità "Ricorda questa risposta". Se l'utente sceglie di eliminare nuovamente la finestra di messaggio, la funzione non mantiene il pulsante selezionato. Le chiamate successive di SHMessageBoxCheck semplicemente restituiscono il valore specificato da iDefault. Si consideri l'esempio seguente.

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

Se l'utente seleziona In futuro, non visualizzare questa finestra di dialogo e fare clic sul pulsante Sì, SHMessageBoxCheck restituisce IDYES. Tuttavia, alla successiva esecuzione di questo codice, SHMessageBoxCheck non restituisce IDYES, anche se l'utente ha selezionato Sì originariamente. Restituisce invece IDNO, perché è il valore specificato da iDefault.

Il pulsante predefinito visualizzato dalla finestra di messaggio deve accettare il valore iDefault. La mancanza di supporto per il flag di MB_DEFBUTTON2 significa che iDefault deve essere impostato su IDOK se è stato specificato il flag MB_OK o MB_OKCANCEL. Il valore iDefault deve essere impostato su IDYES se è stato impostato il flag MB_YESNO.

SHMessageBoxCheck registra le finestre di messaggio che l'utente ha scelto di eliminare nella chiave del Registro di sistema seguente:

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  DontShowMeThisDialogAgain

Fabbisogno