Previous pageNext pageTable of Contents Home page

Using custom dialog boxes

Corel SCRIPT lets you design your own dialog boxes to carry out actions you want. It offers a wide variety of standard controls to fill the dialog with - from simple buttons and text fields to advanced progress bars, image lists and others.

Corel SCRIPT supports two basic dialog types - static and dynamic. Static dialog boxes are dialogs that don't change their content (controls) while the dialog is open. This means that static dialog can't hide or disable a control when the user performs a certain action or change the contents of a control from the script. On the contrary, dynamic dialog box can change its appearance while its open - resize itself, change the contents of one control when the user selects another and so on. A special procedure is assigned to a dynamic dialog which defines the behavior of the dialog. This procedure is called an event handler.

Static dialogs are the only type of dialogs that is supported by Corel SCRIPT 6. Dynamic dialogs were introduced in version 7.

Both static and dynamic dialogs must be defined first, then they can be used in script. For definition of both types BEGIN DIALOG...END DIALOG commands are used. A series of control definition command are placed between these two lines. After the dialog is defined it can be used by calling the DIALOG function.


Static dialog boxes

To define a static dialog the commands with the following syntax must be used:

BEGIN DIALOG Name Left, Top, Width, Height, Title
    [dialog control statements]
END DIALOG

Here Name is the unique name that the dialog is identified with. Actually, Name could be treated as the name of the dialog. This name is used in the script to work with the dialog. Dialog identifier name corresponds to the same naming conventions as other script variable names. This name may be composed from letters "A".."Z", numbers "0".."9" or the underscore character ("_") and never should start with number.

Left and Top are horizontal and vertical coordinates of the upper left corner of the dialog respectively to the upper left corner of the screen. These values are measured in dialog units. One unit in the x-direction is equal to one-fourth of the dialog box base width unit. One unit in the y-direction is equal to one-eighth of the dialog box base height unit. The dialog box base units are computed from the height and width of the system font.

Width and Height are horizontal and vertical dimensions of the dialog. The more these values are the bigger the dialog appears.

Title is a string expression that defines a caption text displayed in the title bar of the dialog box.

You can omit Left and Top coordinates as well as dialog's Title. If you omit Left and Top coordinates, then the dialog is centered on the screen when displayed. Omission of Title means no title in the dialog box window (however the window still has a blue title bar but no text in it).

Dialog control statements define controls used in the dialog. A control is any user interface element used in dialog, be it a button, checkbox or text input field. CorelSCRIPT 7 supports over 20 different controls including:

* - Only available in CorelSCRIPT 7 and later

The following dialog example demonstrates all types of controls available.

The syntax for each separate dialog control statement differs depending on the control type being defined. Here follows the syntax description for each control in static dialog box. Note that the same control definition statement has different syntax in static and dynamic dialogs.

Most dialog control statements include control's coordinates and dimensions. The position of a control is measured in dialog units relative to the dialog's upper left corner (not including the title bar). Height and width are in dialog units as well.

The following CorelSCRIPT code defines the dialog shown above:

BEGIN DIALOG SampleDialog 132, 63, "Corel SCRIPT Dialog"
	OKBUTTON 37, 20, 66, 14
END DIALOG

Here we define the dialog 132 units wide and 63 units high. That's because we have omitted the dialog position in the declaration, so the dialog is automatically centered on the screen when displayed. The dialog's title is "Corel SCRIPT Dialog" and the dialog is associated with the identifier SampleDialog. Each time you need to refer to the dialog you should use this name. For example, to show the dialog, use the following code:

ret%=DIALOG(SampleDialog)

In the dialog definition, the statement OKBUTTON defines an OK button, that is 66 units wide, 14 units high and positioned 37 units away from the left edge of the dialog and 20 units from its top.

BITMAPBUTTON Left, Top, Width, Height, Array

A bitmap button is a usual push button except it has an image instead of a text on its top. Its Left, Top, Width and Height parameters specify the buttons position and size. Array must a string array of three elements containing the filenames (and paths) of images used to draw the button. Each array element specify an image for one of three button states - normal, depressed and focused. Note, that the image must represent the whole button not only its top side (the bitmap should contain the bevels as well).

The array used to specify button's images must be declared prior to defining the dialog.

Normal Usual button state. This image is used when the button is inactive
Depressed Depressed button. This image is used when the user presses and holds the mouse over it.
Focused Active button. The button with focus takes commands from the keyboard.

CorelSCRIPT requires only Windows bitmap files (.BMP and .RLE). No other image format could be used (.TIF, .GIF, .JPG, etc).

An example:

DIM OKBtn$(3)
OKBtn$(1)="C:\MyScript\NormalButton.bmp"
OKBtn$(2)="C:\MyScript\DepressedButton.bmp"
OKBtn$(2)="C:\MyScript\FocusedButton.bmp"

BEGIN DIALOG SampleDialog 132, 63, "Corel SCRIPT Dialog"
	BITMAPBUTTON 37, 20, 50, 14, OKBtn$
END DIALOG

ret%=DIALOG(SampleDialog)

This example displays the following dialog:

When a bitmap button is pressed, the dialog box closes and the DIALOG function returns the value corresponding to the button index (see later on for explanations).

CANCELBUTTON Left, Top, Width, Height

Cancel button just closes the dialog and discards any changes made in the dialog. Pressing Cancel button is the same as pressing the Close button () in the title bar of the dialog box. You can also hit Esc key to close the dialog discarding all data entered.

Left, Top, Width and Height define the button's size and position within the dialog.

Pressing Cancel button closes dialog and makes the DIALOG function to return 2. (See the end of this section for explanations).

CHECKBOX Left, Top, Width, Height, Text, Value

Check Box is a three state switch that can be unchecked, checked and undefined (grayed). Static dialog is always has three states to switch among. In dynamic dialogs you can make the check box control only two-state (checked/unchecked), allowing the user to skip the third, undefined, state.

When the user clicks a check box, the check box' state cycles through the three possible conditions.

Left, Top, Width and Height as usual determine the check box' dimensions and position. Text is a text expression defining the text drawn to the right of the check box. Value is a numeric variable that holds the state of the checkbox.

Check box state Variable value
Unchecked 0 ()
Checked 1 ()
Undefined 2 ()

You can assign a value to this variable before the dialog is displayed to define the initial check box' state. After the dialog is closed, this variable stores the current state of the check box:

DIM State$(0 to 2)

State$(0)="Unchecked"
State$(1)="Checked"
State$(2)="Undefined"

BEGIN DIALOG CheckBoxExample 126, 51, "Check Box Example"
	CHECKBOX  9, 7, 50, 10, "CheckBox1", CheckBox1Val%
	CHECKBOX  9, 19, 50, 10, "CheckBox2", CheckBox2Val%
	CHECKBOX  9, 31, 50, 10, "CheckBox3", CheckBox3Val%
	OKBUTTON  78, 6, 40, 14
	CANCELBUTTON  78, 26, 40, 14
END DIALOG

CheckBox1Val%=0
CheckBox2Val%=1
CheckBox3Val%=2

ret%=DIALOG(CheckBoxExample)

IF ret=1 THEN
	s$="Check Box 1 state: "+State$(CheckBox1Val%)+CHR(13)+ \\
	   "Check Box 2 state: "+State$(CheckBox2Val%)+CHR(13)+ \\
	   "Check Box 3 state: "+State$(CheckBox3Val%)
	
	Message s$
ENDIF

This example defines a dialog box with three check boxes, OK button and Cancel button. Prior to displaying the dialog, initial values are assigned to the check box state variables. First check box becomes unchecked (0), the second is checked (1) and the last is undefined (2). Then the dialog is displayed by calling to DIALOG function with the dialog name (CheckBoxExample) as the parameter:

After the user closes the dialog, you can use the check box state variables to analyze the state of the check boxes. In the above example, the following message box is displayed depending on the check box status:

In order to simplify the script, the array State$ is used to store the check box state strings ("Unchecked", "Checked" and "Undefined"). The array's boundaries are defined to be from 0 to 2. Then this array is used to form an output string and assign it to the variable s$. This string is displayed on the screen afterwargs by MESSAGE statement.

COMBOBOX Left, Top, Width, Height, Array, Value

Combo Box is a special combined control type that actually contains a list box and a text box. You can either select an item from the list box (it is automatically displayed in the text box at the top) or type the text in the text box directly. By the way, while you are typing the list box items are selected according to the first matched items.

Left and Top determine the placement of the combo box within the dialog. Width and Height set its size. Keep in mind, that the text box part of the control is always of the same height. It's only the list box that changes in height when you change the control's height.

If the list box contains too many items and they won't fit the list box, a vertical scroll bar is added to the right of the list box. So make sure you build the control wide enough for the items to be at least recognized.

Array is a string array name that holds all the items for the list box. The array must be declared before using it in the dialog definition. The number of items in the list is determined by the dimensions of the array as specified at the declaration stage (in the DIM statement).

Value is a string variable that holds the string entered in the text box of the control. Actually this is the return value for the combo box (its result).

DIM Color$(3)

Color$(1)="Red"
Color$(2)="Blue"
Color$(3)="Yellow"

BEGIN DIALOG Example1 104, 55, "ComboBox Example"
	COMBOBOX  5, 6, 50, 42, Color$, ComboValue$ 
	OKBUTTON  60, 6, 40, 14
END DIALOG

DIALOG Example1

Message "Text entered: "+ComboValue$

DDCOMBOBOX Left, Top, Width, Height, Array, Value

DDCOMBOBOX defines a Drop-Down Combo Box. The list box of this control is hidden by default. When you click on the down arrow button, the list pops up letting you select an item from the list.

 

All the parameters in DDCOMBOBOX statement have the same meaning as in COMBOBOX.

DDLISTBOX Left, Top, Width, Height, Array, Value

DDLISTBOX is much like the Drop-Down Combo Box except that its Text Box is read-only. You can't type any text in it. The only option is to select an item from the drop-down list that is displayed in the Text Box.

 

Left, Top, Width and Height define the size and position of the control. Array is a string array name which holds the list box elements. Value is a numeric variable that corresponds to the array element (i.e. list box item) selected. The actual value assigned to this variable is determined only by the position of the item selected from the list and has nothing to do with the lower and upper limits of the array defined in DIM statement. For example, even if the array has limits from 5 to 8 (i.e. declared with the statement DIM v$(5 to 8)), the Value variable will be assigned the value of 1 if the first item is selected in the list box, 2 if the second and so on but not 5, 6, etc.


To be continued. Proceed to the next page to read the rest of the Using custom dialog boxes section.


Previous pageNext pageTable of Contents Home page