WORDPERFECT MACRO TUTORIAL

10. User Interaction

10.1 Allowing the user to interact with the macro

Usually when a macro is played it executes its commands from start to finish, and the macro ends. But sometimes you may want to allow the user to do something in the "middle" of the macro, during a pause in the execution of the macro. You can do this by using the Pause() command. Or you might want the macro to get input from the user while it is running, which will then be used in the macro. This is done with the GetString() and GetNumber commands.

10.2 Pausing a macro

A pause in a macro temporarily suspends the play of the macro at a particular point, to allow the user to perform operations "outside" of the macro. When the user's operations are finished, the macro resumes execution once the [ENTER] key is pressed.

You can insert a pause while recording the macro, or while editing the macro. While recording, click on Tools/Macro/Pause at the point where you would like the macro to pause for user operations. This inserts a Pause() into the macro. Recording is temporarily suspended (your actions from this point forward are not included in the macro) until you click on Tools/Macro and uncheck Pause on the menu. Recording of your actions then resumes. You can also type in the Pause() command while editing the macro.

Sometimes the [ENTER] key will not cause the macro to resume (for example, when the user has switched to a different document window in WordPerfect during a pause in a macro). In that case, the macro can always be resumed by clicking on Tools/Macro, and unchecking Pause on the menu.

A macro with a pause can be a tremendous time-saver. For example, if you have repetitive text to enter into a document multiple times with a slight variation each time, you could create a macro that inserts the repetitive text, then pauses to allow the user to type the varying text, and then continues to insert the rest of the repetitive text. This is especially useful when combined with looping.

10.3 Getting input from the user

If you think of a macro as performing a process, you can understand that there are two aspects involved: what the process does, and "who" it does it to. Often you will want to create a macro that performs a standard process, but which can be applied to different items; it will do the same actions each time, but to different things. You can program the macro to ask the user to input the "object" for the macro to act upon.

The GetString() command is used to obtain information from a user during the execution of a macro. The command takes two parameters: a variable name for the variable that will store the information received from the user, and a string that will be displayed as text in the dialog box that will be displayed.

The form of this command is:

GetString(x;"prompt")

At the point where the macro executes this command, a dialog box will be displayed to the user. The dialog will contain text (represented by the "prompt" parameter) that is usually an explanation of the input required, and an edit field into which the user will type the input. When the dialog box is closed, the contents of the edit field are assigned to the variable whose name you specified as the first parameter (represented by x above).

As its name implies, the data accepted by the GetString() command is a string. Remember that you cannot perform arithmetic on strings. If you need to obtain a number from the user,, use the corresponding GetNumber() command. The data obtained from the user by GetNumber() is stored in the variable as a number. (See the topic strings v. numbers earlier in the tutorial.)

Examples:

To allow the user to specify a file to open:

GetString(vFile;"Type name of file to open below")

When the macro is played, the GetString() command would open a dialog box like this:

GetString Dialog Box

When the user clicks OK (or presses [ENTER]) to close the dialog, whatever the user typed in the edit field would be stored in the variable vFile. You could then use the FileOpen() command in the macro to open the file, passing vFile as the file name parameter:

FileOpen(vFile)

Allowing the user to specify what the macro should process makes the macro much more flexible. The same macro can open a different file each time it runs, depending on the value the user passes to the macro in the dialog box. Any time the same set of commands can be applied to different things, and the identification of those things can be obtained from the user, you should think of using GetString() or GetNumber().