Begin Dialog (statement)

Syntax

Begin Dialog DialogName [x],[y],width,height,title$ [,[.DlgProc] [,[PicName$] [,style]]]
 Dialog Statements
End Dialog

Description

Defines a dialog box template for use with the Dialog statement and function.

Comments

A dialog box template is constructed by placing any of the following statements between the Begin Dialog and End Dialog statements (no other statements besides comments can appear within a dialog box template):

 

Picture

OptionButton

OptionGroup

 

CancelButton

Text

TextBox

 

GroupBox

DropListBox

ListBox

 

ComboBox

CheckBox

PictureButton

 

PushButton

OKButton

 

 

The Begin Dialog statement requires the following parameters:

 

Parameter

Description

 

x, y

Integer coordinates specifying the position of the upper left corner of the dialog box relative to the parent window. These coordinates are in dialog units.

If either coordinate is unspecified, then the dialog box will be centered in that direction on the parent window.

 

width, height

Integer coordinates specifying the width and height of the dialog box (in dialog units).

 

DialogName

Name of the dialog box template. Once a dialog box template has been created, a variable can be dimensioned using this name.

 

title$

String containing the name to appear in the title bar of the dialog box. If this parameter specifies a zero-length string, then the name "Basic Control Engine" is used.

 

.DlgProc

Name of the dialog function. The routine specified by .DlgProc will be called by the script when certain actions occur during processing of the dialog box. (See DlgProc [prototype] for additional information about dialog functions.)

If this omitted, then the script processes the dialog box using the default dialog box processing behavior.

 

style

Specifies extra styles for the dialog. It can be any of the following values:

 

 

Value

Meaning

 

 

0

Dialog does not contain a title or close box.

 

 

1

Dialog contains a title and no close box.

 

 

2 (or omitted)

Dialog contains both the title and close box.

 

The script generates an error if the dialog box template contains no controls.

A dialog box template must have at least one PushButton, OKButton, or CancelButton statement. Otherwise, there will be no way to close the dialog box.

Dialog units are defined as ΒΌ the width of the font in the horizontal direction and 1/8 the height of the font in the vertical direction.

Any number of user dialog boxes can be created, but each one must be created using a different name as the DialogName. Only one user dialog box may be invoked at any time.

Expression Evaluation within the Dialog Box Template

The Begin Dialog statement creates the template for the dialog box. Any expression or variable name that appears within any of the statements in the dialog box template is not evaluated until a variable is dimensioned of type DialogName. The following example shows this behavior:

  Sub Main()

    MyTitle$ = "Hello, World"
    Begin Dialog MyTemplate 16,32,116,64,MyTitle$
      OKButton 12,40,40,14
    End Dialog
    MyTitle$ = "Sample Dialog"
    Dim dummy As MyTemplate
    rc% = Dialog(dummy)
  End Sub

The above example creates a dialog box with the title "Sample Dialog".

Expressions within dialog box templates cannot reference external subroutines or functions.

All controls within a dialog box use the same font. The fonts used for text and text box control can be changed explicitly by setting the font parameters in the Text and TextBox statements. A maximum of 128 fonts can be used within a single dialog, although the practical limitation may be less.

Example

This example creates an exit dialog box.

Sub Main()

  Begin Dialog QuitDialogTemplate 16,32,116,64,"Quit"
    Text 4,8,108,8,"Are you sure you want to exit?"
    CheckBox 32,24,63,8,"Save Changes",.SaveChanges
    OKButton 12,40,40,14
    CancelButton 60,40,40,14
  End Dialog
  Dim QuitDialog As QuitDialogTemplate
  rc% = Dialog(QuitDialog)
  Select Case rc%
  Case -1
      MsgBox "OK was pressed!"
    Case 1
      MsgBox "Cancel was pressed!"
  End Select
End Sub

See Also

CancelButton (statement); CheckBox (statement); ComboBox (statement); Dialog (function); Dialog (statement); DropListBox (statement); End Dialog (statement); GroupBox (statement); ListBox (statement); OKButton (statement); OptionButton (statement); OptionGroup (statement); Picture (statement; PushButton (statement); Text (statement); TextBox (statement); DlgProc (function).

Note

Within user dialog boxes, the default font is 8-point MS Sans Serif.

More information

B