Previous pageNext pageTable of Contents Home page

Using Corel SCRIPT dialog boxes

Dialog boxes are very efficient user interface units. Scripts can use dialog boxes to get user input or to inform user about any events or conditions.

Earlier you already learned of two simple Corel SCRIPT dialog boxes - INPUTBOX for aquiring user input and MESSAGE for displaying a text message.

INPUTBOX(x$)

INPUTBOX is a string function that displays a dialog box prompting the user to supply any string information. The string entered bu the user is returned by the function and can be used in the script. The dialog box displayed by INPUTBOX function contains two buttons - OK and Cancel, an input text field where the user types the text and a prompt. The prompt is a custom text string specified by x$ as a parameter passed to INPUTBOX. x$ is any string expression that may be a combination of string functions, variables or constants.

If the user presses the OK button the text entered in the dialog's input field is returned as a result. If the Cancel button is pressed, the function returns an empty string.

Example:

a$=INPUTBOX("Enter a command (exit or quit to finish the script)")

The above command will display the following dialog when executed:

You can enter several lines of text using INPUTBOX function. For this just press Ctrl-Enter at the end of line to start a new one. Such multi-line text is returned as one text string delimiting each line with the combination of Carriage Return/Line Feed characters (the one with codes 13 and 10). For example, if you enter the following:

Line 1<Ctrl-Enter>Line 2<Enter>

the function INPUTBOX will return the string equal to the following:

"Line 1"+CHR(13)+CHR(10)+"Line 2"

MESSAGE x$

Displays a message string passed as a parameter to the procedure (x$). The procedure MESSAGE doesn't return any result so it should be used as any other procedures (as opposed to a function that returns a value).

The message is displayed in a window that has only one button (OK) to close the dialog box:

MESSAGE "Example"

You can insert a line break into the message, just use the Carriage Return character (ASCII code 13) for this:

MESSAGE "String 1"+CHR(13)+"String 2"

MESSAGE and INPUTBOX display very simple dialogs and they offer little flexibility. You can create your own dialog boxes that behaves depending on the user's actions. Corel SCRIPT provides great flexibility for creating custom dialog boxes that could meet any user's demands. However custom dialog boxes are very useful and flexible there are five more standard dialog boxes that could be used to implement some basic user interface procedures quickly and easily.

MESSAGEBOX(text$,title$,option%)

This function is used to display messages like MESSAGE procedure but it offers more options. First of all, you can specify the message text and message box title (the text displayed in the window's caption). Along with this you can insert several buttons in the dialog box (for example, OK, Yes/No, Abort/Retry/Ignore and so on). MESSAGEBOX function can display an icon in the message box. The function returns a numeric value depending on the button pressed by the user.

text$ is a text to be displayed in the message box. If it is too long to fit the message window, the text is wrapped. If you want to insert a line break, use Carriage Return character (ASCII 13) as a part of a text string.

title$ is a window title displayed in the window caption.

option% is a numeric expression representing the type of buttons to include in the box and an icon (if any) to appear beside the message. The option value is set adding the following values for button and icon types:

Button type:
0 OK only (used by default if a button is not specified)
1 OK/Cancel
2 Abort/Retry/Ignore
3 Yes/No/Cancel
4 Yes/No
5 Retry/Cancel

Icon type:

0 16 32 48 64
No icon
Stop Question Exclamation Information

The function MESSAGEBOX returns the following values depending on the button pressed by user:

Value Button pressed
1 OK
2 Cancel or the user presses Esc key to close the dialog
6 Abort
4 Retry
5 Ignore
6 Yes
7 No

Example:

v%=MESSAGEBOX("This dialog displays three buttons","MESSAGEBOX Example",51)

This command will display the following dialog box:

Here the number 51 is the superposition of 3 (Yes/No/Cancel buttons) and 48 (Exclamation icon).

The last parameter in call to MESSAGEBOX  (option) is optional and can be omitted. If so, zero is assumed (OK button only, no icon).

MESSAGEBOX can be used as a procedure as well. In this case, no parentheses for parameters should be used as in the following example:

MESSAGEBOX "File not found","Error",16

GETCOLOR(r%,g%,b%)

Displays Windows standard color selection dialog and assigns the RGB components of the color selected to the arguments (r, g, b for Red, Green, and Blue respectively). Color component values range from 0 to 255 each. GETCOLOR can be used both as a function and as a procedure (the same way as MESSAGEBOX). If GETCOLOR is a procedure, no parentheses are required. If GETCOLOR is used as a function, it returns a numeric value that indicates where the values assigned to r, g, b are valid. The values are invalid if the user presses the Cancel button. The function returns TRUE (-1) if the values are valid and FALSE (0) otherwise.

valid%=GETCOLOR(r%,g%,b%)
if valid then
  MESSAGEBOX "You selected the color: R="+STR(r)+", G="+STR(g)+", B="+STR(b),"Color chosen",64
else
  MESSAGE "CANCEL is pressed"
end if

The above code will display the Color dialog:

If the user presses the Cancel button, the variable valid% is assigned the value of 0 (FALSE) and the IF statement will execute the ELSE branch that displays "CANCEL is pressed" message. If the user presses the OK button, the THEN branch is executed and the following message is displayed:

GETFILEBOX(Filter$,Title$,Type%,DefFile$,DefExt$,DefFol$,BtnName$)

This function displays a standard Windows File Open or File Save As dialog box. Both dialog boxes allow users to choose a file from the file system. The GETFILEBOX function returns the selected filename and its full path, or an empty string if the user chooses Cancel. The GETFILEBOX statement by itself does not open or save a file; it only returns a string corresponding to the selected file.

Filter$ String expression specifying the filters to use in the dialog box. For the Open dialog box, the filters are listed in the Files of Type list box. For the Save As dialog box, the filters are listed in the Save as Type list box.

Filters are used to limit the number of file names listed in the window. For example, you can display only bitmap images or executable files. Each filter is specified by its name and default file mask that is used to filter file names. Filter name is displayed in the corresponding file type dropdown list in the dialog. Filter name must be separated from the file mask with the "|" character. No spaces should be used. For example, "Bitmap files|*.bmp" will display "Bitmap files in the list and will use "*.bmp" mask to display only files with BMP extension.

You can specify several file masks for a single filter separating them with semicolon (";"), e.g. "Bitmap files|*.bmp;*.tif;*.gif;*.cpt".

You can specify several filters to use separating from each other with "|" character. Example: "Bitmap files|*.bmp;*.tif;*.gif;*.cpt|Text files|*.txt;*.asc|All Files|*.*". This will create a list of three filters:

Filter Name Mask used
Bitmap files *.bmp;*.tif;*.gif;*.cpt
Text files *.txt;*.asc
All Files *.*
Title$ Text string specifying the title to display in the dialog box. If not specified, "Open" is displayed for an Open dialog box and "Save As" is displayed for a Save As dialog box.
Type% Numeric expression specifying the type of dialog box to display:
0 File Open dialog box (default if omitted)
1 File Save dialog box
DefFile$ String expression specifying the text to display in the File name text box of the dialog box. If not specified, the text box is empty.
DefExt$ String expression specifying the default extension to append to a File name if the user omits the extension.
DefFol$ String expression specifying the default folder used by the dialog box. If not specified, or the specified folder does not exist, the current folder is used.
BtnName$ String expression specifying a button name to override the Open or Save button in the dialog box. If not specified, the button's name remains unchanged.

Example:

Flt$="Bitmap files|*.bmp;*.tif;*.gif;*.cpt|Text files|*.txt;*.asc|All Files|*.*"
Filename$=GETFILEBOX(Flt$,"Select a file to import")

Displays the following Open dialog box:

Here a list of three file filters is used (the string is first assigned to the variable Flt$). The second parameter (the string "Select a file to import") is displayed in the window title. The rest of arguments are omitted assuming their default values. You may want to change the title of the "Open" dialog to "Import". You should use the last argument for this purpose. In this case you can't omit any preceding parameter, so you'll have to specify even empty strings:

Filename$=GETFILEBOX(Flt$,"Select a file to import",0,"","","","Import")

This command will display a dialog box and the "Open" button will be changed to "Import":

GETFOLDER(InitFolder$)

This function displays a Windows Choose Folder dialog box. The Choose Folder dialog box returns the folder and path a user chooses as a string. InitFolder is a string specifying the default path and folder to display in the dialog box. If not specified, the active folder is used.If the CANCEL button is clicked, an empty string is returned.

Folder$=GETFOLDER("C:\Windows")
if Folder<>"" then Message "Folder selected: "+Folder$

GETFONT(FaceName$,PointSize%,Weight%,Italic%,Underline%,StrikeOut%,Red%, Green%,Blue%)

Displays a standard Windows Font dialog box and returns the selected font settings.

FaceName Specifies a string variable that is passed the name of the selected font. You can also use this variable to set an initial value.
PointSize Specifies a numeric variable that is passed the font size in points. You can also use this variable to set an initial value. This parameter uses non-fractional values
Weight Specifies a numeric variable that is passed the font's weight setting (number of inked pixels per 1000 pixels). Common values and their corresponding names include:

100 Thin
200 Extra Light, Ultra Light
300 Light
400 Normal, Regular
500 Medium
600 Semi Bold, Demi Bold
700 Bold
800 Extra Bold, Ultra Bold
900 Black, Heavy

Most Windows fonts only use two weight settings: 400 (Normal) and 700 (Bold).

Italic Specifies a numeric variable that is passed the font's italic setting: TRUE (-1) if this setting is enabled; FALSE (0) otherwise.
Underline Specifies a numeric variable that is passed the font's underline setting: TRUE (-1) if this setting is enabled; FALSE (0) otherwise.
StrikeOut Specifies a numeric variable that is passed the font's strike out setting: TRUE (-1) if this setting is enabled; FALSE (0) otherwise.
Red Specifies the numeric variable that is passed the Red (RGB color model) setting of the selected font's color (0 - 255). You can also use this variable to set an initial value.
Green Specifies the numeric variable that is passed the Green (RGB color model) setting of the selected font's color (0 - 255). You can also use this variable to set an initial value.
Blue Specifies the numeric variable that is passed the Blue (RGB color model) setting of the selected font's color (0 - 255). You can also use this variable to set an initial value.

The function returns a numeric variable that is passed a value corresponding to whether the CANCEL button was clicked on the Font dialog box: FALSE (0) if the CANCEL button was clicked; otherwise TRUE (-1). If the CANCEL button is pressed, the value of the other variables don't change.

GETFONT can also be used as a procedure. In this case no paretheses are required and it doesn't return any value:

GETFONT FN$,PS%,Wt%,Italic%,Under%,Strike%,R%,G%,B%


What next?

On the next page you will learn about creating and using custom dialog boxes.


Previous pageNext pageTable of Contents Home page