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 can not be made active until the modal dialog box is destroyed.

BCX_MDIALOG calls a user created callback function


 BEGIN MODAL DIALOG AS DlgProcName
 
 END DIALOG.

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.

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 dimensioned in the BEGIN MODAL DIALOG ... END DIALOG block, should be dimensioned 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.


 Syntax:

 hCtl = BCX_MDIALOG(DlgProcName, _
                       DlgTitle$, _
                      hWndParent, _ 
                           Xpos%, _ 
                           Ypos%, _ 
                          Width%, _
                         Height%, _
                     [,WinStyle%] _ 
                   [,ExWinstyle%] _
                     [,FontFace$] _
                     [,FontSize%])

 Parameters:

  • hCtl The default value returned by BCX_MDIALOG is 0, however, a specified value, instead, can be returned by using the Win32 API EndDialog function.

    Since a modal dialog box does not return until it is closed, returning a handle to the dialog box would be of little use. Specifying a return value in the second parameter of the Win32 API EndDialog function provides a handy way to pass back a user defined return value.

    For example, the value of IDButton1 returned by

    
     EndDialog(hWnd, IDButton1)
    
    

    could then be used like this

    
     RetVal = BCX_MDIALOG(...)
     IF RetVal = IDButton1 THEN 
      Do something ...
     ELSEIF RetVal = IDButton2 THEN
      Do something else ...
     END IF
    
    
  • DlgProcName Specifies the name
    
     BEGIN MODAL DIALOG AS DialogName
     
     END DIALOG
    
    
    callback function.
  • DlgTitle$ A string that specifies text to be placed as the title on the dialog box.
  • hWndParent Specifies the HWND type handle to the parent window of the dialog box being created.
  • 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.
  • 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.
  • Width% Specifies the width, in device units or, if the PIXELS optional parameter was specified in the GUI statement, in pixels, of the dialog being created.
  • Height% Specifies the height, in device units or, if the PIXELS optional parameter was specified in the GUI statement, in pixels, of the dialog being created.
  • WinStyle% [OPTIONAL] If the WinStyle% parameter is used, the default Window Style for a BCX_MDIALOG control,
    WS_POPUP | WS_SYSMENU | DS_MODALFRAME | WS_CAPTION
    is replaced with the value in WinStyle%. See your Win32 SDK or PSDK Reference help for more information about valid Dialog Box Template Styles for a dialog box. Note that if the optional FontFace parameter is used then the DS_SETFONT style is added automatically as an argument to the WinStyle% parameter.
  • ExWinstyle% [OPTIONAL] The default Extended Window Style for a BCX_MDIALOG box is 0. See your Win32 SDK or PSDK Reference help for the CreateWindowEx Function to get more information about valid Extended Window Styles for a BCX_MDIALOG box.
  • FontFace$ [OPTIONAL] The name of the typeface to use for the text in the dialog box client area and controls.
  • FontSize% [OPTIONAL] Specifies the point size of the font to use for the text in the dialog box client area and controls.

Remarks: Note well !!! You should always use the modal version, BCX_MDIALOG, for a dialog box based application.

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 will allow Dialog based apps to be setup as:


 FUNCTION WinMain
  FUNCTION = BCX_MDialog(...)
 END FUNCTION

Example: The following demo shows how a dialog box based application can be setup using the modal BCX_MDIALOG 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


 $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

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


 BEGIN DIALOG AS DlgProcName
 
 END DIALOG.

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.

Note well ! 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 dimensioned in the BEGIN DIALOG ... END DIALOG block, should be dimensioned 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.


 Syntax:

 hCtl = BCX_DIALOG(DlgProcName, _
                      DlgTitle$, _
                     hWndParent, _ 
                          Xpos%, _ 
                          Ypos%, _ 
                         Width%, _
                        Height%, _
                    [,WinStyle%] _ 
                  [,ExWinstyle%] _
                    [,FontFace$] _
                    [,FontSize%])

 Parameters:

  • hCtl The return value is a handle to the new dialog if the function succeeds. If the function fails, the return value is NULL.
  • DlgProcName Specifies the name to be used in the
    
     BEGIN DIALOG AS DlgProcName
     
     END DIALOG
    
    
    callback function.
  • DlgTitle$ A string that specifies text to be placed as the title on the dialog box.
  • hWndParent Specifies the HWND type handle to the parent window of the dialog box being created.
  • 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.
  • 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.
  • Width% Specifies the width, in device units or, if the PIXELS optional parameter was specified in the GUI statement, in pixels, of the dialog being created.
  • Height% Specifies the height, in device units or, if the PIXELS optional parameter was specified in the GUI statement, in pixels, of the dialog being created.
  • WinStyle% [OPTIONAL] If the WinStyle% parameter is used, the default Window Style for a BCX_DIALOG control,
    WS_POPUP | WS_BORDER | WS_SYSMENU | WS_VISIBLE | WS_CAPTION
    is replaced with the value in WinStyle%. See your Win32 SDK or PSDK Reference help for more information about valid Dialog Box Template Styles for a dialog box. Note that if the optional FontFace$ parameter is used then the DS_SETFONT style is added automatically as an argument to the WinStyle% parameter.
  • ExWinstyle% [OPTIONAL] The default Extended Window Style for a BCX_DIALOG box is 0. See your Win32 SDK or PSDK Reference help for the CreateWindowEx Function to get more information about valid Extended Window Styles for a BCX_DIALOG box.
  • FontFace$ [OPTIONAL] The name of the typeface to use for the text in the dialog box client area and controls.
  • FontSize% [OPTIONAL] Specifies the point size of the font to use for the text in the dialog box client area and controls.

Remarks: 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:


 '***********************************************************
  '  Demo by Mike Henning
  '  Feb. 2005
  '  Modified by P.Kort and Robert Wishlaw for the BCX_Help file.
  '***********************************************************
  
  $BCXVERSION "5.05.174"
  
  GUI "DialogTest"
  
  GLOBAL Form1 AS CONTROL
  
  SUB FORMLOAD
  
  Form1 = BCX_FORM("Dialog Test",0,0,110,110)
  BCX_BUTTON("Modal",Form1,98,5,10,100,16)
  BCX_BUTTON("Modeless",Form1,99,5,30,100,16)
  CENTER(Form1)
  SHOW(Form1)
  
  END SUB
  
  '----------------------------------------------------
  
  BEGIN EVENTS
  SELECT CASE CBMSG
    CASE WM_COMMAND
    IF CBCTLMSG = BN_CLICKED THEN
      IF CBCTL = 98 THEN
        BCX_MDialog(DialogOne,"BCX Modal Dialog",Form1,-110,-110,110,110)
      END IF
      IF CBCTL = 99 THEN
        BCX_DIALOG(DialogTwo,"BCX Modeless Dialog",Form1,110,110,110,110)
      END IF
    END IF
  END SELECT
  END EVENTS
  
  '----------------------------------------------------
  
  BEGIN MODAL DIALOG AS DialogOne
  
  SELECT CASE CBMSG
    CASE WM_INITDIALOG
      SHOW(hWnd)
  END SELECT
  
  END DIALOG
  
  '----------------------------------------------------
  
  BEGIN DIALOG AS DialogTwo
    
  SELECT CASE CBMSG
    CASE WM_INITDIALOG
      SHOW(hWnd)
  END SELECT
  
  END DIALOG