BCX_DIALOG or BCX_MDIALOG function

BCX_MDIALOG function

Purpose:

BCX_MDIALOG creates a modal dialog box and the system then makes the modal dialog box the active window. When a dialog box is modal, other dialogs of the same application cannot be put on top of it and the modal dialog box owner window cannot be made active until the modal dialog box is destroyed.

Syntax:

RetVal = BCX_MDIALOG(DlgProcName AS DLGPROC, _
                         DlgTitle AS STRING, _
                         hwndParent AS HWND, _
                            Xpos AS INTEGER, _
                            Ypos AS INTEGER, _
                           Width AS INTEGER, _
                          Height AS INTEGER  _
                     [, WinStyle AS INTEGER] _
                   [, ExWinStyle AS INTEGER] _
                      [, FontFace AS STRING] _
                     [, FontSize AS INTEGER])

Return Value:

Data type: INT_PTR
RetVal Contains -1 if the function fails and 0 if it succeeds. The successful value is returned when either the END DIALOG closes the callback function or the CLOSEDIALOG function is called.

Parameters:

Data type: DLGPROC
DlgProcName User defined name for the BEGIN MODAL DIALOG callback function.
BCX_MDIALOG calls a user created callback function that has this basic form
```
BEGIN MODAL DIALOG AS DlgProcName

END DIALOG
```
and which contains code that is responsible for monitoring and responding to messages and commands to and from the dialog box like mouse clicks, button presses, radio controls and so on.

The dialog box retains control until either the END DIALOG closes the callback function or the CLOSEDIALOG function is called or else until another application activates a window.

Between BEGIN and END, the keyword CLOSEDIALOG may be used to close a dialog box window in response to a button or keypress.

It is important to remember that this block is a callback routine which can be called several times before any specific task contained in the block is completed. For this reason, it is best that any variables which must be declared in the BEGIN MODAL DIALOG ... END DIALOG block, should be declared as STATIC or DIM RAW. When DIM or LOCAL are used, BCX emits code to automatically clear the variable to zero and so if a callback occurs before a task is completed the DIM or LOCAL variables will be cleared to zero and the task will fail.
Data type: STRING
DlgTitle A string that specifies text to be placed as the title on the dialog box.
Data type: HWND
hwndParent Specifies the HWND type handle of the parent window of the dialog box being created.
Data type: INTEGER
Xpos Specifies the initial horizontal position of the dialog being created. Xpos% is the x-coordinate of the upper-left corner of the tab control being created relative to the upper-left corner of the parent window's client area.
Data type: INTEGER
Ypos Specifies the initial vertical position of the dialog being created. Ypos%% is the initial y-coordinate of the upper-left corner of the dialog being created relative to the upper-left corner of the parent window's client area.
Data type: INTEGER
Width Specifies the width, in device units, of the dialog being created.
👉 The dialog event loop is expecting device units, regardless of what scaling was specified in the GUI statement.
Data type: INTEGER
Height Specifies the height, in device units, of the dialog being created.
👉 The dialog event loop is expecting device units, regardless of what scaling was specified in the GUI statement.
Data type: INTEGER
WinStyle [OPTIONAL] If the WinStyle parameter is used, the default Window Style, that is,
WS_POPUP | WS_SYSMENU | DS_MODALFRAME | WS_CAPTION
is replaced with the value in WinStyle. For more information, visit the Microsoft Dialog Box Styles webpage. and the Microsoft Window Styles webpage. Note that if the optional FontFace parameter is used then the DS_SETFONT style is added automatically as an argument to the WinStyle parameter.
Data type: INTEGER
ExWinstyle [OPTIONAL] The default Extended Window Style for a BCX_MDIALOG box is 0. For more information, visit the Microsoft Extended Window Styles webpage.
Data type: STRING
FontFace [OPTIONAL] The name of the typeface to use for the text in the dialog box client area and controls.
Data type: INTEGER
FontSize [OPTIONAL] Specifies the point size of the font to use for the text in the dialog box client area and controls.

Remarks:

For a dialog box based application, a modal BCX_MDIALOG is best.

When BCX_MDIALOG is detected within the WinMain function the following globals will be defined: BCX_HINSTANCE, BCX_SCALEX and BCX_SCALEY In addition to this BCX_HINSTANCE = hinst will be emitted immediately before the first occurrence of BCX_MDIALOG.

This allows Dialog based apps to be setup as:

FUNCTION WinMain
 FUNCTION = BCX_MDIALOG(...)
END FUNCTION

In dialogs (callback functions), when declaring variables that you wish to hold a value for the life of the function, it is best to avoid using DIM or LOCAL and instead use STATIC. The reason for doing this is that code is emitted to clear the variable each time the callback function calls itself, which would be many times while the dialog is open.

So instead of declaring as

DIM hwndHot AS CONTROL

it is better to use

STATIC hwndHot AS CONTROL

Example 1:

The following demo shows how a dialog box based application can be setup

$BCXVERSION "5.05.172"

GLOBAL  hEdit1     AS  HWND
GLOBAL  hButton1   AS  HWND
GLOBAL  hButton2   AS  HWND
GLOBAL  hStatic1   AS  HWND

FUNCTION WINMAIN ()
  FUNCTION = BCX_MDIALOG(InputBox,"InputBox App",0,157, 76, 146, 41)
END FUNCTION
 
BEGIN MODAL DIALOG AS InputBox
  LOCAL Txt$
  SELECT CASE Msg

    CASE WM_INITDIALOG
    hEdit1   = BCX_EDIT("BCX is cool!",hWnd,101, 3, 6, 69, 12)
    hButton1 = BCX_BUTTON("Okay",hWnd,102,4, 23, 40, 14)
    hButton2 = BCX_BUTTON("Cancel",hWnd, 104, 100, 23, 40, 14)
    hStatic1 = BCX_LABEL(" ",hWnd, 103, 78, 6, 64, 10)
    CENTER(hWnd)
 
    CASE WM_COMMAND
    IF CBCTLMSG = BN_CLICKED THEN
      IF CBCTL = 102 THEN      'clicked the okay button
       Txt$ = BCX_GET_TEXT$(hEdit1)
        BCX_SET_TEXT(hStatic1,Txt$)
      END IF
      IF CBCTL = 104 THEN      'clicked the cancel button
       CLOSEDIALOG
      END IF
    END IF

  END SELECT
END DIALOG

Example 2:

The following demo shows how a dialog box based application can be setup

$BCXVERSION "7.1.8"

GLOBAL hEdit1   AS HWND
GLOBAL hButton1 AS HWND
GLOBAL hButton2 AS HWND
GLOBAL hStatic1 AS HWND

FUNCTION WINMAIN ()
  FUNCTION = BCX_MDIALOG(InputBox,"InputBox App", _
                  0, 157, 76, 146, 61, 0, 0, "TAHOMA", 16)
END FUNCTION

BEGIN MODAL DIALOG AS InputBox
  LOCAL Txt$
  SELECT CASE Msg

    CASE WM_INITDIALOG
    hEdit1 = BCX_EDIT("BCX is cool!", hWnd, 101, 3, 6, 69, 30)
    hButton1 = BCX_BUTTON("Okay", hWnd, 102, 4, 43, 40, 14)
    hButton2 = BCX_BUTTON("Cancel", hWnd, 104, 100, 43, 40, 14)
    hStatic1 = BCX_LABEL(" ", hWnd, 103, 78, 6, 64, 30)
    BCX_SET_FONT(hStatic1, "TAHOMA", 12) 'for comparison
   CENTER(hWnd)

    CASE WM_COMMAND
    IF CBCTLMSG = BN_CLICKED THEN
      IF CBCTL = 102 THEN 'clicked the okay button
       Txt$ = BCX_GET_TEXT$(hEdit1)
        BCX_SET_TEXT(hStatic1, Txt$)
      END IF
      IF CBCTL = 104 THEN 'clicked the cancel button
       CLOSEDIALOG
      END IF
    END IF
  END SELECT
END DIALOG

BCX_DIALOG function

Purpose:

BCX_DIALOG creates a modeless dialog box and the system makes it the active window. The user or the application can change, at any time, the active modeless dialog box window, unlike a modal dialog box.

BCX_DIALOG calls a user created callback function that has this basic form

BEGIN DIALOG AS DlgProcName

END DIALOG

and which contains code that is responsible for monitoring and responding to messages and commands to and from the dialog box like mouse clicks, button presses, radio controls and so on.

The keyword CLOSEDIALOG may be used to close a dialog box window in response to a button or keypress.

👉 There is currently a limit of 32 unique modeless dialogs that may be open at any one time.

It is important to remember that this block is a callback routine which can be called several times before any specific task contained in the block is completed. For this reason, it is best that any variables, which must be declared in the BEGIN DIALOG ... END DIALOG block, should be declared as STATIC or DIM RAW. When DIM or LOCAL are used, BCX emits code to automatically clear the variable to zero and so if a callback occurs before a task is completed the DIM or LOCAL variables will be cleared to zero and the task will fail.