Chapter 2
Macros
Macros automate application tasks. For example, Corel WordPerfect macros automate tasks such as setting margins, selecting a font, or creating a merge file.
Macros tasks consist of instructions called statements. There are several kinds of statements: assignments, conditions, loops, comments, and commands. For example,
MarginLeft (1.0")
MarginRight (1.0")
are Corel WordPerfect commands that set one-inch left and right margins (the task). Each command represents one instruction or statement. The simplest macro consists of only one statement. Complex macros have hundreds of statements. The sequence of statements determines how a macro performs its tasks.
Each type of statement is discussed in this chapter.
Syntax refers to rules that govern the form of macro statements and expressions. For example, the following statement types “John Doe”:
Type(Text: “John Doe”)
The next example lacks a closing parenthesis.
Type(Text: “John Doe”
The syntax is incorrect and produces an error message.
Expressions
Expressions represent values. They are used in several statements (assignments, conditions, loops, and commands) to form a statement that the computer can understand.
To create expressions, you use variables and constants. Variables represent data that can change while a macro is playing (for example, vCount), and constants represent data items that cannot change during macro play (for example, 20).
You combine variables and constants with operators (+, -, *, %, etc.) to create an expression. For example, a valid expression would be vCount + 20.
Assignment statements assign the value of an expression to a variable. For example,
x := “John Doe”
Result: x equals John Doe
y := 5
Result: y equals 5
z := 3 + 4
Result: z equals the result of 3 + 4
The assignment operator (:= or =) assigns the value of a right operand expression to a left operand variable.
Conditional Statements
Conditional statements play a statement or group of statements (statement block) when a specified condition is met. Conditional statements are useful for displaying a list of options. A statement block is played depending on which option the user chooses. Conditional statements include Case, If, and Switch.
Loop statements play a statement or statement block a specified number of times until an expression is true or while an expression is true. The macro then exits the loop and continues to the next statement. Loop statements include For, ForNext, ForEach, Repeat, and While.
Comment statements contain notes and other information that do not affect macro play. Use comment statements to explain the purpose of your macro, describe its components, or to prevent a statement from playing. Comment statements help if you have to modify a macro months after it is written or if someone else has to understand your macro. A comment either begins with // and ends with a hard return [HRt], or it begins with /* and ends with */. See PerfectScript // and /* */ commands.
Command statements consist of a name and can include one or more parameters. Commands represent instructions to the parent application.
There are three types of macro commands: product commands, OLE Object commands, and programming commands. Product commands are specific to a product; for example, Corel WordPerfect or Corel Quattro Pro. OLE object commands perform tasks on an OLE object. Programming commands work across applications; they are PerfectScript commands.
Command names often describe an action, such as Font, MarginLeft, Advance, and FootnoteOptions in Corel WordPerfect; or AlignObjectsLeft, BitmapBlur, SelectAllObjects, and ToolbarCopy in Corel Presentations; or Range in Microsoft Excel. Command names are not case sensitive and usually do not contain spaces. Exceptions include programming commands that call a subroutine, such as Case Call or OnCancel Call.
A macro can use more than one application product and OLE object. Commands to the non-default application or OLE Object require a prefix, which is specified in an Application or Object statement. In this example,
A1.AboutDlg ()
A1 (followed by a period) is the prefix. It tells the compiler to use the application or Object assigned A1 in a PerfectScript Application or Object statement.
Product commands perform product tasks in a specific application. For example,
ShowSlide(Slide: 4)
displays the fourth slide in the current slide show in Corel Presentations.
Product commands are specific for each application, such as Corel WordPerfect or Corel Presentations. They perform various functions in that application, such as:
Product commands that report information (return value) about the state of an application or feature are sometimes called system variables. In Corel WordPerfect, system variables begin with a leading question mark (?ColumnWidth). In Corel Presentations, they begin with a leading Env (EnvPaths). Some system variables in Corel Presentations have parameters as well as return values.
Product commands and programming commands are not case sensitive.
OLE object commands are called methods, and they perform tasks on an OLE object in a specific OLE Automation server.
OLE object methods are specific for each object, such as "Excel.Application" or "Excel.Workbooks." They perform various functions on that object.
OLE object methods that return information about an object are called properties. Many properties have parameters as well as return values. In addition, many properties can be assigned a value by placing them on the left-hand side of the assignment symbol ":=" like the name of a variable.
Programming commands work across applications. They generally control macro functions, such as:
For example,
If (x = “A”)
LineHeightDlg
Else
LineSpacingDlg
Endif
displays the Line Height dialog box in Corel WordPerfect if x equals the value “A”, or displays the Line Spacing dialog box if x has any other value. If, Else, and Endif are programming commands. LineHeightDlg and LineSpacingDlg are product commands.
Programming commands and product commands are not case sensitive.
Commands often require parameters, which are constant values (data). Parameters are passed to the compiler (that translates the macro so it can be played in the application) or passed between subroutines (statement blocks). In this Corel WordPerfect example,
Advance (Where: AdvanceDown!; Amount: 1.0")
Advance is the command name, and AdvanceDown! and 1.0² are parameter data. This command advances the insertion point down one inch. Parameter names, such as Where and Amount, are optional.
A data type represents information that is needed by a parameter or returned by a command (return value).
In the command syntax, data types are displayed in italics. For example, the enumerations for the Rotation parameter of BoxCaption Rotation are Degrees90!, Degress 180!, Degrees 270!, and None!. Only these enumerations can replace the data type in the command syntax. Note that enumerations are identified by a trailing exclamation point. The most common data types in product commands are string, enumeration, and numeric. Programming commands also frequently use variables.
Using parameter names is optional. For example, InhibitInput (State: Off!) works just like InhibitInput (Off!). Some product commands have no parameters. Their syntax is usually written with empty parameters, such as PosScreenUp (). Some programming commands and system variables have no parameters, also. Their syntax is the command name alone, such as Pause and ?FeatureBar.
Italics in Macros syntax indicate parameter names or types to be replaced with data. For example, the syntax of GraphicsLineLength is:
GraphicsLineLength (Length: measurement)
After you replace measurement with a number, the command might be:
GraphicsLineLength (Length: 2I)
or
GraphicsLineLength (2I)
Enclose parameters in parentheses. A missing parenthesis, either opening or closing, is a common error that prevents macros from compiling. Parentheses are optional for commands with no parameters but must be used with user-defined functions and procedures (see Subroutines in Chapter 5: Conditional, Loop, and Calling Statements).
Spaces between command names and the opening parenthesis of the parameter section and after semicolons in parameters are optional.
Separate multiple parameters with semicolons(;). If you omit an optional parameter, include the semicolon in the syntax to keep following parameters in their correct positions. For example,
AbbreviationExpand (AbbreviationName:; Template: PersonalLibrary!)
or
AbbreviationExpand (; PersonalLibrary!)
Repeating parameters are enclosed in braces and separated by semicolons. For example,
CASE (<Test>: any ; {<Case>: any; <Label>: label; <Case>: any; <Label>: label...})
When data is supplied, the command could be
CASE (vChoice; {1; Exclaim; 2; Info; 3; Question; 4; Stop;5; QuitMacro}; QuitMacro)
Enumerations are identified by a trailing exclamation point (Printer!).
Some commands are used to retrieve data from various sources. For example, commands can get the current date from the system, the current page number or document filename from an application, or a specific value from the Windows registry. This information is usually returned as a return value. Corel WordPerfect returns information such as this primarily with system variables, but there are also some product commands that return values. In addition, many of the PerfectScript (programming) commands return values. Each return value has a specific data type (see Data Types earlier in this chapter).
Handling a return value means to do something with it. Macros can either ignore or handle the return values of commands that return values. To handle a return value, you must assign it to a variable or use it in an expression. For example,
vVariable := ?Name
stores the return value of ?Name (filename of the current Corel WordPerfect document) in vVariable. In the above example, ?Name’s return value is handled by assigning it to a variable. System variable return values are handled in exactly the same manner as command return values.
To ignore a return value, simply don’t handle (assign, etc.) it. For instance, some commands change an option’s state and also return the option’s previous state. If your macro changes the option’s state and doesn’t care what the previous state was, it should ignore the return value.
Expressions and Value-returning Commands
System variables or commands that return values are said to “evaluate to” the return value. Just as (2+2) evaluates to 4, ?Name, a Corel WorPerfect system variable, evaluates to the filename of the current document. Therefore, you could use (2+2) anywhere in an expression where you could use 4. Likewise, you could use ?Name in an expression anywhere you could use the filename of the current document.
Suppose you are writing a macro that opens a file, writes text to it, and closes it. To close the open file you would use the CloseFile PerfectScript command. CloseFile returns True if the file was closed successfully and False if not. Since CloseFile evaluates to its return value, you can close the file and check to see if it was successfully closed at the same time. For example,
If (CloseFile (FileID: xxxx))
...(statements to execute if the file was successfully closed)...
Else
...(statements to execute if the file was not successfully closed)...
EndIf
In the above example, xxxx represents the file ID number of the file to be closed.
Enumeration return values require special treatment. If the data type of the return value is enumeration, rather than evaluating to just the enumeration, it evaluates to the name of the command followed by a period then the enumeration (for example, command name.enumeration!). This is necessary because the compiler needs to know what command the enumeration is referring to. For instance, the enumeration On! does not mean anything by itself. Within the context of a command parameter, On! has meaning because what is being turned on is specified by the parameter. Since return values can be handled outside of the context of a command, they need to be associated with the command to have meaning.
Here is the syntax for the Cancel PerfectScript command:
enumeration := Cancel (State: enumeration)
It determines how a macro responds to a Cancel condition. It also returns the previous Cancel state (On! or Off!). The following example,
Cancel (State: On!)
vVariable := Cancel ()
If (vVariable = Cancel.On!)
Type ("Correct")
EndIf
If (vVariable = "Cancel.On!")
Type ("Not Correct")
EndIf
sets the Cancel state to On!, stores the current state of the Cancel command in vVariable, and types “Correct” in the current Corel WordPerfect document. Notice the omission of the State parameter in the Cancel command of the second line. The state of Cancel can be returned without changing it, by omitting the optional parameter. Also notice the Type command within the second If statement. This command will not be executed because the expression in the second If statement assumes the enumeration returned by the Cancel command is a string. Although enumerations look like strings, they are not.
Enumerations have numeric equivalents. In the above example vVariable is also equal to 1. If you were to follow the above example with the Corel WordPerfect product command Type (vVariable), the number 1 would be typed in the current document. Since the numeric equivalents of enumerations may change, users are strongly encouraged to use the command name.enumeration!syntax to evaluate return values. Enumeration numeric equivalents are generally not documented.
Accessing Commands
The PerfectScript Command Browser keeps programming commands and product commands in separate lists. It also displays the parameters and enumerations for each command.
To use the Command Browser,
1 From the Windows Start Bar, click Corel WordPerfect 8 Suite > Tools Corel PerfectScript.
2 Click Help > Macro Command Browser.
3 Select the application you want to use from the Command type pull-down list.
4 Select a command from the command list.
Subroutines consist of a statement or group of statements (statement block) that are played when the macro calls a subroutine. For example,
Call (SubExample)
...(other statements)...
Label (SubExample)
...statement block...
Return
The calling statement Call (SubExample) calls (directs macro play to) the subroutine Label (SubExample). Return directs macro play to the statement that follows Call (SubExample).
Subroutines include functions, procedures, and labels. Subroutines are useful because the statements in a subroutine are accessible to any part of a macro, and can be called any number of times during play.
A macro compiler is used to compile or “translate” macros so that Corel WordPerfect Suite applications can play them. Macros in Corel WordPerfect are compiled when you record, play, or save them, or when you click Save & Compile or Options > Close Macro on the Macro Edit feature bar.
From Here
The topics in this chapter are discussed further in: