DialogBox

La función DialogBox crea un cuadro de diálogo modal a partir de un recurso de plantilla de cuadro de diálogo. DialogBox no devuelve el control hasta que la función callback especificada termine el cuadro de diálogo modal con la llamada a la función EndDialog.

Sintaxis

int DialogBox(
    HANDLE hInstance,      // manipulador a la instancia de la aplicación
    LPCTSTR lpTemplate,    // identifica el recurso de cuadro de diálogo
    HWND hWndParent,       // manipulador a la ventana propietaria
    DLGPROC lpDialogFunc   // dirección del procedimiento de diálogo
   );

Parámetros:

hInstance: identifica una instancia del módulo cuyo fichero ejecutable contiene la plantilla del cuadro de diálogo.

lpTemplate: identifica la plantilla del cuadro de diálogo. Este parámetro puede ser la dirección de una cadena de caracteres terminada en cero que especifique el nombre de la plantilla o un valor entero que especifique el identificador de recurso de la plantilla. Si el parámetro se refiere a un identificador de recurso, su palabra de mayor peso debe ser cero y la de menor peso contendrá el identificador. Se puede usar la macro MAKEINTRESOURCE para crear este valor.

hWndParent: identifica la ventana a la que pertenece el cuadro de diálogo.

lpDialogFunc: apunta al procedimiento de diálogo. Para más información ver la función callback DialogProc.

Valor de retorno

Si la función tiene éxito, el valor de retorno será el parámetro nResult en la llamada a la función EndDialog usada para terminar el diálogo.

Si la función fracasa, el valor de retorno es -1.

Observaciones

La función DialogBox usa la función CreateWindowEx para crear el cuadro de diálogo. Entonces DialogBox envía un mensaje WM_INITDIALOG (y un mensaje WM_SETFONT si la plantilla especifica el estilo DS_SETFONT) al procedimiento de diálogo. La función muestra el cuadro de diálogo (independientemente de si la plantilla especifica el estilo WS_VISIBLE), desactiva la ventana propietaria y comienza su propio bucle de mensajes para recuperar y despachar los mensajes del cuadro de diálogo.

Cuando el procedimiento de diálogo llama a la función EndDialog, DialogBox destruye el cuadro de diálogo, termina el bucle de mensajes, activa la ventana padre (si antes estaba activa) y devuelve el parámetro nResult suministrado por el procedimiento de diálogo cuando llamó a EndDialog.

Sólo en Windows 95: el sistema puede soportar un máximo de 16364 manipuladores de ventanas.