Generating and editing Corel Presentations macros by using PerfectScript
With PerfectScript, the command-based macro language of WordPerfect Office, you can combine statements to automate routine tasks and simplify large ones.
In this section, you'll learn about
understanding components of macro commands
using types of macro commands
understanding syntax
using macro conventions
formatting macros
using programming commands
using parameters
using variables
assigning variables in PerfectScript
inserting commands with the Macro Command Browser
using macro commands to retrieve information
inserting codes into macros
compiling macros using the macro compiler
fixing compile errors
editing and deleting macros in PerfectScript
adding search capabilities to macros
Understanding components of macro commands
Recording and playing macros can simplify routine tasks, but when product commands are used together with PerfectScript programming commands, you can create more complex macros. By using product commands and programming commands, the functionality of WordPerfect Office features is combined with the customizing, decision making, and iterative capabilities of a programming language. Using programming commands also makes it possible to include the functionality of other applications in WordPerfect Office.
PerfectScript macros are composed using PerfectScript, the common macro language for all applications in WordPerfect Office. PerfectScript is a command-based language. When you record a macro, PerfectScript records the results of keystrokes or mouse selections instead of recording the keystrokes themselves. For example, instead of recording each keystroke required to change the top margin of a page to 2" (5.1 cm), the macro records the command:
MarginTop(MarginWidth:2.0")
PerfectScript also includes programming commands that direct the function of the macro. These commands let you prompt for user input, make decisions based on conditions in a document, access system variables, and so on. Using programming commands with product commands can automate long, complex tasks.
A written macro can include nonrecordable statements, which cannot be included in recorded macros that specify how a macro performs a task. Writing a macro provides greater flexibility to determine function than recording a macro. You can create a macro in WordPerfect and play it in the application for which it was written.
WordPerfect lets you include the functionality of other applications in WordPerfect Office with the PerfectScript language. A macro written in one application can open another application and perform tasks, giving you tools to use Quattro Pro, Corel Presentations, and WordPerfect together.
Macro commands consist of three parts: a command name, parameters, and separators. The table below describes these elements of syntax.
Component Definition
Command names Indicate the type of action to be performed. Some commands consist only of a command name, such as FileOpenDlg().
Parameters Provide more information about the command, such as which options of a feature are active. Parameters are always enclosed in parentheses; for example, SelectTextChart(Chart:Bullets!).
Separators Mark the parameters in a command. Semicolons separate individual parameters; parentheses enclose a series of parameters; braces enclose a series of repeating parameters.
In the example included in the following table, the statement selects the title, subtitle, or bullet chart for a slide that contains these elements. The 'Bullet!' enumeration will only work for bullet charts inserted from the layout layer. The command has one parameter called 'Chart'. The value of the parameter is set to 'Bullet!'. Other acceptable values for this parameter are 'Title!' and 'Subtitle!'. The various acceptable values for this type of parameter are called enumerations. Other parameter types accept values of the type string or numeric.
The PerfectScript programming language consists of Corel Presentations application commands and functions, and programming statements and functions. PerfectScript can do more than perform recorded Corel Presentations commands-it can extend the functionality of slide shows in a number of ways, such as prompting you for input, displaying messages, controlling other Corel and Windows-based applications, and performing and repeating commands. You can also build complete applications or Wizards so that a user with limited experience using Corel Presentations can still use some of the more complex functions.
There are three types of macro commands: product commands, OLE object commands, and programming commands. Product commands are specific to a product, such as Corel Presentations or 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 AlignObjectsLeft, BitmapBlur, SelectAllObjects, and ToolbarCopy. 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 the following 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.
Understanding syntax
Syntax refers to the grammatical rules that govern the form of macro statements and expressions. For example, the syntax of the following statement, which types "John Doe," is correct:
Type(Text: "John Doe")
The syntax of the next example is incorrect and produces an error message because the statement lacks a closing parenthesis:
Type(Text: "John Doe"
If you find it difficult to distinguish different parts of a macro, remember that you can add extra line spaces, tabs, and even font changes to make the macro more readable. As long as the commands are written correctly, the macro compiler ignores extra spaces and lines.
Using macro conventions
When you create macros in WordPerfect, you must obey macro command syntax for the macro to compile properly. You do not need to follow macro formatting conventions for a macro to compile correctly. However, you will improve the readability of a macro if you use these conventions.
Macro command syntax must be correct for a macro to compile. Understanding the following conventions used in WordPerfect macros will help you avoid common syntax errors:
You can enter programming commands in uppercase, lowercase, or mixed case. The compiler is not case sensitive.
Product commands, such as AboutDlg or AddSlide, are shown in mixed case.
Corel Presentations system variables begin with Env, such as EnvCurrentSlideNumber or EnvSlideTitle. They are shown in mixed case and they return information about the application environment.
Line wrapping does not affect macro execution.
Do not insert a space in a command name unless the space is part of the syntax.
Do not use hard returns, tabs, or indents in a character expression (a character string enclosed in double quotation marks).
You can use spaces, tabs, indents, and hard returns before and after commands, or between parameters, to make a macro easier to read.
Smart quotes in a macro create a compile-time syntax error.
Formatting macros
You can type commands into a macro that is saved in a file. If you want to improve the readability of a macro, you can format it so that it includes tabs, spaces, and font or text appearance changes. Formatting the macro does not affect how it works. The two forward slashes indicate comments within the macro formula. For example, WordPerfect records the following macro in this format:
// Create a chart
BeginDataChart()
ChartCreate (VertBar!;Button1!;Yes!;Yes!)
// Display subtitle which is off by default
ChartSubtitleToggle()
// Display the chart title
ChartTitlesDisplay(Title!;On!)
However, if you type the commands yourself or edit an existing macro, you can format the macro the way you want. For example, you can format it as follows:
// Create a chart
BeginDataChart()
ChartCreate (VertBar!;Button1!;Yes!;Yes!)
// Display subtitle which is off by default
ChartSubtitleToggle()
// Display the chart title
ChartTitlesDisplay(Title!;On!)
Using programming commands
Programming commands work across WordPerfect Office applications. They control macro functions, such as
Repeating macro commands or statements a specified number of times or until certain conditions are met (For, Endfor, Repeat, Until, While, EndWhile)
Invoking or jumping to a specified subroutine with Call or Go
Specifying conditions under which other macro commands or statements operate (Case, IfElse, Endif, Switch, EndSwitch)
For example,
If (x = "A")
EditBackground
Else
EditLayouts
Endif
displays the background layer of a slide in edit mode if x equals the value "A". If x has another value, the subroutine displays the layout layer of a slide for you to edit. The If, Else, and Endif commands are programming commands. EditBackground and EditLayouts are product commands.
Using parameters
Commands often require parameters, which can be assigned values (data). Parameters are passed to the compiler (which translates the macro so that it can be played in the application) or passed between subroutines. In this WordPerfect command,
Advance (Where: AdvanceDown!; Amount: 1.0")
Advance is the command name, Where and Amount are parameters, and Advance Down! and 1.0" are parameter data. This command advances the insertion point down one inch. The parameter names, Where and Amount, are optional.
Data types
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 BoxCaptionRotation are Degrees90!, Degrees180!, Degrees270!, and None!. Only these enumerations can replace the data type in the command syntax. Enumerations are identified by a trailing exclamation point. The most common data types in product commands are string, enumeration, and numeric. Programming commands frequently use variables.
Parameter names
Using parameter names is optional. For example, the command InhibitInput (State: Off!) works just like the command InhibitInput (Off!). Some product commands have no parameters. Their syntax is usually written with empty parameters, such as PosScreenUp (). Some programming commands and all system variables have no parameters. Their syntax is the command name alone, such as Pause and ?FeatureBar.
Italics
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: 21)
or
GraphicsLineLength (21)
Punctuation
You must enclose parameters in parentheses(()). A missing parenthesis 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.
You must 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,
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.
Spaces between command names and the opening parenthesis of the parameter section and after semicolons in parameters are optional.
Product commands are specific for each application. They perform various functions in that application, such as
displaying a dialog box(InitialCodesStyleDlg)
specifying settings, such as styles (BorderBottomLine), user settings (PrefZoom), or attributes (font)
enabling and disabling features (InhibitInput) or (TableCellIgnoreCalculation)
performing actions, such as inserting a file (FileInsert) or code, (PrinterCommand), renaming a bookmark (BookmarkRename), converting comments to text (CommentConvert), or moving the insertion point (PosColBottom)
playing macros that are included with the application (AddressMergeShippingMacro)
Product commands that report information (return value) about the state of an application or feature are sometimes called system variables. In Corel Presentations, system variables begin with a leading Env (EnvPaths). Some system variables in Corel Presentations have parameters as well as return values.
Using variables
A variable represents a place in memory where data is stored for use by a macro or a merge. As its name indicates, the data in a variable is changeable. All variables must be declared and named. The name and content are determined by the programmer. You can perform operations on variables and change the content. The variable name is used to access the value of the variable.
There are four different types of variables: local, global, persistent, and constant. When a variable is declared, its type determines how visible the variable is (scope) and how long the variable will exist in memory. By default, when a variable is declared, it is local.
Local, global, and persistent variables all have a valid use and purpose. It is important to understand the scope and duration of the variables in macros. In most situations, local variables should be used. Global and persistent variables may be a necessity in some cases, but should be used with care. Constant variables should be used sparingly, if at all.
Other programming languages force you to specify the type of data that will be stored in a variable. PerfectScript, however, is an untyped language-it does not force the user to specify the type of data that a variable will contain. If a variable called x was declared in WordPerfect, that variable could contain a text string or a number.
Declaring variables
Variables must be declared before they can be used. Declaring a variable instructs PerfectScript to set aside memory for the variable. When declaring a variable, you specify a name and, optionally, a value for the new variable. Variables may be initialized with a value at the time of declaration. The following sections show how to appropriately name variables and how to declare (and initialize) the four types of variables.
Naming variables
Variable names should be descriptive. Variable names must begin with a letter, can include any other combination of letters or numbers, must be 50 characters or less in length, and are not case sensitive. Variables that have a string value should be named with a lowercase 's' as the beginning character of the name. The lowercase 's' denotes string. Variables that have a numeric value should be named with a lowercase 'n' to denote number. Some example variable names follow:
// String values
sFirstName := "Claudia"
sAddress := "1625 East Nowhere St."
sBirthday := "6/12/69"
// Number values
nAge := 25
nTotal := 145.97
The preceding code sample shows some variable examples. Each variable above has a descriptive name to help you remember what type of value should be expected. The variables that were declared in these examples are local variables by default, because no variable type is specified.
Assigning variables in PerfectScript
A variable acts as a placeholder that represents a value, which can be text, numbers, or measurements, that can be used repeatedly in a macro. This value can be changed or manipulated. Variables are typically preceded by the letter "v." You can assign a variable.
To assign a variable
Type Assign where you want to define the variable.
If you want to assign the text "Claudia" to the variable "vName", type Assign (vName;"Claudia").
Tip
You can type a colon followed by the equals sign (:=) as a shortcut to assigning a variable. For example, you could type vName:="Claudia" for the above procedure.
Inserting commands with the Macro Command Browser
Product commands perform tasks that you would normally perform manually using WordPerfect Office applications. Many product commands require you to specify parameter values. These values give the application information about where and how to perform the task associated with the specified command. You can use the Macro Command Browser to choose commands and set parameters quickly.
You can use the Macro Command Browser to insert product or programming commands in a macro you are editing. If the command you choose has required parameters, you must set values for these before you insert the macro.
When you create macros using the Macro Command Browser, the commands are inserted in the correct format. If you type a macro without the Macro Command Browser, you must arrange macro commands and their elements in a precise order of syntax. Each macro command must be spelled correctly and must include all the required parameters and separators.
To insert a command using the Macro Command Browser
1 If the Macro toolbar is not already displayed, click Tools Macro Macro toolbar.
2 Click Commands.
3 Choose a product from the Command type list box.
4 Choose a command from the Commands list box.
If the Parameters list box does not display, proceed to step 7.
5 Choose any parameters from the Parameters list box.
If the Enumeration list box does not display, proceed to step 7.
6 Choose an enumeration from the Enumeration list box.
7 Type any additional parameters in the Command box.
8 Click Insert.
Note
A parameter that is displayed in bold is a required parameter. The macro will not compile or run without it. Other parameters are optional and may, in some cases, be useless depending on the values given to required parameters.
Tips
You can also insert system variables with the Macro Command Browser. System variables contain current system information, such as the current chart type or the default directory. In WordPerfect, system variables begin with a question mark (?). In Corel Presentations, system variables begin with the letters "Env."
You can add blank lines to separate programming commands and subroutines.
You can indent lines to show levels of nested commands.
Using macro commands to retrieve information
WordPerfect allows you to use commands, such as MessageBox or GetString, that gather information for macros. You can use these types of commands, for example, to prompt the user to type in information. For information about the MessageBox command, see the PerfectScript Programming Macros Help in the PerfectScript Macro Command Browser.
You can use the GetString command if you need to enter text that will be used by your macro. The GetString command uses the following format:
GetString (Var;Prompt Text; Title; MaxLength)
The Prompt text, Title, and Maximum length parameters are optional. The Var parameter specifies a string variable to load with text entered by the user. You can use the GetUnits command if you want the user to provide the macro with measurement information that can be used to move the insertion point and set margins. If you want the user to enter information for use in a numeric expression (such as addition or subtraction), you can use the GetNumber command. Both the GetUnits and GetNumber commands are similar to the GetString command; however, they do not use maximum parameter length. The user can use any of the abbreviations listed in the following table to represent units of measurement.
Unit of measurement Abbreviation
WP Units (1200 per inch) w
Points (72 per inch) p
Millimeters m
Centimeters c
Inches i or "
Note
If the user doesn't type a unit of measurement with the number when prompted, WordPerfect uses WP Units as the default unit of measurement.
Inserting codes into macros
You can use WordPerfect to insert a code into a macro.
To insert a code into a macro
1 On the Windows taskbar, click Start WordPerfect Office 11 WordPerfect 11.
2 Click Tools Macro Macro toolbar.
3 Click Codes.
4 Click one of the following tabs:
Search-allows you to select search find codes
Merge-allows you to select merge find codes
Date-allows you to select date find codes
Other-allows you to select chapter, page, section page, total page, and volume number find codes
5 Choose a code from the Find codes list.
6 Click Insert.
7 Click Close.
Note
When you insert a code into a macro, you must use straight double quotation marks around the code so that WordPerfect recognizes the code in the macro.
Compiling macros using the macro compiler
The programs that compile macros are called compilers. A macro compiler is used to compile or "translate" macros so that WordPerfect Office applications can play them. The macro compiler creates an object, which it saves in a hidden area of the source file (the macro compiler does not create a separate object file). When you edit the source file, the object is destroyed. The object is recreated each time the source file is compiled. Macros in WordPerfect are compiled when you record, play, save, save and compile them, or when you close the macro from the Macro toolbar. You must compile a macro before you can play it.
If you receive an error message while the macro is compiling, you must correct all the errors before the macro will play. For information about fixing compile errors, see "Fixing compile errors."
To compile a macro
Click the Save & compile button on the Macro toolbar.
Note
If a macro you compile has error messages, WordPerfect still saves it even if you do not fix the compile errors. For information about fixing compile errors, see "Fixing compile errors."
Fixing compile errors
Macros have three types of errors: syntax errors, run-time errors, and logic errors. You can set PerfectScript to generate a list when you compile a macro. You can also use the PerfectScript debugger to find errors. WordPerfect lets you to test for errors from inside the PerfectScript utility. WordPerfect allows you several options for debugging macros. You can debug macros step-by-step so that the macro executes the current commands and stops at the next command. You can also debug macros with a breakpoint so that the macro executes all the commands in the macro until it reaches the breakpoint. Macro breakpoints are set by default to be the beginning of the macro, the end of the macro, and at any errors. WordPerfect also lets you debug a macro by briefly displaying or "animating" each command before it is executed.
Animation allows you to step through macros line by line, automatically bringing up the debugging dialog box at each step so you can check the variables and other calls. You can specify how long the debugger will pause before moving to the next step.
You can also view the meaning of commands from the PerfectScript debugger.
Identifying syntax errors
Syntax errors appear when you are compiling a macro. The PerfectScript compiler flags unrecognizable commands, such as missing parentheses or semi-colons and incorrectly spelled command names.
The compiler identifies syntax errors and suggests solutions. The error message displays information about the error and its location. The compiler makes a best guess and may not always be accurate.
Common syntax errors include
missing semicolons between parameters
missing parentheses
missing double quotation marks
missing command in a conditional or loop statement
misspelled macro command names
undefined calling statements
using commas between parameters instead of semicolons
Identifying run-time errors
Run-time is the same as execution time. Run-time errors occur while the macro is playing. Referencing a variable that has not been assigned a value causes a run-time error. Run-time error messages identify errors that occur while the macro plays and show where errors occur.
Identifying logic errors
When a macro does not produce the expected result, you may have a logic error. When a macro has a logic error, it plays without producing any error messages because WordPerfect accepts all of the macro commands.
To set PerfectScript to generate a listing file when you compile a macro
1 On the Windows taskbar, click Start Programs WordPerfect Office 11 Utilities PerfectScript.
2 Click Tools Settings.
3 Click the Compile tab.
4 Enable the Generate listing file check box.
Note
When you generate a listing file, PerfectScript saves it with a .wcl filename extension, and it is saved to the same location as the macro you are compiling.
To use the PerfectScript debugger to find errors
1 Click Tools Macro Edit.
2 Choose the macro you want to debug.
3 Click Edit.
4 Click where you want to begin debugging the macro.
5 Type Step (On!).
If you want to display a debug window, type Display (On!).
6 Click Save & compile.
7 Type a file path and filename in the Listing filename box.
To debug a macro from PerfectScript
1 Click File Debug Play.
2 Choose the macro you want to debug.
3 Type a file path and filename in the Listing filename box.
4 Click OK.
5 Click Debug Step into.
To set a macro breakpoint
1 Select the line of the macro in which you want to insert a breakpoint.
2 Click Debug Breakpoint Add.
The Breakpoint symbol displays beside the line in which you added the breakpoint.
To debug a macro with a breakpoint
1 Select the line of the macro in which you want to insert a breakpoint.
2 Click Debug Breakpoint Add.
The Breakpoint symbol displays beside the line in which you added the breakpoint.
3 Click Debug Continue.
To animate a macro
1 Click Edit Settings.
2 Click the Debug tab.
3 In the Animate settings area, enable one of the following options:
RunTo does 'step into'-executes the next single statement
RunTo does 'step over'-executes the call of the label or routine without stopping until it has completed
4 Type a value in the Delay (seconds) box.
This value specifies the number of seconds the macro should display after executing each step.
5 Click OK.
6 Click Debug Animate.
Tip
When correcting compilation errors, start at the beginning, correcting errors that are obvious and leaving the others until later, as some of these errors may have been caused by an earlier error.
To view the meaning of commands from the PerfectScript debugger
Point to a command line.
When you pause on a line of code, the command or variable name and definition is displayed.
Editing and deleting macros in PerfectScript
You can edit a macro by adding new and modifying existing commands. If you have written a macro for Corel Presentations, you can only edit the macro from within WordPerfect or by using the PerfectScript utility. You can also delete macros.
To edit a macro
1 Click Tools Macro Edit.
2 Choose the drive and folder where the macro is stored.
3 Click a filename.
4 Click Edit.
5 Edit the macro commands.
6 Click Save & compile.
7 Click Options Close macro on the macro toolbar.
To delete a macro
1 Click Tools Macro Edit.
2 Choose a macro.
3 Press DELETE.
Adding search capabilities to macros
WordPerfect allows you to add search capabilities to a macro. You can apply all of the search functionality included in WordPerfect when you are searching in a macro.
To add search capabilities to a macro
1 Click Tools Macro Edit.
2 Click in the macro where you want to add the search capability.
3 Click Tools Macro Record.
4 Click Edit Find and replace.
5 Type text in the Find box.
If you want to search for codes, click Match Codes, and choose any codes from the Find codes list box.
