Chapter 11
Corel® PerfectScript® 8 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.
SendKeys
Purpose
Send keystrokes to the application that has focus.
Make sure focus is where it should be. Most errors using SendKeys occur when keys are sent to the wrong place.
Keys such as Alt or F1 must be enclosed in braces to specify a single keystroke. For example,
SendKeys("{Alt}LLH")
sends four keystrokes (Alt, L, L, and H) which opens the Line Height dialog box. The following commands are equivalent to the previous example:
SendKeys("{Alt + L + L + H}")
SendKeys("{Alt}{L}{L}{H}")
If you combine keystrokes in a single set of braces, you must separate them with a plus operator; otherwise, the result is unpredictable. Enclosing single character keystrokes in braces is optional.
Assign frequently used keystrokes to a variable. For example,
KS_MarginsDlg := "{Alt}LM"
SendKeys(KS_MarginsDlg)
opens the Margins dialog box, and is equivalent to the Corel WordPerfect product command FormatMarginsDlg.
A minus operator releases a keystroke. For example,
SendKeys("{Shift+Del-Del+Ins}")
cuts selected text to the Clipboard (Shift+Del), then pastes it at the insertion point (Shift+Ins).
SendKeys is always processed immediately. For example,
Application(A1; "WordPerfect"; Default; "US")
Display(On!)
InhibitInput(Off!)
SendKeys("{Alt + F}{O}")
opens the Corel WordPerfect Open File dialog box.
Note
In Corel WordPerfect, set InhibitInput(Off!) for SendKeys to operate correctly.
Syntax
SendKeys (KeyCode: string; [MarkupLanguage: enumeration])
Parameters
KeyCode
string The keystrokes to send.
{VKnnn} nnn = ANSI character number
{Alt}
{Ctrl}
{Control}
{Shift}
{0} - {9} Digits
{A} - {Z} Alphabet
{F1} - {F16} Function keys
{NumLock}
{NumAdd}
{NumSubtract}
{NumMultiply}
{NumDivide}
{NumDecimal}
{Num0} - {Num9} Numpad numbers
{Left}
{Right}
{Up}
{Down}
{PgDn}
{PageDown}
{PgUp}
{PageUp}
{Bksp}
{Backspace}
{Break} Cancel
{CapsLock}
{Clear}
{Del}
{Delete}
{End}
{Enter}
{Esc}
{Escape}
{Help} VK Help key
{Home}
{Ins}
{Insert}
{Minus}
{Pause}
{ScrLock}
{ScrollLock}
{PrintScrn}
{PrintScreen}
{Space}
{Tab}
{LeftBrace} {
{RightBrace} }
MarkupLanguage
enumeration (optional) Specify which language interprets the key codes. Default: New! The values are:
Old!
New!
SetCurrentDirectory
Purpose
Specify a new default directory.
Example
Appendix A: 8079
Return Value
Return True if successful, False if not.
Syntax
boolean := SetCurrentDirectory (DirectoryName: string)
Parameters
DirectoryName
string Include the full path.
SetFileAttributes
Purpose
Change file attributes.
Example
Appendix A: 8083
Return Value
Return True if successful, False if not.
Syntax
boolean := SetFileAttributes (Filename: string; [Attributes: enumeration]; [Prompts: enumeration])
Parameters
Filename
String
Attributes
enumeration (optional) Default: Normal!
Normal!
ReadOnly!
Hidden!
System!
Label!
Directory!
Archived!
Prompts
enumeration (optional) Prompt if attribute does not exist. Default: NoPrompts!
NoPrompts!
Prompts!
SetFileDateAndTime
Purpose
Change the date and time a file was last written to.
Example
Appendix A: 8085
Return Value
Return True if successful, False if not.
Syntax
boolean := SetFileDateAndTime (Filename: string; [DateAndTime: numeric])
Parameters
Filename
string Include the full path and filename.
DateAndTime
numeric (optional) This value is returned from DateAndTime.
Sign
Purpose
Return the sign of a value.
Return Value
Return -1 if Value is less than 0, 0 if Value equals 0, and 1 if Value is greater than 0.
Syntax
numeric := Sign (Value: numeric)
Parameters
Value
numeric Return the sign of this value.
sin
Purpose
Get the sine of an angle in radians.
Return Value
Sine of an angle in radians.
Syntax
numeric := sin (Angle: numeric)
Parameters
Angle
numeric The angle in radians.
sinh
Purpose
Get the hyperbolic sine of an angle in radians.
Return Value
Hyperbolic sine of an angle in radians.
Syntax
numeric := sinh (Angle: numeric)
Parameters
Angle
numeric The angle in radians.
SizeOf
Purpose
Get the size needed to store a specified data value.
This command is mostly used with BinaryPack and BinaryUnpack.
Return Value
Size needed to store a specified data value.
Syntax
numeric := SizeOf (Value: any)
Parameters
Value
any (optional) The value to compute the size of. If missing, the size of the Corel PerfectScript system overhead for storing a value is returned.
Speed
Purpose
Slow macro execution.
Time is measured in tenths of a second. Speed(0) runs at maximum speed. Speed(5) delays a macro one-half second between statements. The maximum delay is one minute or Speed(600). The following example delays one second between beeps.
Speed(10)
Beep
Beep
Beep
Example
Appendix A: 8035
Syntax
Speed (TenthsOfSeconds: numeric)
Parameters
TenthsOfSeconds
numeric A number from zero to 600. Divide the number by 10 to calculate the number of seconds.
SquareRoot
Purpose
Get the square root of a value.
Return Value
Square root.
Syntax
numeric := SquareRoot (Value: numeric)
Parameters
Value
Numeric
Step
Purpose
Turn on Macro Debugger single stepping.
See Corel PerfectScript Help for information about the debugger itself.
Syntax
Step (State: enumeration)
Parameters
State
Enumeration
Off!
On!
String
Purpose
Pass a value as an ANSI string (DLL call in- line parameter function). See DLLCall.
Syntax
string := String (<Value> string)
StrFill
Purpose
Fill (replicate) a string a specified number of times.
Return Value
Replicated string.
Examples
vStr := StrFill (2; "PerfectScript")
MessageBox (x; "StrFill"; "..." + vStr + "...")
Result: ...PerfectScriptPerfectScript...
vStr := StrFill (2)
MessageBox (x; "StrFill"; "..." + vStr + "...")
Result: ... ...
Syntax
string := StrFill (Count: numeric; [String: string])
Parameters
Count
numeric The number of times to duplicate String. If Count is less than or equal to zero, an empty ("") string is returned.
String
string (optional) The string to repeat. If String is missing, spaces are used.
StrFraction
Purpose
Get the numeric value of a string representing a fraction.
vFrac := StrFraction ("1/2")
Result: vFrac = 0.5
vFrac := StrFraction ("187 7/8")
Result: 187.875
Return Value
Numeric value of a string representing a fraction.
Syntax
numeric := StrFraction (String: string)
Parameters
String
string The string to convert. The form of the string is "n/n" or "n n/n".
StrInsert
Purpose
Insert a substring into a string, replace characters in a string, or remove characters from a string.
Return Value
The modified string.
Examples
vStr := StrInsert ("Corel Corporation"; ""; 6; 12)
MessageBox (x; "StrInsert"; "..." + vStr + "...")
Result: ...Corel...
vStr := StrInsert ("Corel Corporation"; "anada"; 8; -1)
MessageBox (x; "StrInsert"; "..." + vStr + "...")
Result: ...Corel Canada...
vStr := StrInsert ("Corel Corpxxxtion"; "ora"; 11; 3)
MessageBox (x; "StrInsert"; "..." + vStr + "...")
Result: ...Corel Corporation...
Syntax
string := StrInsert (String: string; [SubString: string]; [Beginning: numeric]; [NumberOfChars: numeric])
Parameters
String
string The original string.
SubString
string (optional) The string to insert into String. If missing, characters are removed from String.
Beginning
numeric (optional) The starting position for inserting SubString, or for removing characters from String. If missing, the starting position is the end of the string. If less than zero, the starting position is the absolute value taken from the end of the string. See the example above.
NumberOfChars
numeric (optional) The number of characters replaced by SubString. If SubString is missing, the number of characters to remove from String. If NumberOfChars is missing or equal to zero, no characters are removed. If less than zero, all characters from the starting position to the right are either replaced by SubString or removed.
StrIsChar
Purpose
Determine whether a string or character is of a specified type.
Return Value
True if String is of type CharSet, False if not.
Syntax
boolean := StrIsChar (String: string; [Position: numeric]; [Option: enumeration]; [CharSet: string or enumeration])
Parameters
String
string The string to test.
Position
numeric (optional) The position of a character to test. If missing or 0, all characters are tested. If greater than the length of String, False is returned. If less than 0, the starting position is the absolute value taken from the end of the string (-1 tests the last character in the string, -2 the second to last character, and so forth).
Option
enumeration (optional) Specify matching criteria. If missing, EqualTo! is used. If CharSet is also missing, NotEqualTo! is used and WhiteSpace! is used for CharSet.
EqualTo!
Test for a character in the specified character set.
NotEqualTo!
Test for a character that is not in the specified character set.
CharSet
string or enumeration (optional) The set of characters to test. If missing, WhiteSpace! is used. CharSet may be a user- defined character set, specified as a character string expression such as "abcdef", or any combination of the character sets listed below. Type | between enumerations to combine character sets.
Alphabetic!
AlphaNumeric!
Numeric!
Punctuation!
WhiteSpace!
UpperCase!
LowerCase!
StrLeft
Purpose
Get the left part of a string.
vStr := StrLeft ("Corel Corporation"; 5)
MessageBox (x; "StrLeft"; "..." + vStr + "...")
Result: ...Corel...
vStr := StrLeft ("Corel Corporation ")
MessageBox (x; "StrLeft"; "..." + vStr + "...")
Result: ...Corel Corporation...
Return Value
Left part of a string.
Syntax
string := StrLeft (String: string; [Length: numeric])
Parameters
String
string The original string.
Length
numeric (optional) The length of string to return from the left side. If Length is greater than String length, the original string is returned. If Length is is missing, or less than or equal to zero, leading whitespace is removed.
StrLen
Purpose
Return the number of characters in a string.
The string can be a variable, constant, character string, or result of an expression.
vWord := "WordPerfect"
vNumber := StrLen(vWord)
Result: vNumber equals 11
vNumber := StrLen(45899)
Result: vNumber equals 5
vNumber := StrLen("WordPerfect")
Result: vNumber equals 11
vNumber := StrLen(9 + 9)
Result: vNumber equals 2
Example
Appendix A: 8036
Return Value
The number of characters in a string.
Syntax
numeric := StrLen (String: string)
Parameters
String
string A variable, constant, character string, or result of an expression.
StrMakeList
Purpose
Return a list of substrings.
Return Value
The string list of SubString items.
Syntax
string := StrMakeList ([Separator: string]; {SubString: string})
Parameters
Separator
string (optional) The string to insert between SubString items. If missing, ";" is used.
SubString
string (repeating) The repeating group of items from which to make a list.
StrNum
Purpose
Convert a character string of numbers to a numeric equivalent.
Example
Appendix A: 8037
Return Value
A number.
Examples
vNum := StrNum("123")
Result: vNum = 123
vNum := StrNum("123.5")
Result: vNum = 123.5
vNum := StrNum("9 + 9")
Result: vNum = 9
Syntax
string := StrNum (String: string)
Parameters
String
string Contains a character string of numbers. StrNum recognizes the decimal point defined by the sDecimal setting in the [intl] section of the Windows WIN.INI file. Alphabetic characters, operators, and punctuation marks, and everything that follows them are ignored.
StrPad
Purpose
Pad (lengthen) a string to a specified length.
Return Value
The padded string.
Examples
In the following examples, PadString consists of numbers to illustrate the command. Any string of characters, including spaces, could have been used.
vPad := StrPad ("Corel"; 15; PadRight!; "12345")
MessageBox (x; "StrPad"; vPad)
Result: Corel1234512345
vPad := StrPad ("Corel"; 15; PadLeft!; "12345")
MessageBox (x; "StrPad"; vPad)
Result: 1234512345Corel
vPad := StrPad ("Corel"; 15; PadEnds!; "12345")
MessageBox (x; "StrPad"; vPad)
Result: 12345Corel12345
vPad := StrPad ("Corel1products2are3great"; 30; PadWords!; "12345")
MessageBox (x; "StrPad"; vPad)
Result: Corel111Products222are333great
Syntax
string := StrPad (String: string; Length: numeric; [Option: enumeration]; [PadString: string])
Parameters
String
string The string to be padded.
Length
numeric The final length of the padded string. If the length is less than or equal to zero, or less than the length of String, the original string is returned.
Option
enumeration (optional) Specify where padding is to be added. Default: PadRight!
PadRight!
Pad the end of the string.
PadLeft!
Pad the front of the string.
PadEnds!
Pad both ends, centering the string.
PadWords!
Spread the padding between words, expanding String to the specified length. Words must be separated by a character in PadString, or PadEnds! is used.
PadString
string (optional) Multiples of characters in this string pad String to the specified length. PadString may be any string of characters (it is not limited to a single character). If missing, spaces are used. If the string is empty (""), no padding is done. See the examples above.
StrParseList
Purpose
Parse a string list into substrings.
Return Value
The array of substrings (a substring occupies each array element).
Syntax
array := StrParseList (String: string; [Separators: string or enumeration]; [Option: enumeration])
Parameters
String
string The string to parse.
Separators
string or enumeration (optional) Characters or a string that separate(s) the substrings in String. This parameter is either a string of characters or an enumeration that specifies any combination of predefined character sets. It represents individual characters, all of which are used to separate substrings, or as a string (see the Option parameter). If missing, ";" is used.
Punctuation!
Separator characters are the set of punctuation characters.
WhiteSpace!
Separator charactes are the set of whitespace characters.
Option
enumeration (optional) Specifies how to interpret the Separators parameter. If missing, and Separators is a predefined character set, Characters! is used. Otherwise, Strings! is used.
Characters!
Any number of individual characters separates substrings in String (see the Separator parameter). Ignores multiple separators.
Strings!
An entire string of characters separates substrings in String.
StrPos
Purpose
Determine whether a character string is also a substring.
Example
Appendix A: 8039
Return Value
The beginning position of a substring, or zero if a substring is not found.
Examples
vPos := StrPos("WordPerfect"; "Perfect")
Result: vPos = 5
vPos := StrPos("WordPerfect"; "Scott")
Result: vPos = 0
vPos := CharPos("Corel WordPerfect"; "or"; 7)
Result: vPos = 8
Explanation: Search begins at character position 7, bypassing the first occurrence of the substring.
Syntax
numeric := StrPos (String: string; SubString: string; [Beginning: numeric])
Parameters
String
string A character string to evaluate.
Substring
string A substring to locate in String parameter.
Beginning
numeric (optional) Default: 1. Begin looking for Substring at this character position (see the example above).
StrReverse
Purpose
Reverse all characters in a string.
Return Value
The string in reverse character order.
Syntax
string := StrReverse (String: string)
Parameters
String
string The original string.
StrRight
Purpose
Get the right part of a string.
vStr := StrRight ("Corel Products"; 8)
MessageBox (x; "StrRight"; "..." + vStr + "...")
Result: ...Products...
vStr := StrRight (" Corel Products")
MessageBox (x; "StrRight"; "..." + vStr + "...")
Result: ...Corel Products...
Return Value
Right part of a string.
Syntax
string := StrRight (String: string; [Length: numeric])
Parameters
String
string The original string.
Length
numeric (optional) The length of the string to return from the right side. If Length is greater than String length, the original string is returned. If Length is 0, an empty ("") string is returned. If Length is missing, or less than or equal to zero, leading whitespace is removed.
StrScan
Purpose
Return the index (position) of the first matching or non-matching character.
Return Value
If no matching or non-matching characters are found, the length of String plus 1 is returned (or 0 if scan was reversed).
Syntax
numeric := StrScan (String: string; [Beginning: numeric]; [Option: enumeration]; [CharSet: string or enumeration])
Parameters
String
string The string to scan.
Beginning
numeric (optional) Ths position at which to start the scan. If missing or zero, the starting position is 1. If less than zero, the starting position is the absolute value taken from the end of the string, scanning backwards.
Option
enumeration (optional) Specify matching criteria. If missing, EqualTo! is used. If CharSet is also missing, NotEqualTo! is used and WhiteSpace! is used for CharSet.
EqualTo!
Scan until a character in the specified character set is found.
NotEqualTo!
Scan until a character not in the specified character set is found.
CharSet
any (optional) The set of characters to match or skip over. If missing, WhiteSpace! is used. CharSet may be a user-defined character set, specified as a character string expression such as "abcdef", or any combination of the predefined character sets listed below. Type | between enumerations to combine character sets.
Alphabetic!
AlphaNumeric!
Numeric!
Punctuation!
WhiteSpace!
UpperCase!
LowerCase!
StrToChars
Purpose
Remove characters from a string.
Return Value
Transformed string.
Examples
vStr := StrToChars ("Win95!"; Remove!; Alphabetic!
| Punctuation!)
MessageBox (x; "StrToChars"; vStr)
Result: vStr = 95
vStr := StrToChars ("Win95!"; Keep!; Alphabetic!
| Punctuation!)
MessageBox (x; "StrToChars"; vStr)
Result: vStr = Win!
vStr := StrToChars ("Win95!"; Keep!; "95")
MessageBox (x; "StrToChars"; vStr)
Result: vStr = 95
Syntax
string := StrToChars (String: string; [Option: enumeration]; [CharSet: string or enumeration])
Parameters
String
string The original string.
Option
enumeration (optional) Specify whether characters are to be kept or removed. If missing, Keep! is used. If CharSet is also missing, Remove! is used and WhiteSpace! is used for CharSet.
Keep!
Keep specified characters, remove all others.
Remove!
Remove specified characters.
CharSet
string or enumeration (optional) The set of characters to keep or remove. If missing, WhiteSpace! is used. CharSet may be a user-defined character set, specified as a character string expression such as "abcdef", or any combination of the predefined character sets listed below. Type | between enumerations to combine character sets.
Alphabetic!
AlphaNumeric!
Numeric!
Punctuation!
WhiteSpace!
UpperCase!
LowerCase!
StrTransform
Purpose
Convert a string of characters into other characters.
Return Value
Transformed string.
Syntax
string := StrTransform (String: string; FromChars: string; [ToChars: string]; [Options: enumeration])
Parameters
String
string The string to transform.
FromChars
string The characters in String to transform.
ToChars
string (optional) The replacement characters. There is a one-to- one correspondence between FromChars and ToChars. Characters in String that are in FromChars are replaced by characters in ToChars in the equivalent positions. For example, the result of
vStr := StrTransform ("12345"; "2345"; "xxxx")
is that "1xxxx" is returned in vStr. If ToChars is missing or shorter than FromChars, all characters are removed from String that match characters in FromChars but have no corresponding character in ToChars.
Options
enumeration (optional) Control the interpretation of FromChars and ToChars, and how many transformations are performed. Default: Characters! | All!
Characters!
Characters are transformed independently.
Strings!
The string of characters is transformed as a whole.
FirstOnly!
Transform only the first occurence of characters in FromChars.
All!
Transform all occurences of characters in FromChars. Use a number to specify a specific number of occurrences to transform.
StrTrim
Purpose
Trim (remove) characters from a string.
Return Value
The string trimmed of characters to a specified length.
Syntax
string := StrTrim (String: string; [Length: numeric]; [Option: enumeration]; [TrimChars: string or enumeration])
Parameters
String
string The string to be trimmed.
Length
numeric (optional) The final length of the trimmed string. If Length is greater than the length of String, no trimming is done and the original string is returned. If Length is missing, or less than or equal to zero, String is trimmed until all matching characters are removed at specified locations (see Option below). If the length of String after trimming exceeds Length, no further trimming is done.
Option
enumeration (optional) Specify where String is to be trimmed. Characters matching TrimChars are removed from specified locations until Length is reached, or until no more matching characters are found. Default: TrimRight!
TrimRight!
Trim characters from the end of the string.
TrimLeft!
Trim characters from the front of the string.
TrimEnds!
Trim characters from both ends, centering the string.
TrimWords!
Trim multiple characters within String, reducing String to specified length. If the length of String still exceeds Length after trimming multiple characters, the ends are trimmed like TrimEnds!
TrimChars
string or enumeration (optional) The characters to be trimmed from String (all matching characters are removed). If missing, WhiteSpace! is used. TrimChars may be a user- defined character set, specified as a character string expression such as "abcdef", or any combination of the predefined character sets listed below. If TrimChars is empty (""), no trimming is done. Type | between enumerations to combine character sets.
Alphabetic!
AlphaNumeric!
Numeric!
Punctuation!
WhiteSpace!
UpperCase!
LowerCase!
Structure
Purpose
Pass a value as a C struct (DLL call in-line parameter function). See DLLCall.
Return Value
string
Syntax
string := Structure (<Value> string)
StrUnit
Purpose
Convert a string of numbers to a measurement.
The string may contain a number, an arithmetic expression that results in a number, or a character string of numbers. If a character string is used, alphabetic characters (except units of measure), operators, and punctuation marks are ignored. The default unit of measure is WordPerfect units. You can change the default using DefaultUnits, or by specifying a unit of measure as part of the character string.
DefaultUnits(Centimeters)
vUnit := STRunIT(9)
Result: vUnit equals 9.C
vUnit :equals STRunIT(4+3)
Result: vUnit equals 7.C
vUnit :equals STRunIT("10")
Result: vUnit equals 10.C
vUnit :equals STRunIT("10abc")
Result: vUnit equals 10.C
vUnit :equals STRunIT("10i")
Result: vUnit equals 10I
The units of measure are:
" inches
i inches
c centimeters
m millimeters
p points (72 per inch)
w WP units (1200 per inch)
Example
Appendix A: 8038
Return Value
A unit of measure.
Syntax
numeric := StrUnit (String: string)
Parameters
String
string A number or character string of numbers.
SubChar
Purpose
Extract a substring from a character string. Use CharPos to locate a substring.
Example
Appendix A: 8013
Return Value
A character string.
// vSub = "Word"
vSub := SubChar("WordPerfect"; 1; 4)
Syntax
string := SubChar (String: string; Beginning: numeric; [NumberOfChars: numeric])
Parameters
String
string A character string to evaluate.
Beginning
numeric The starting position of a substring. Negative numbers begin from the end of the string (-1 is the last character).
NumberOfChars
numeric (optional) The number of characters to extract. If missing, the rest of the string is extracted.
SubStr
Purpose
Extract a substring from a character string. Use StrPos to locate a substring.
Example
Appendix A: 8039
Return Value
A character string.
// vSub = "Word"
vSub := SubStr("WordPerfect"; 1; 4)
Syntax
string := SubStr (String: string; Beginning: numeric; [NumberOfChars: numeric])
Parameters
String
string A character string to evaluate.
Beginning
numeric The starting position of a substring. Negative numbers begin from the end of the string (-1 is the last character).
NumberOfChars
numeric (optional) The number of characters to extract. If missing, the rest of the string is extracted.
Sum
Purpose
Get the sum of a list of values.
Return Value
Sum of a list of values.
Syntax
numeric := Sum ({Value: numeric})
Parameters
Value
numeric The list of values. Separate multiple values with a semicolon.
Switch
Purpose
A conditional statement that tests for matching expressions. If a match is found, a statement (or statement block) is executed. See Conditional Statements in Chapter 5: Conditional, Loop, and Calling Statements.
If Test matches Selector, the statement block that follows Selector is executed and no other evaluation is made. Test and Selector are case sensitive and must match exactly.
If Continue follows an executed statement block, the next statement block is automatically executed. Continue is optional.
The DEFAULT statement block is executed if no Selector matches Test. DEFAULT is optional. If no match is found and DEFAULT is not used, the macro continues to the first statement after EndSwitch.
If Break occurs in a state block, the macro continues to the first statement after EndSwitch.
EndSwitch closes a Switch statement.
The general form of a Switch statement is:
Switch (<Test>)
CaseOF <Selector>:
...statement block...
Continue
CaseOF <Selector>:
...statement block...
Default:
...statement block...
EndSwitch
Example
Appendix A: 8002
Syntax
Switch (<Test> any)
Parameters
<Test>
any The control expression. Variables are assigned values by commands such as GetString, GetNumber, or Menu.
<Selector>
any An expression (variable, constant, character) with a value that is usually assigned before the macro is compiled. It is possible to assign the value at run-time. Selector always follows a CaseOF statement.