Funzione DialogBoxParamA (winuser.h)

Articolo
03/13/2024

Crea una finestra di dialogo modale da una risorsa modello di finestra di dialogo. Prima di visualizzare la finestra di dialogo, la funzione passa un valore definito dall'applicazione alla routine della finestra di dialogo come parametro lParam del messaggio WM_INITDIALOG . Un'applicazione può usare questo valore per inizializzare i controlli della finestra di dialogo.

Sintassi

INT_PTR DialogBoxParamA(
  [in, optional] HINSTANCE hInstance,
  [in]           LPCSTR    lpTemplateName,
  [in, optional] HWND      hWndParent,
  [in, optional] DLGPROC   lpDialogFunc,
  [in]           LPARAM    dwInitParam
);

Parametri

[in, optional] hInstance

Tipo: HINSTANCE

Handle per il modulo che contiene il modello di finestra di dialogo. Se questo parametro è NULL, viene usato l'eseguibile corrente.

[in] lpTemplateName

Tipo: LPCTSTR

Modello della finestra di dialogo. Questo parametro è il puntatore a una stringa di caratteri con terminazione Null che specifica il nome del modello di finestra di dialogo o un valore intero che specifica l'identificatore di risorsa del modello della finestra di dialogo. Se il parametro specifica un identificatore di risorsa, la parola di ordine elevato deve essere zero e la parola in ordine basso deve contenere l'identificatore. È possibile utilizzare la macro MAKEINTRESOURCE per creare questo valore.

[in, optional] hWndParent

Tipo: HWND

Handle per la finestra proprietaria della finestra di dialogo.

[in, optional] lpDialogFunc

Tipo: DLGPROC

Puntatore alla procedura della finestra di dialogo. Per altre informazioni sulla procedura della finestra di dialogo, vedere DialogProc.

[in] dwInitParam

Tipo: LPARAM

Valore da passare alla finestra di dialogo nel parametro lParam del messaggio WM_INITDIALOG .

Valore restituito

Tipo: INT_PTR

Se la funzione ha esito positivo, il valore restituito è il valore del parametro nResult specificato nella chiamata alla funzione EndDialog utilizzata per terminare la finestra di dialogo.

Se la funzione ha esito negativo perché il parametro hWndParent non è valido, il valore restituito è zero. La funzione restituisce zero in questo caso per la compatibilità con le versioni precedenti di Windows. Se la funzione ha esito negativo per qualsiasi altro motivo, il valore restituito è -1. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La funzione DialogBoxParam usa la funzione CreateWindowEx per creare la finestra di dialogo. DialogBoxParam invia quindi un messaggio di WM_INITDIALOG (e un messaggio di WM_SETFONT se il modello specifica lo stile DS_SETFONT o DS_SHELLFONT) alla routine della finestra di dialogo. La funzione visualizza la finestra di dialogo , indipendentemente dal fatto che il modello specifichi lo stile di WS_VISIBLE , disabilita la finestra del proprietario e avvia il proprio ciclo di messaggi per recuperare e inviare messaggi per la finestra di dialogo.

Quando la routine della finestra di dialogo chiama la funzione EndDialog , DialogBoxParam elimina definitivamente la finestra di dialogo, termina il ciclo di messaggi, abilita la finestra proprietario (se abilitata in precedenza) e restituisce il parametro nResult specificato dalla routine della finestra di dialogo quando viene chiamato EndDialog.

Nota

L'intestazione winuser.h definisce DialogBoxParam come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll
Set di API	ext-ms-win-ntuser-dialogbox-l1-1-1 (introdotto in Windows 8.1)