Click above to get retro games delivered to your door ever month!

DialogBox()
Display and activate a modal dialog from a dialog resource
------------------------------------------------------------------------------

Syntax
DialogBox( [ <hInst> ] , <cnDlg>, [ <hWnd> ] , <bAction> )
         -->   nResult

Arguments
<hInst> is the handle of the instance of the application (as
returned by the _GetInstance() function), or a handle of a
DLL (as returned by the LoadLibrary() function).  The default
is the current application.

<cnDlg> is the name or numeric id of the dialog in the resource
file identified by <hInst>.

<hWnd> is the handle to the window that is to own the dialog
box.  The default is the currently selected window.

<bAction> is a code block to be executed every time Windows
sends a message to the dialog box.

Returns
If successful, the value returned is the numeric value specified
when EndDialog() was called to terminate the dialog.  Otherwise, -1
is returned.

Common reasons for getting -1 include not building the
resource into the EXE, and getting the <cnDlg> name/id wrong.

WINDOWS.CH defines some common values in the range 1 to 7 as
IDOK, IDCANCEL, IDABORT, IDRETRY, IDIGNORE, IDYES, and IDNO,
so you should probably not define your own return values in
that range.

Description
This function is used to display and activate a modal dialog
from a dialog resource.  (It is the resource equivalent of the
ModalDialog() function.)  The dialog resource is usually
stored in the application's EXE file, but can be in another
EXE or DLL.

The code block <bAction> is passed each message from Windows,
together with the associated parameters, as the dialog is
created, used, and terminated.  The code block should be as
follows:

          { | hDlg, nMsg, nwParam, nlParam |                ;
             DlgFunc( hDlg, nMsg, nwParam, nlParam ) }

The messages from Windows have 4 parameters:

          hDlg      the handle of the dialog window
          nMsg      the WM_* value identifying the message
          nwParam   depends on nMsg
          nlParam   depends on nMsg

The code block should return a value to indicate whether it
processed the message.  In practice, you'll probably just call
a function (as shown above), so it's up to the function to
behave correctly.

Most of the messages can be ignored, in which case the dialog
function should return zero (0).  However, the WM_INITDIALOG
message, which is sent before the dialog is made visible, is
different: you should only return zero if you use SetFocus()
to give the input focus to a particular control within the
dialog.  You should return a non-zero value (one (1) is
usually used) if you don't set the focus, in which case the
focus will be set by default (typically to the first control
with the WS_TABSTOP setting).  For this message, nwParam is
the handle of the control that will be given the focus by
default.

The other important message is WM_COMMAND, which is sent when
a control sends a notification message to its parent.
Examples of controls are buttons, list boxes, edit controls
and combo boxes.  The parent will be the dialog box itself
(identified by hDlg).

The numeric id of the control is passed in the nwParam
parameter.

The nlParam value is really two values joined together.  These
may be fetched using _LastLolParam(), which identifies the
handle of the control, and _LastHilParam(), which identifies
the notification code the control is sending (one of the BN_*,
CBN_*, EN_*, LBN_* values).  Alternatively, you can isolate
these values using C4W_LOWORD( nlParam ) and C4W_HIWORD( nlParam ).

A dialog created by this function should be terminated by
calling the EndDialog() function.  Do not use DestroyWindow().

If you have a data-driven application, you may still be able
to use resource dialogs, because you can alter dialogs during
the WM_INITDIALOG message.  Among other things, you can
enable/disable controls, hide them, and/or move them outside
the visible part of the dialog.   See the source\dialog.prg
sample for some ideas.

Example
See the files DIALOG.PRG, DIALOG.RC, DIALOG.CH, and DIALOG.RMK.
Also, a number of the other samples.