Chapter 11

See Graphic

Corel® PerfectScript™ Programming Commands




Corel® PerfectScript™ Programming Commands

Three new macro commands have been added: MacroCompile, MacroIsCompiled, and MacroPlay. See online Help for information about these commands. Also, the following commands have been changed: DialogAddControl, DialogDelete, FileFind, FileNameDialog, GetFileAttributes, MacroInfo, OLEAutomation, and SetFileAttributes. See online Help for information about these commands.

DialogAddBitmap

Purpose Add a bitmap control to a dialog box. After DialogLoad or DialogShow, bitmap controls can be added to a dialog created with the Dialog Editor.
 
Examples 
APPLICATION(A1; "WordPerfect"; Default; "US")
OnError (ErrorMsg)
DialogDefine ("Dialog1"; 50; 50; 200; 100; Percent! | OK! | Cancel!; "Dialog Example")
DialogAddPushButton("Dialog1"; "PushBttn1"; 153; 35; 38; 14; NonDefaultBttn!; "Add Ctrl 1")
DialogAddPushButton("Dialog1"; "PushBttn2"; 153; 55; 38; 14; NonDefaultBttn!; "Add Ctrl 2")
DialogShow ("Dialog1"; "WordPerfect"; Msg)
CallbackWait
Quit

Label(Msg)
If (Msg[5] = 274)
 DialogDestroy ("Dialog1")
 CallbackResume
 Return
Endif
Switch (Msg[3])
 CaseOf "OKBttn": MessageBox(x; "OK Button"; "You pressed OK"; IconInformation!)
 CaseOf "CancelBttn":
  DialogDestroy("Dialog1")
  CallBackResume
  Return
 CaseOf "PushBttn1":
  DialogAddBitmap ("Dialog1"; "BCtrl"; 10; 10; 50; 50; SizeBmpToCtl!; "c:\windows\cars.bmp")
 CaseOf "PushBttn2":
  RegionSetBitmap ("Dialog1.BCtrl"; "c:\windows\arcade.bmp")
EndSwitch
Return

Label (ErrorMsg)
MessageBox (x; "Error"; "You pressed Add Ctrl 2 before Add Ctrl 1"; IconInformation!)
Quit
 
Return Value Name of the control if successful, an empty string ("") if not. This same value is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddBitmap (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; [Style: enumeration]; FileName: string; [Name: string]; [TransparentColor: numeric])
 
Parameters
Dialog String The name or number of the dialog box to contain the bitmap control (see DialogDefine).
Control string A name or number that identifies the bitmap control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the bitmap.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the bitmap.
Width numeric (optional) The width of the bitmap control in dialog units.
Height numeric (optional) The height of the bitmap control in dialog units.
Style enumeration (optional) Specify how the bitmap is displayed.
SizeCtlToBmp!
SizeBmpToCtl!
Transparent!
FileName string The path and filename of a bitmap file, or resource file such as a .dll.
Name string (optional) Specify a bitmap in a resource file such as "#1".
TransparentColor numeric (optional) Any color between 0 and 16,777,215 (0 is black). Colors are based on RGB colors.

R=Red (0-255 in bits 0-7)

G=Green (0-255 in bits 8-15)

B=Blue (0-255 in bits 16-23)

DialogAddCheckBox

Purpose Add a check box control to a dialog box. After DialogLoad or DialogShow, a check box can be added to a dialog created with the Dialog Editor.
 
Examples Appendix A: 8041
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddCheckBox (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; Text: string; MacroVar: Varible; [Style: enumeration])
 
Parameters
Dialog string The name or number of the dialog box to contain the check box control (see DialogDefine).
Control string A name or number that identifies the check box control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the check box.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the check box.
Width numeric (optional) The width of the check box control in dialog units.
Height numeric (optional) The height of the check box control in dialog units.
Text string The text displayed to the right of the check box, unless TextOnLeft! style is used. See Style below.
MacroVar variable 1 is returned in this variable when check box is checked, and 0 when it is not checked. The default value is 0. If MacroVar is assigned a value greater than 0 before the check box is added, the check box is checked when the dialog box is displayed.
Style enumeration (optional) Checkbox styles are mutually exclusive (choose only one).
CheckboxAuto! Toggles between check and clear.
Checkbox! Can be one of two states: check or clear. See RegionSetCheck.
Checkbox3State! Can be one of three states: check, clear, or gray. See RegionSetCheck.
CheckboxAuto3State! Toggles between check, clear, and gray.
TextOnLeft! Positions text to the left of the check box.

DialogAddColorWheel

Purpose

Add a color wheel control to a dialog box, and return a number that represents the selected color when the dialog is dismissed. After DialogShow or DialogLoad, a color wheel can be added to a dialog created with the Dialog Editor.

The color selection consists of three color elements (red, green, and blue), separated into color values by the formula given below (see the MacroVar parameter below). These values are used in Windows programming to specify the color of a pen or brush.

 
Examples Appendix A: 8043
 
Return Value Name of the control if successful, an empty string ("") if not. This same value is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddColorWheel (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; MacroVar: variable)
 
Parameters
Dialog string The name or number of the dialog box to contain the color wheel control (see DialogDefine).
Control string A name or number that identifies the color wheel control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the color wheel control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the color wheel control.
Width numeric (optional) The width of the color wheel control in dialog units.
Height numeric (optional) The height of the color wheel control in dialog units.
MacroVar variable A number corresponding to a color selection is returned in this variable. This number can be divided into three other numbers which correspond to red, green, and blue. The formulas are:

vRed := MacroVar % 256 (vRed contains the red component, which is the remainder of MacroVar divided by 256)

vGreen := MacroVar / 256 % 256 (vGreen contains the green component, which is the remainder of MacroVar divided by 256 divided by 256)

vBlue := MacroVar / 256 / 256 (vBlue contains the blue component, which is the result of MacroVar divided by 256 divided by 256)

Preselect a color by assigning its value to MacroVar before adding the color wheel control.

DialogAddComboBox

Purpose

Add a combo box control to a dialog box. After DialogShow or DialogLoad, a combo box can be added to a dialog created with the Dialog Editor.

The combo box displays an edit box and a list box. You enter text in the edit box, or double-click a list item to insert it. Use DialogAddListItem to create list box items.

 
Examples Appendix A: 8043
 
Return Value Name of the item added to the combo box control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddComboBox (Dialog: string; Control: string; numeric; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; [Style: enumeration]; MacroVar: variable; [LimitText: numeric])
 
Parameters
Dialog string The name or number of the dialog box to contain the combo box control (see DialogDefine).
Control string A name or number that identifies the combo box control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the combo box.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the combo box.
Width numeric (optional) The width of the combo box control in dialog units.
Height numeric (optional) The height of the combo box control in dialog units.
Style enumeration

(optional) Combo box styles. The first three styles are exclusive (choose only one). Type | between enumerations to combine styles.

Example:

Sort! | Simple!

Explanation: Name search allowed on a sorted list box. A vertical scrollbar automatically appears when needed.

Dropdown! Display an edit control. Clicking the arrow to the right of the edit control displays a drop-down list box.
Droplist! Display a read-only edit control. Clicking the arrow to the right of the edit control displays a drop-down list box.
Simple! Display an edit control and an opened drop-down list box.
Unsorted! Items are not sorted.
Sort! Items are sorted alphabetically. If Sort! is used by itself, Simple! is the default combo box style. See DialogAddListItem.
WPChars! Non-keyboard characters allowed in a list item. See DialogAddListItem.
AutoHScroll! Automatic horizontal scrolling.
OEMConvert! Convert ANSI to OEM character set.
MacroVar variable The selected combo box item is returned in this variable. An item can be assigned to MacroVar before the control is added to a dialog.
LimitText numeric (optional) The maximum number of characters the edit control accepts, up to the number of characters that fit in the edit box. This number has no effect if you choose style DropList!.

DialogAddControl

Purpose

Add a custom control to a dialog box. After DialogShow or DialogLoad, a custom control can be added to a dialog created with the Dialog Editor.

The macro system knows nothing about custom controls. The user is responsible for all control message processing and queries.

 
Return Value Name of the control added to the dialog box if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddControl (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; Class: string; [Style: numeric]; WindowName: string; MacroVar: variable; [Instance: numeric])
 
Parameters
Dialog string The name or number of the dialog box to contain the custom control (see DialogDefine).
Control string A name or number that identifies the custom control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the custom control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the custom control.
Width numeric (optional) The width of the custom control in dialog units.
Height numeric (optional) The height of the custom control in dialog units.
Class string The name of the control class. Standard Windows classes include Button, ComboBox, Edit, ListBox, ScrollBar, and Static. Other controls such as Meters and Spin buttons must be defined in a DLL (see the Instance parameter below).
Style numeric (optional) A number that defines a valid style within the control Window class. For example, an edit control includes styles such as left, multiline, and password. The values for standard Windows styles are in the Windows SDK. If missing, no style bits are specified for this control.
WindowName string The control text. For example, the text that appears on a button control. Set this value to "" if the control does not accept text.
MacroVar variable The value returned by a control. This variable is retained for backward compatibility. You must query the control to retrieve needed values.
Instance numeric (optional) This parameter is retained for backward compatibility. If the DLL is loaded, the macro should be able to locate the control.

DialogAddCounter

Purpose

Add a counter control to a dialog box. After DialogShow or DialogLoad, a counter can be added to a dialog created with the Dialog Editor.

Click the counter button to insert a number in the edit box that is within a specified range (see the CountMin and CountMax parameters below).

 
Examples Appendix A: 8043
 
Return Value Name of the control if successful, an empty string ("") if not. This same value is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddCounter (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: Numeric]; [Format: enumeration]; MacroVar: variable; [CountMin: any]; [CountMax: any]; [CountStep: any])
 
Parameters
Dialog string The name or number of the dialog box to contain the counter control (see DialogDefine).
Control string A name or number that identifies the counter control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the counter control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the counter control.
Width numeric (optional) The width of the counter control in dialog units.
Height numeric (optional) The height of the counter control in dialog units.
Format enumeration

(optional) Specify counters of various unit values. When a value is entered without a unit of measure (24 instead of 24i), the value assumes the specified counter unit (not the default unit type). All the Display... enumerations are exclusive (use only one).

Type | between enumerations to combine styles. Use only one Display enumeration.

DisplayNormal! (-2147483647 to 2147483647)
DisplayWPU! (-2147483647 to 2147483647)
DisplayPoints! (-4294967.0 to 4294966.0)
DisplayCentimeters! (-151518.0 to 151519.0)
DisplayFixedPoint! (-32767.0 to 32767.0)
DisplayPercent! (-2147483647 to 2147483647)
DisplayInches! (-59651.0 to 59652.0)
DisplayInches2! (-59651.0 to 59652.0)
DisplayMillimeters! (-1515513.0 to 1515514.0)
DisplayI_Inches! (-59651.0 to 59652.0)
AutoHScroll!
NoScroll!
AutoValidate!
MacroVar variable The selected counter number is returned in this variable. A number can be assigned to MacroVar before the dialog is displayed.
CountMin any (optional) The minimum number that you can insert by clicking the counter button. Out-of-range values are replaced by the minimum value.
CountMax any (optional) The maximum number that you can insert by clicking the counter button. Out-of-range values are replaced by the minimum value.
CountStep any (optional) The increment and decrement step value. Out- of-range values are replaced by the minimum or maximum values.

DialogAddDate

Purpose Add a date to a dialog box. After DialogShow or DialogLoad, a date can be added to a dialog created with the Dialog Editor.
 
Examples Appendix A: 8097
 
Return Value Date added to the dialog box if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddDate (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; Style: enumeration; MacroVar: variable; [Year: numeric]; [Month: enumeration]; [Day: numeric])
 
Parameters
Dialog string The name or number of the dialog box to contain the date control (see DialogDefine).
Control string A name or number that identifies the date control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the date.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the date.
Width numeric (optional) The width of the date control in dialog units.
Height numeric (optional) The height of the date control in dialog units.
Style enumeration (optional) Determine whether the date is valid.
NoValidate! The contents of the edit field in the date control will not be validated, and will accept any string.
Validate! Validate the contents of the edit field in the date control for a valid date.
MacroVar variable The initial value when the control is displayed, and the value of the control when the dialog is dismissed.
Year numeric (optional) The number representing the year. Enter all 4 digits of the year, not just 2. The value 97 is the year 97, not 1997.
Month enumeration (optional)
January!
February!
March!
April!
May!
June!
July!
August!
September!
October!
November!
December!
Day numeric (optional) The number representing the day.

DialogAddEditBox

Purpose

Add an edit control to a dialog box. After DialogShow, an edit box can be added to a dialog created with the Dialog Editor.

The text entered in the edit box is returned in MacroVar when the dialog is dismissed (see MacroVar parameter).

 
Examples Appendix A: 8046
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax

string := DialogAddEditBox

(Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; [Style: enumeration]; MacroVar: variable; [LimitText: numeric])
 
Parameters
Dialog string The name or number of the dialog box to contain the edit control (see DialogDefine).
Control string A name or number that identifies the edit control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the edit control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the edit control.
Width numeric (optional) The width of the edit control in dialog units.
Height numeric (optional) The height of the edit control in dialog units.
Style enumeration (optional) The edit control styles. Type | between enumerations to combine styles. Not all combinations are possible.
Left! Text is left justified.
Right! Text is right justified if Multiline! style is set and WPChars! style is not set.
Center! Text is centered if Multiline! style is set and WPChars! style is not set.
VScroll! Edit control with a vertical scroll bar. Use with Multiline!
HScroll! Edit control with a horizontal scroll bar. Use with Multiline! or WPChars!.
WPChars! Can display WP Character box (press Ctrl+W). Non-keyboard characters are allowed.
Multiline! Multiple lines of input automatically wrap to the next line. Press Enter to cause the default button action (see DialogAddPushButton). If Enter2Hrtn! style is set in DialogDefine, press Enter to move the insertion point to the next line.
Uppercase! Text is automatically converted to uppercase.
Lowercase! Text is automatically converted to lowercase.
Password! Text is automatically displayed with asterisk (*) characters. The actual characters are stored by the edit control.
WordWrap! Text wraps if Multiline! is set.
SoftRet! Text contains Soft Return codes [SRt].
Attributes! Underline (press Ctrl+U) and italics (press Ctrl+I) are allowed if WPChars! style is set.
NoTabs! Tab codes are not exported with output.
NoWPChar! Cannot display WP Character dialog box. Non-keyboard characters are not allowed.
AutoVScroll! Automatic vertical scrolling.
AutoHScroll! Automatic horizontal scrolling.
OEMConvert! Convert ANSI to OEM character set.
ReadOnly! Edit control is read only.
WantReturn! Pressing Enter produces a hard return. Use with Multiline!.
MacroVar variable The text entered in the edit box is returned in this variable. Text can be assigned to MacroVar before the dialog is displayed.
LimitText numeric The maximum number of characters the edit control accepts.

DialogAddFileNameBox

Purpose

Add a filename edit control to a dialog box. After DialogShow or DialogLoad, a filename box can be added to a dialog created with the Dialog Editor.

The filename edit control consists of an edit control and a button control. Clicking the button displays the Select Directory or Select File dialog box depending on the control style (see the Style parameter).

 
Examples Appendix A: 8046
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddFileNameBox (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; [Style: enumeration]; MacroVar: variable; [DefaultDir: string]; [Template: string])
 
Parameters
Dialog string The name or number of the dialog box to contain the filename edit control (see DialogDefine).
Control string A name or number that identifies the filename edit control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the filename edit control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the filename edit control.
Width numeric (optional) The width of the filename edit control in dialog units.
Height numeric (optional) The height of the filename edit control in dialog units.
Style enumeration (optional) The filename edit control styles. Default: FilesAndDirs!. Type | between enumerations to combine styles.
FilesAndDirs! Directories and filenames are allowed.
DirOnly! Only directories are allowed.
FileDoesntHaveToExist!
MacroVar variable The directory or filename entered in the edit box is returned in this variable. A name can be assigned to MacroVar before the macro is displayed.
DefaultDir string (optional) The default directory when the Select File dialog box is displayed.
Template string (optional) The filenames to display in the Select File dialog box. For example, "*.*" (all files) and "*.bat" (all batch files).

DialogAddFrame

Purpose

Add a frame to a dialog box. After DialogShow or DialogLoad, a frame can be added to a dialog created with the Dialog Editor.

You can combine frame styles by creating two frames the same size and at the same position. For example, you can create a black frame and a white-filled frame (see the Control and Style parameters). You can also create custom controls by combining frames and QuickSpots (see DialogAddHotSpot and DialogShow).

 
Examples Appendix A: 8047
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddFrame (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; [Style: enumeration])
 
Parameters
Dialog string The name or number of the dialog box to contain the frame control (see DialogDefine).
Control string A name or number that identifies the frame control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the frame control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the frame control.
Width numeric (optional) The width of the frame control in dialog units.
Height numeric (optional) The height of the frame control in dialog units.
Style enumeration (optional) The frame styles. Type | between enumerations to combine styles. Not all combinations are possible.

Examples:

Frame! | White!

Explanation: White frame is displayed.

Filled! | White!

Explanation: White-filled frame is displayed.

Frame! Frame only.
Black! Black frame.
Gray! Gray frame. Gray is the default DeskTop color of the Windows Default color scheme. To select a different color, choose Colors in the Windows Control Panel.
White! White frame.
Filled! Filled frame.

DialogAddGroupBox

Purpose

Draw a rectangle around related dialog controls such as buttons. After DialogShow or DialogLoad, a group box can be added to a dialog created with the Dialog Editor.

Grouping related controls helps narrow user options.

 
Examples Appendix A: 8048
 
Return Value

Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.

 
Syntax

string := DialogAddGroupBox

(Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; Title: string)
 
Parameters
Dialog string The name or number of the dialog box to contain the group box control (see DialogDefine).
Control string A name or number that identifies the group box control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the group box control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the group box control.
Width numeric (optional) The width of the group box control in dialog units.
Height numeric (optional) The height of the group box control in dialog units.
Title string The title displayed at the top-left corner.

DialogAddHLine

Purpose

Add a horizontal line to a dialog box. After DialogShow or DialogLoad, a horizontal line can be added to a dialog created with the Dialog Editor.

 
Examples Appendix A: 8048
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddHLine (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Length: numeric])
 
Parameters
Dialog string The name or number of the dialog box to contain the horizontal line control (see DialogDefine).
Control string A name or number that identifies the horizontal line control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the horizontal line control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the horizontal line control.
Length numeric (optional) The length of the horizontal line control in dialog units.

DialogAddHotSpot

Purpose

Create an invisible area (QuickSpot) in a dialog box that closes the dialog box when clicked. After DialogShow or DialogLoad, a QuickSpot can be added to a dialog created with the Dialog Editor.

Other responses are possible when you use DialogAddHotSpot with a callback function (see DialogShow).

To create a QuickSpot within a frame (see DialogAddFrame), overlap size and position parameters.

 
Examples Appendix A: 8045
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax

string := DialogAddHotSpot

(Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; [Style: enumeration])
 
Parameters
Dialog string The name or number of the dialog box to contain the QuickSpot control (see DialogDefine).
Control string A name or number that identifies the QuickSpot control (the "Named region" of a control created with the Dialog Editor). The Control value is returned in the implicit variable MacroDialogResult (see DialogAddPushButton or DialogDefine) if the user chooses the QuickSpot to dismiss the dialog box.
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the QuickSpot control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the QuickSpot control.
Width numeric (optional) The width of the QuickSpot control in dialog units.
Height numeric (optional) The height of the QuickSpot control in dialog units.
Style enumeration (optional) The QuickSpot styles.
Click! Single click closes dialog box.
DblClick! Double click closes dialog box.

DialogAddIcon

Purpose Add an icon to a dialog box. After DialogShow or DialogLoad, an icon can be added to a dialog created with the Dialog Editor.
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddIcon (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; IconName: string; [Instance: numeric])
 
Parameters
Dialog string The name or number of the dialog box to contain the icon control (see DialogDefine).
Control string A name or number that identifies the icon control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the icon control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the icon control.
Width numeric (optional) The width of the icon control in dialog units.
Height numeric (optional) The height of the icon control in dialog units.
IconName string The name of an icon in a DLL. If an icon is identified by a number, precede the number with a pound sign (#). For example, "#160".
Instance numeric (optional) The handle of the DLL that contains the icon. The PerfectFit default is 0. DLLLoad returns the handle in a variable.

DialogAddListBox

Purpose

Add a list box control to a dialog box. After DialogShow or DialogLoad, a list box can be added to a dialog created with the Dialog Editor.

The item you choose is returned in MacroVar (see the MacroVar parameter). Use DialogAddListItem to create list box items.

 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddListBox (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; [Style: enumeration]; MacroVar: variable)
 
Parameters
Dialog string The name or number of the dialog box to contain the list box control (see DialogDefine).
Control string A name or number that identifies the list box control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the list box control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the list box control.
Width numeric (optional) The width of the list box control in dialog units.
Height numeric (optional) The height of the list box control in dialog units.
Style enumeration (optional) The list box control styles. Type | between enumerations to combine styles.

Examples:

Sort! | NameSearch!

Explanation: Name search is allowed on a sorted list box. A vertical scrollbar automatically appears when needed.

Sort! | NameSearch! | MultiColumn!

Explanation: Name search is allowed on a sorted list box. Items automatically roll in other columns as needed. A horizontal scrollbar automatically appears when needed.

Unsorted! Items are listed in the order in which they are defined. Type a keyboard character to give the input focus to the first item that begins with that character. A vertical scrollbar automatically appears when needed. See DialogAddListItem.
Sorted! Default. Items are sorted alphabetically. Type a keyboard character to give the input focus to the first item that begins with that character. See DialogAddListItem.
NameSearch! Item search is allowed. Begin typing the name of an item to select. An edit control is displayed above the list box, and the input focus is given to the item that most closely matches the characters you type.
MultiColumn! Items automatically roll into other columns as needed. A horizontal scrollbar automatically appears when needed. Column width is set by Windows.
WPChars! Non-keyboard characters are allowed in a list item. See DialogAddListItem.
ExtendedSelection! Click an item, press shift key and select another item. Selects all items in between.
MultipleSelection! Click items to select or deselect.
Checkboxes! List the box items have check boxes. Use with WPChars!.
MacroVar variable The selected list box item is returned in this variable. An item can be assigned to MacroVar before the dialog is displayed. The item is highlighted (selected) if it exists in the control's list of items. Otherwise, it is ignored.

DialogAddListItem

Purpose Creates a list item(s) for DialogAddComboBox and DialogAddListBox. After DialogShow, a list item(s) can be added to a list box in a dialog created with the Dialog Editor.
 
Examples Appendix A: 8049
 
Return Value Index (position) where the item was added to the list if successful, or -1 if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
numeric := DialogAddListItem (Dialog: string; Control: string; {Item: string; ...})
 
Parameters
Dialog string The name or number of the dialog box to contain the list item (see DialogDefine).
Control string The name or number of the control to contain the list item (the "Named region" of a control created with the Dialog Editor).
Item string

(repeating) One or more list items separated by a semicolon. Use the NToC programming command to include non-keyboard characters in a list item for DialogAddComboBox and DialogAddListBox, when the WPChars! style is set. For example,

DialogAddListItem(1000; 100; "Sample 1"; "Sample 2" + NToC(5;10))

DialogAddProgress

Purpose Add a progress indicator to a dialog box. After DialogShow or DialogLoad, a progress indicator control can be added to a dialog created with the Dialog Editor. See RegionSetProgressPercent.
 
Examples Appendix A: 8098
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax

string := DialogAddProgress

(Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric])
 
Parameters
Dialog string The name or number of the dialog box to contain the progress indicator control (see DialogDefine).
Control string A name or number that identifies the progress indicator control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the progress indicator.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the progress indicator.
Width numeric (optional) The width of the progress indicator in dialog units.
Height numeric (optional) The height of the progress indicator in dialog units.

DialogAddPushButton

Purpose

Add a push button to a dialog box. After DialogShow or DialogLoad, a push button can be added to a dialog created with the Dialog Editor.

When you choose a user-defined push button or QuickSpot, the Control parameter value of the button or QuickSpot is returned in the implicit variable MacroDialogResult (see DialogDefine). Other controls return the following Control parameter values: 1 for OK, 2 for Cancel, 2 for Close (system menu box), 2 if you double-click the system menu box, 2 if you press Alt+F4 or Esc.

 
Examples Appendix A: 8048
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddPushButton (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; [Style: enumeration]; ButtonText: string)
 
Parameters
Dialog string A name or number that matches the Dialog parameter of the dialog box to contain the push-button control (see DialogDefine).
Control string A name or number that identifies the push- button control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the push- button control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the push-button control.
Width numeric (optional) The width of the push-button control in dialog units.
Height numeric (optional) The height of the push button control in dialog units.
Style enumeration (optional) The push button styles.
NonDefaultBttn! Create a push button.
DefaultBttn! Create a default push button, with a heavy black border, that dismisses the dialog box. Press Enter to choose the default button. If Enter2HRtn! style is specified in DialogDefine, pressing Enter in a multiline edit control produces a hard return rather than the default button action.
OKBttn! Create a push button with ID OK style.
CancelBttn! Create a push button with ID Cancel style.
HelpBttn! Create a Help push button.
ButtonText string The text displayed on the push button.

DialogAddRadioButton

Purpose

Add a radio button to a dialog box. After DialogShow or DialogLoad, a radio button can be added to a dialog created with the Dialog Editor.

Radio buttons represent mutually exclusive choices. Selecting one radio button deselects another. Group them together by a control such as a group box or horizontal or vertical line. For multiple selections, see DialogAddCheckBox.

 
Examples Appendix A: 8048
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddRadioButton (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; ButtonText: string; MacroVar: variable; [Style: enumeration])
 
Parameters
Dialog string The name or number of the dialog box to contain the radio-button control (see DialogDefine).
Control string A name or number that identifies the radio- button control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the radio-button control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the radio-button control.
Width numeric (optional) The width of the radio-button control in dialog units.
Height numeric (optional) The height of the radio-button control in dialog units.
ButtonText string The text displayed by the radio button (see Style below).
MacroVar variable button is selected, 0 if not. The default value is 0. If MacroVar is assigned a value greater than 0 before the macro compiles, the radio button is automatically selected.
Style enumeration (optional)
Radio! Button is not checked. Use RegionSetCheck in a callback function to check or uncheck. See DialogShow.
RadioAuto! Normal radio button.
RadioLeft! Positions text to the left of the radio button.

DialogAddScrollBar

Purpose

Adds a horizontal or vertical scroll bar to a dialog box. After DialogShow or DialogLoad, a scroll bar can be added to a dialog created with the Dialog Editor.

A callback function (see DialogShow) can receive Windows WM_HSCROLL and WM_VSCROLL messages from DialogAddScrollBar.

For more information, refer to your Windows documentation.

 
Examples Appendix A: 8050
 
Return Value Name that identifies the scroll bar control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddScrollBar (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; [Style: enumeration]; MacroVar: variable; [Minimum: numeric]; [Maximum: numeric]; [Step: numeric])
 
Parameters
Dialog string The name or number of the dialog box to contain the scroll bar control (see DialogDefine).
Control string A name or number that identifies the scroll bar control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the scroll bar control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the scroll bar control.
Width numeric (optional) The width of the scroll bar control in dialog units (0 for vertical scroll bar).
Height numeric (optional) The height of the scroll bar control in dialog units (0 for horizontal scroll bar).
Style enumeration

(optional) The scroll bar thumb position and type styles. If missing, Top! | vScroll! is used. Type "|" between enumerations to combine styles. Not all combinations are possible.

Examples:

Left!| VScroll!

Explanation: Creates a standard-size vertical scroll control on the left side of the window defined by Left, Top, Width, and Height.

Right! | HScroll!

Explanation: Creates a standard-size vertical scroll control on the right side of the window defined by Left, Top, Width, and Height.

Vscroll! A vertical scroll control that occupies the entire window defined by Left, Top, Width, and Height.

Hscroll! works the same as VScroll!, but uses the Top! and Bottom! styles.

Left!
Top!
Right!
Bottom!
VScroll! Create a vertical scroll bar.
HScroll! Create a horizontal scroll bar.
MacroVar variable The position of the thumb is returned in this variable. To pre-select a thumb position, initialize MacroVar to the desired position. Default: the minimum position.
Minimum numeric (optional) The minimum thumb position (default). If the maximum position is 6 and the minimum position is 1, there are six positions on the scroll bar. If the maximum position is 6 and the minimum position is 2, there are five positions on the scroll bar.
Maximum numeric (optional) The maximum thumb position. See the Minimum parameter.
Step numeric (optional)

DialogAddText

Purpose Display a line of text in a dialog box. After DialogShow or DialogLoad, text can be added to a dialog created with the Dialog Editor.
 
Examples Appendix A: 8041
 
Return Value Text added to the dialog box if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddText (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; [Style: enumeration]; Text: string)
 
Parameters
Dialog string The name or number of the dialog box to contain the text control (see DialogDefine).
Control string A name or number that identifies the text control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the text control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the text control.
Width numeric (optional) The width of the text control in dialog units. This parameter determines how much horizontal space the control occupies, not the text width which is fixed by the system.
Height numeric (optional) The height of the text control in dialog units. This parameter determines how much vertical space the control occupies, not the text height which is fixed by the system.
Style enumeration (optional) The text control styles. Type | between enumerations to combine styles. Not all combinations are possible.

Examples:

Left! | RecessBox!

Explanation: Text is left justified in a recess box.

Center! | ShadowBox!

Explanation: Text is centered in a shadow box.

Left! Left justified.
Right! Right justified unless WPChars! style is set.
Center! Centered inside Width parameter value unless WPChars! style is set.
RecessBox! Recessed background.
ShadowBox! Shadowed background.
WPChars! Non-keyboard characters are allowed. See the Text parameter.
Multiline! Text wraps if WPChars! is set.
Filename! Ellipsis truncate path and filename to the length of the Width parameter.
NoPrefix! The & character is not interpreted as an accelerator prefix (displays in the text).
Text string

The text to display on the dialog box. Use the NToC programming command to display a non- keyboard character. For example,

Text: "A bullet character " + NToC(4; 0)

DialogAddViewer

Purpose Add a window to a dialog box for viewing files. The contents of the specified file are displayed in the viewer.
 
Examples Appendix A: 8046
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogAddViewer (Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Width: numeric]; [Height: numeric]; [Filename: string])
 
Parameters
Dialog string The name or number of the dialog box to contain the viewer control (see DialogDefine).
Control string A name or number that identifies the viewer control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the viewer control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the viewer control.
Width numeric (optional) The width of the viewer control in dialog units.
Height numeric (optional) The height of the viewer control in dialog units.
Filename string (optional) The path and name of a file to view.

DialogAddVLine

Purpose Add a vertical line to a dialog box. After DialogShow or DialogLoad, a vertical line can be added to a dialog created with the Dialog Editor.
 
Examples Appendix A: 8048
 
Return Value Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax

string := DialogAddVLine

(Dialog: string; Control: string; [Left: numeric]; [Top: numeric]; [Length: numeric])
 
Parameters
Dialog string The name or number of the dialog box to contain the vertical line control (see DialogDefine).
Control string A name or number that identifies the vertical line control (the "Named region" of a control created with the Dialog Editor).
Left numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the vertical line control.
Top numeric (optional) The number of dialog units from the top of the dialog box to the top of the vertical line control.
Length numeric (optional) The length of the vertical line in dialog units.

DialogControlQuery

Purpose Get the value of a control, or of all controls in a dialog.
 
Return Value True if successful, False if not.
 
Syntax
boolean := DialogControlQuery (Dialog: string; [Control: string]; [MacroVar: variable])
 
Parameters
Dialog string The name or number of the dialog box from which to get the value of a control or controls (see DialogDefine).
Control string (optional) A name or number of a control. If missing, the value of all the associated variables are updated.
MacroVar variable (optional) The value of Control is returned in this variable. This variable does not become the associated variable for the control. If missing, the control's associated variable is updated.

DialogControlUpdate

Purpose Update a dialog control or controls from a value.
 
Return Value True if successful, False if not.
 
Syntax
boolean := DialogControlUpdate (Dialog: string; [Control: string]; [Value: any])
 
Parameters
Dialog string The name or number of the dialog box in which to update a control (see DialogDefine).
Control string (optional) The name or number of a control to update. If missing, all controls are updated from the variables associated with the controls when they were created.
Value any (optional) Value used to update a control(s). If missing, Control is updated from the variable associated with it when it was created.

DialogDefine

Purpose

Assemble dialog data in memory. Use DialogShow to create and display the dialog box.

Dialog names are limited to 25 characters.

Dialog sizes do not include caption and border space (in Windows 95, dialog captions and borders can be sized by the user).

The value of the control that dismisses a dialog box is returned in an implicit variable named MacroDialogResult: 1 for OK, 2 for Cancel, 2 for Close (system menu box), 2 if you double-click the system menu box, 2 if you press Alt+F4 or Esc. It also returns the value of the Control parameter of a user-defined push button or QuickSpot (see DialogAddPushButton and DialogAddHotSpot).

MacroDialogResult is replaced or destroyed when you close a dialog box or call DialogDestroy. To save its value, assign it to a variable. For example, vResult := MacroDialogResult.

Dialog boxes are positioned and sized in dialog units. A vertical unit equals 1/8 of the font height, and a horizontal unit equals 1/4 of the font width.

 
Examples Appendix A: 8041
 
Return Value Name of the dialog if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
 
Syntax
string := DialogDefine (Dialog: string; Left: numeric; Top: numeric; Width: numeric; Height: numeric; Style: enumeration; Caption: string)
 
Parameters
Dialog string A name or number that identifies the dialog box. This name or number is used by DialogShow and by DIALOGADD commands.
Left numeric The number of dialog units from the left side of the screen to the left side of the dialog box. When used with Percent! (see Style parameter), this number is a percentage of the screen width minus the width of the dialog box.
Top numeric The number of dialog units from the top of the screen to the top of the dialog box. When used with Percent! (see the Style parameter), this number is a percentage of the screen height minus the height of the dialog box.
Width numeric The width of the dialog box in dialog units.
Height numeric The height of the dialog box in dialog units.
Style enumeration The dialog box styles. Type | between enumerations to combine styles. Not all combinations are possible.

Example:

OK! | Percent! | NoTitle!

Explanation: Creates a modal dialog box without a title, and positions it in the center of the screen.

OK! Create an OK button.
Cancel! Create a Cancel button.
Percent! Set Top and Left parameters to a percentage of the screen width or height minus the width or height of the dialog box. Use 50 to display the dialog box in the center of the screen.
NoFrame! Create a dialog box without a frame. Style has no effect in Windows 95.
Sizeable! Resizing of the dialog box is allowed.
NoTitle! Remove the caption (title) bar.
Modeless! Dialog box can lose input focus without closing. The Corel WordPerfect command InhibitInput must be Off!. Default is modal dialog box.
Enter2HRtn! Press Enter in a multiline edit control (see DialogAddEditBox) to move the insertion point to the next line. This does not cause the default button action (see DialogAddPushButton).
NoCloseBox!
Caption string The text displayed in the caption (title) bar.

DialogDelete

Purpose

Delete a (binary form) dialog from the prefix packet area of the current macro file.

 
Return Value Return True if successful, False if not.
 
Syntax
boolean := DialogDelete (Dialog: string)
 
Parameters
Dialog string Name of the dialog to delete (see DialogDefine).

DialogDestroy

Purpose Remove an old-style dialog box from memory.
 
Examples Appendix A: 8041
 

Discussion

A dialog created with the Dialog Editor, without a callback (see DialogShow), is removed from memory when any button is pushed. Subsequent calls to the dialog create an error (the macro system no longer knows anything about the dialog). For example, DialogDismiss in 

DialogShow ("Dialog1"; "PerfectScript")
DialogDismiss ("Dialog1"; "OKBttn")

creates an error when OK is pressed (Dialog1).

The next example, which includes a callback function, displays the dialog, continuously executes instructions (callback function "CallHere"), is dismissed (hidden), and is finally destroyed. 

DialogShow ("Dialog1"; "PerfectScript"; CallHere)
DialogDismiss ("Dialog1"; "OKBttn")
DialogDestroy ("Dialog1")
Quit

Label (CallHere)
 ...other statements...
 Return
 
Return Value True if successful, False if not. This same value is placed in MacroDialogResult.
 
Syntax
boolean := DialogDestroy (Dialog: string)
 
Parameters
Dialog string The name or number of a dialog box to destroy (see DialogDefine).

DialogDismiss

Purpose Hide a dialog box. Use DialogShow to display a hidden dialog box.
 
Examples Appendix A: 8094
 

Discussion

A dialog created with the Dialog Editor, without a callback (see DialogShow), is removed from memory when any button is pushed. Subsequent calls to the dialog create an error (the macro system no longer knows anything about the dialog). For example, DialogDismiss in 

DialogShow ("Dialog1"; "PerfectScript")
DialogDismiss ("Dialog1"; "OKBttn")

creates an error when OK is pressed (Dialog1).

The next example, which includes a callback function, displays the dialog, continuously executes instructions (callback function "CallHere"), is dismissed (hidden), and is finally destroyed. 

DialogShow ("Dialog1"; "PerfectScript"; CallHere)
DialogDismiss ("Dialog1"; "OKBttn")
DialogDestroy ("Dialog1")
Quit

Label (CallHere)
 ...other statements...
 Return
 
Return Value Name of the button control used to dismiss a dialog, which can be slightly different than the value placed in MacroDialogResult. If the button used to dismiss a dialog is OK, 1 is placed in MacroDialogResult, or 2 if the button is Cancel. DialogDismiss returns "OKBttn" or "CancelBttn." If the button is not OK or Cancel, the name of the control is placed into MacroDialogResult, and returned from DialogDismiss. If an error occurs, an empty string ("") is returned.
 
Syntax
string := DialogDismiss (Dialog: string; Control: string)
 
Parameters
Dialog string The name or number of the dialog box to hide (see DialogShow).
Control string OKBttn or 1 for OK, CancelBttn or 2 for Cancel, or the control value of a user-defined push button or QuickSpot. CancelBttn cancels value assignments to control return variables. For example, an edit control does not return the text entered in the edit box. The value of Control is returned in MacroDialogResult as OKBttn, CancelBttn, or the control value of another push button or QuickSpot.

DialogHandle

Purpose Return the handle of a dialog or dialog box control.
 
Examples Appendix A: 8051
 
Return Value Handle of a dialog or dialog box control.
 
Syntax
numeric := DialogHandle (Dialog: string; [Control: string])
 
Parameters
Dialog string The name or number of a dialog (see DialogDefine).
Control string (optional) The name or number of a dialog box control (see Control parameter of any dialog control). If you omit this parameter, the handle of the dialog box is returned.

DialogLoad

Purpose Load a dialog in memory without displaying it. You can use Region commands on a dialog box that has been loaded. See also DialogShow and Discussion under DialogDismiss.
 
Examples Appendix A: 8041
 
Return Value The window handle if successful, or 0 if not.
 
Syntax
numeric := DialogLoad (Dialog: string; [Parent: string])
 
Parameters
Dialog String The name or number of a dialog box (see DialogDefine).
Parent string (optional) The name of the parent region, such as "Corel PerfectScript," or "Corel WordPerfect" for Corel WordPerfect.

DialogSave

Purpose Save the specified dialog as a binary form dialog in the prefix packet area of the current macro file.
 
Return Value True if saved successfully, False if not.
 
Syntax
boolean := DialogSave (Dialog: string; [SaveAsName: string])
 
Parameters
Dialog string The name of the dialog to save (see DialogDefine).
SaveAsName string (optional) The name to save the dialog under. If missing, the dialog is saved under the current dialog name.

DialogSetProperties

Purpose

Specify additional properties for a dialog box.

This command should be used only on dialogs created with DialogDefine. It should be called immediately after DialogDefine. 

DialogDefine(....)
DialogSetProperties(....)
 
Return Value True if successful, False if not.
 
Syntax
boolean := DialogSetProperties (Dialog: string; [FontName: string]; [FontSize: measurement]; [ClassName: string]; [HelpFile: string]; [HelpString: string])
 
Parameters
Dialog string The name or number of a dialog box (see DialogDefine).
FontName string (optional) The font that dialog text will appear in.
FontSize measurement (optional) Specify the font size using a measurement type, such as 12p. If the measurement type specifier is not used, default units is assumed. See DefaultUnitscommand.
ClassName string (optional) Specify another class name.
HelpFile string (optional) The name of the Help file associated with the dialog.
HelpString string (optional) The part of the Help file to come up along with the dialog.

DialogShow

Purpose

Display a dialog box, and, optionally, identify a callback function.

Use DialogDismiss to hide a dialog box. See Discussion under DialogDismiss or DialogDestroy.

A callback function enables a macro to respond immediately and in specific ways to events such as selecting a radio button or check box, without waiting until the dialog box is dismissed. Without a callback function, user input is acted upon only after the dialog box is dismissed and the macro resumes execution.

To create a callback function, use the Label parameter of DialogShow, and a loop statement after DialogShow. For example, 

DialogShow(1000; "WordPerfect"; Msgs)
CallbackWait

Label(Msgs)
 ... other statements ...
 Return

The value of the control that dismisses a dialog box is returned in an implicit variable named MacroDialogResult: 1 for OK, 2 for Cancel, 2 for Close (system menu box), 2 if you double-click the system menu box, 2 if you press Alt+F4, or the value of the Control parameter of a user-defined push button or QuickSpot (see DialogAddPushButton and DialogAddHotSpot).

If DialogShow is used with Dialog commands, such as DialogDefine and DialogAddEitBox (old- style dialog box), the first control that can return a value has the input focus.

If a dialog is preloaded through DialogLoad or a Region command, the Parent parameter of DialogDefine is not used (the dialog is already created or "parented"). Before loading a dialog through a Region command, use DialogLoad to specify the parent.

 
Examples Appendix A: 8094
 
Return Value

If DialogShow is used to display a callback dialog, the window handle of the dialog is returned (the same value placed into MacroDialogResult), and returned from DialogShow. If an error occurs, 0 is returned.

If DialogShow is used to display a non-callback dialog, the button control used to dismiss the dialog is returned, which can be slightly different from the value placed in MacroDialogResult. If the button used to dismiss the dialog is OK, 1 is placed in MacroDialogResult, or 2 if the button is Cancel. DialogShow returns "OKBttn" or "CancelBttn." If the button is not OK or Cancel, the name of the control is placed into MacroDialogResult. If an error occurs, an empty string ("") is returned.

 
Syntax
numeric or string := DialogShow (Dialog: string; [Parent: string]; [Callback: label]; [Focus: string])
 
Parameters
Dialog string name of a dialog box to display (see DialogDefine for old-style dialog boxes).
Parent string (optional) The name of the parent window, such as "WordPerfect" for Corel WordPerfect. The parameter is required by new-style dialog boxes (see Help in Corel WordPerfect and Corel PerfectScript), and it can be used by old-style dialog boxes.
Callback label

(optional) Identify a callback function (Label to call) when the dialog box becomes active, or the user

  • Chooses Close from the system menu.
  • Presses Alt+F4.
  • Double-clicks the system menu box.
  • Chooses a push button, radio button, check box, QuickSpot, or scroll bar control.

The Windows messages are:

  • WM_ACTIVATE
  • WM_COMMAND
  • WM_DESTROY
  • WM_HSCROLL
  • WM_INITDIALOG
  • WM_SYSCOMMAND
  • WM_VSCROLL

For more information, see Callback Data Description in Chapter 5: Conditional, Loop, and Calling Statements.

Focus string (optional) Specify the control to receive the initial focus.