.
Chapter 7
Users interact with applications through menus and dialog boxes. Dialog boxes can display more than one option for user input. For example, in the Corel WordPerfect Margins dialog box, default settings are displayed in edit boxes next to buttons. To display the Margins dialog box, choose Format < Margins (an ellipsis to the right of a menu option indicates a dialog box is available).
To change settings, enter new values in the edit boxes or click a button (see PerfectScript DialogAddPopupButton command). The edit box and button are Windows controls for user input. Controls available for a user-defined dialog box are described in the sections listed below.
Dialog Box Controls
Dialog box controls are input or output windows where the user interacts with a dialog box and its parent application. The table below describes the dialog controls that are supported by PerfectScript macros.
|
Control Type |
Description |
|
Display bitmap graphics. Accept no input, unless used in a callback function with DialogAddHotSpot. See PerfectScript DialogAddHotSpot, DialogAddBitmap, DialogShow commands. |
|
|
Display one or more options. Use a callback function to activate user-defined responses. See PerfectScript DialogAddCheckBox command. |
|
|
Display colors to select. See PerfectScript DialogAddColorWheel command. |
|
|
Display an edit box and a list box. Enter text such as a filename in the edit box, or double-click a list item to insert it. See PerfectScript DialogAddComboBox command. |
|
|
Display an edit box and counter buttons. Enter a number in the edit box, or click the counter buttons to insert a number. See PerfectScript DialogAddCounter command. |
|
|
Display an edit box and a calendar button. Enter a date in the edit box, or click the calendar button to insert a date. See PerfectScript DialogAddDate command. |
|
|
Receive text input. There are different styles of edit controls, including single line and multiple line. See PerfectScript DialogAddEditBox command. |
|
|
Display an edit control and a button control. Enter a filename in the edit control, or click the button to display the Select File dialog box. See PerfectScript DialogAddFileNameBox command. |
|
|
Group items in a dialog box. Accept no input. See PerfectScript DialogAddFrame command. |
|
|
Group items in a dialog box with a titled frame. Accept no input. See PerfectScript DialogAddGroupBox command. |
|
|
Horizontal Lines |
Separate items in a dialog box. Accept no input. See PerfectScript DialogAddHLine command. |
|
Are invisible controls that close a dialog box when the user clicks a defined area. Redefine the response with a callback function. See PerfectScript DialogAddHotSpot command. |
|
|
Display graphic representations. Accept no input, unless used in a callback function with DIALOGADDHOTSPOT. See PerfectScript DialogAddHotSpot, DialogAddIcon, DialogShow commands. |
|
|
Display a list of options to choose from. There are different styles of list boxes, including single-column and multi-column. See PerfectScript DialogAddListBox commands. |
|
|
Display a progress indicator. See PerfectScript DialogAddProgress command. |
|
|
Activate user-defined responses when chosen. See PerfectScript DialogAddPushButton command. |
|
|
Display mutually exclusive options. Use a callback function to activate user-defined responses. See PerfectScript DialogAddRadioButton and DialogShow commands. |
|
|
Scroll through documents, or activate user-defined responses with a callback function. See PerfectScript DialogAddScrollBar and DialogShow commands. |
|
|
Send text to a dialog box. Accept no input. See PerfectScript DialogAddText command. |
|
|
Display read-only text files. See PerfectScript DialogAddViewer command. |
|
|
Vertical Lines |
Separate items in a dialog box. Accept no input. See PerfectScript DialogAddVLine command. |
Creating a Dialog Box with Macro Commands
To create a dialog box with macro commands, define it, add controls, and display it. You should dismiss the dialog box when the macro ends. The following commands create a dialog box:
// Example Dialog Box
// Define dialog box
DialogDefine (Dialog: 1000; Left: 50; Top: 50; Width: 150; Height: 100; Style: OK! | Percent!; Caption: "Example Dialog Box")
//Static text control
DialogAddText (Dialog: 1000; Control: 100; Left: 10; Top: 10; Width: 50; Height: 15; Style: Left!; Text: "Edit control:")
// Edit box control
DialogAddEditBox (Dialog: 1000; Control: 101; Left: 10; Top: 25; Width: 125; Height: 25; Style: Left! | VScroll! | Multiline!; vReturn; 1000)
// Display dialog box
DialogShow (1000; "WordPerfect")
// Destroy dialog box
DialogDestroy (1000)
The following sections describe the above example in detail.
Specify the size and style of the dialog box, and the controls it will contain. The following command,
DialogDefine(Dialog: 1000; Left: 50; Top: 50; Width: 150; Height: 100; Style: OK! | Percent!; Caption: "Example Dialog Box")
defines (creates in memory) a dialog box. The table below describes the functions of the parameters.
|
Parameter(s) |
Description |
|
Dialog |
The number 1000 was chosen to identify the dialog box. A name such as “MainDialog” could also have been used. The number or name must be unique. It is used again to add controls, display, and then destroy the dialog box when the macro ends. |
|
Left, Top, Width, Height |
The dialog box is displayed in the center of the screen by setting the left and top parameters to 50 and using the Percent! style. Dialog boxes are positioned and sized in dialog units. A vertical unit equals 1/8 the font height, and a horizontal unit equals 1/4 the font width. |
|
Style |
The Percent! formula is: [(screen width or height - dialog box width or height) * percentage]. This formula equals the number of dialog units from the left side of the screen to the left side of the dialog box, or the number of dialog units from the top of the screen to the top of the dialog box. The dialog box has an OK push button control. |
|
Caption |
The dialog box title is “Example Dialog Box”. |
Parameter names are optional. For example,
DialogDefine (1000; 50; 50; 200; 125; OK! | Percent!; "Example Dialog Box")
defines the same dialog box as the command above.
Add Controls
The following commands:
DialogAddText (Dialog: 1000; Control: 100; Left: 10; Top: 10; Width: 50; Height: 15; Style: Left!; Text: "Edit control:")
DialogAddEditBox (Dialog: 1000; Control: 101; Left: 10; Top: 25; Width: 125; Height: 25; Style: Left! | VScroll! | Multiline!; vReturn; 1000)
add a static control and an edit control to the dialog box. The table below describes the functions of the parameters.
|
Parameter(s) |
Description |
|
Dialog |
1000 for both controls, which equals the Dialog parameter of the parent dialog box (see Define earlier in this chapter). |
|
Control |
The controls have unique Control numbers (100 and 101), which could also be names such as “Control 1" and ”Control 2". Old-style dialog boxes used Control values to give a control the initial input focus (see Creating a Dialog Box with Dialog Editor later in this chapter).
The value of the Control used to dismiss the dialog box is returned in the implicit variable MacroDialogResult (see PerfectScript DialogDefine command): 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 hot spot (see PerfectScript DialogAddPushButton and DialogAddHotSpot commands). |
|
Left, Top, Width, Height |
The controls are displayed 10 dialog units from the left side of the dialog box, and 10 and 25 units from the top. The widths are 50 and 175 dialog units, and the heights are 15 and 50 dialog units. A vertical dialog unit equals 1/8 the font height, and a horizontal dialog unit equals 1/4 the font width. |
|
Style |
The static text is left justified. The edit box is multi-line with a vertical scroll bar. Combine styles with bitwise OR operator (|) (see Bitwise Operators in Chapter 4: Expressions). |
|
Text |
The static control text is “Edit Control”. |
|
MacroVar, LimitText |
Text typed into the edit box is assigned to variable vReturn when the dialog box is dismissed by OK or Close on the system menu. The maximum number of characters the edit control accepts is 1000. |
The following command
DialogShow (1000; "WordPerfect")
displays dialog box 1000 and gives the input focus to control 101 (edit control has the insertion point).
Destroy
The following command
DialogDestroy (1000)
destroys dialog box 1000, and clears the value of the implicit variable MacroDialogResult. If you need this value, assign it to another variable before executing DialogDismiss. If you do not destroy a dialog box before the macro ends, memory conflicts may occur.
Creating a Dialog Box with Dialog Editor
Use the Macro Dialog Editor to quickly and easily create, design, set properties for, and edit the dialogs you use in your macros. Using the Macro Dialog Editor takes the place of the DialogDefine sections in your macros.
The Macro Dialog Editor lets you add, edit, position, size, move, and assign values to controls, lines, and other elements of a dialog. You can also use it to give each control a control name, variable name, values, and other properties, as well as define the control order, set the initial focus, set tab stops, and group controls.
With Dialog Editor you can visually create and edit dialogs for Windows application macros. Open Dialog Editor from PerfectScript or from within Corel WordPerfect.
Opening the Macro Dialog Editor from PerfectScript
1 Open PerfectScript (run PS80.EXE from Windows).
2 Click Tools > Dialog Editor.
3 Specify a macro filename, then click OK.
4 Click File > New, type a name for the dialog, then click File > Open.
or
Select the dialog you want, then click File > Open.
Opening the Macro Dialog Editor from within Corel WordPerfect
1 Click Tools > Macro > Edit.
2 Specify a macro filename, then click Edit to display the macro toolbar.
3 Click Dialog Editor on the macro toolbar.
4 Click File > New, type a name for the dialog, then double-click it.
or
Select the dialog you want, then click File > Open.
Modal dialog boxes require the user to complete an action before input to the parent application is allowed. For example, the Margins dialog box (Corel WordPerfect) and the Page Format dialog box (Corel Presentations) and the Busy Search Settings dialog box (Novell GroupWise) require the user to choose OK or Cancel before control returns to the application. Macro dialog boxes are modal by default (see PerfectScript DialogDefine command).
Modeless dialog boxes do not require the user to complete an action before input to the parent application is allowed. For example, you can perform a search with the Find and Replace Text dialog box (in Corel WordPerfect, choose Edit < Find and Replace), then click Document and edit the document while the Find and Replace Text dialog box remains on the screen. Click the dialog box to perform another search. For information about creating a modeless dialog box, see PerfectScript DialogDefine command.