Chapter 11

See Graphic.

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.