Copyright: Copyright © Corel Corporation Limited. 1996.   Tue Feb 11 12:15:53 1997All rights reserved.
Citation: Copyright © Corel Corporation Limited. 1996. %date  All rights reserved.


[]

Any := [] Numeric

Operator.

Return Value

Returns the specified element of an array.


~

Numeric := ~ Numeric

Operator.  Precedence level 1.

Return Value

Returns the bitwise complement of a number (toggles binary value 1 to 0, or 0 to 1).  See Bitwise Operators.


**

Numeric := Numeric ** Numeric

Operator.  Precedence level 2.

Return Value

Returns the left operand raised to the power of the right operand.  See Arithmetic Operators.

Example

vResult = 2**3

Result: vResult = 8 (2 to the 3rd power)


*

Numeric := Numeric * Numeric

Operator.  Precedence level 3.

Return Value

Returns the product of two numbers.  See Arithmetic Operators.


/

Numeric := Numeric / Numeric

Operator.  Precedence level 3.

Return Value

Returns the floating point quotient of two numbers.  See Arithmetic Operators.


%

Numeric := Numeric % Numeric

Operator.  Precedence level 3.

Return Value

Returns the floating point division remainder.  See Arithmetic Operators.


+

Any := Any + Any

Operator.  Precedence level 4.

Return Value

Returns the sum of two numbers or the result of concatentating two strings.  See Arithmetic Operators.

Examples

vNmbr := 10 + 10

Result: vNmbr = 20

vStr := "abcdefg" + "xyz"

Result: vStr = "abcdefgxyz"


+

Any := Any + Any

Operator.  Precedence level 4.

Return Value

Returns the sum of two numbers or the result of concatentating two strings.  See Arithmetic Operators.

Examples

vNmbr := 10 + 10

Result: vNmbr = 20

vStr := "abcdefg" + "xyz"

Result: vStr = "abcdefgxyz"


-

Any := Any - Any

Operator.  Precedence level 4.

Return Value

Returns the difference between two numbers or the result of removing one string from another.  If the right string does not occur in the left string, the left string is returned unchanged.  See Arithmetic Operators.

Examples

vNmbr := 10 - 10

Result: vNmbr = 0

vStr := "abcdefg" - "cd"

Result: vStr = "abefg"


-

Any := Any - Any

Operator.  Precedence level 4.

Return Value

Returns the difference between two numbers or the result of removing one string from another.  If the right string does not occur in the left string, the left string is returned unchanged.  See Arithmetic Operators.

Examples

vNmbr := 10 - 10

Result: vNmbr = 0

vStr := "abcdefg" - "cd"

Result: vStr = "abefg"


<<

Numeric := Numeric << Numeric

Operator.  Precedence level 5.

Return Value

Returns the numeric result of shifting bits one or more positions left.  This operator works only on integer data.  See Bitwise Operators.


>>

Numeric := Numeric >> Numeric

Operator.  Precedence level 5.

Return Value

Returns the numeric result of shifting bits one or more positions right.  This operator works only on integer data.  See Bitwise Operators.


<<<

Numeric := Numeric <<< Numeric

Operator.  Precedence level 5.

Return Value

Returns the numeric result of rotating bits one or more positions to the left.  Rotated bits off the left end are inserted on the right end of the value (shifted bits are lost).  This operator works only on integer data.  See Bitwise Operators.


>>>

Numeric := Numeric >>> Numeric

Operator.  Precedence level 5.

Return Value

Returns the numeric result of rotating bits one or more positions to the right.  Rotated bits off the right end are inserted on the left end of the value (shifted bits are lost).  This operator works only on integer data.  See Bitwise Operators.


=

Boolean := Any = Any

Any := Variable = AnyThe = operator has two functions.

Relational Operator

Operator.  Precedence level 6.

Return Value

Returns True if two operands are equal, or False if not.  See Relational Operators.

This operator is defined for values and arrays.  Two arrays are equal if they have the same number of dimensions and all corresponding elements are equal.

Examples

z := {1; 2; 3} = {1; 2; 3}

Result: z = True

z := {1; 2; 3} = {1; 3; 2}

Result: z = False

z := {1; 2; 3} = {1; 2; 3; 4}

Result: z = False

Operator Assigning Value

Operator.  Precedence level 10.

Assigns a value to a variable.  See Assign.


<>

Boolean := Any <> Any

Operator.  Precedence level 6.

Return Value

Returns False if two operands are equal, or True if not.  See Relational Operators.

This operator is defined for values and arrays.  Two arrays are not equal if they have different dimensions or if at least one corresponding element is not equal.

Examples

z := {1; 2; 3} <> {1; 2; 3}

Result: z = False

z := {1; 2; 3} <> {1; 3; 2}

Result: z = True

z := {1; 2; 3} <> {1; 2; 3; 4}

Result: z = True


!=

Boolean := Any != Any

Operator.  Precedence level 6.

Return Value

Returns False if two operands are equal, or True if not.  See Relational Operators.

This operator is defined for values and arrays.  Two arrays are not equal if they have different dimensions or if at least one corresponding element is not equal.

Examples

z := {1; 2; 3} != {1; 2; 3}

Result: z = False

z := {1; 2; 3} != {1; 3; 2}

Result: z = True

z := {1; 2; 3} != {1; 2; 3; 4}

Result: z = True


<

Boolean := Any < Any

Operator.  Precedence level 6.

Return Value

Returns True if the left operand is less than the right, or False if not.  See Relational Operators.


<=

Boolean := Any <= Any

Operator.  Precedence level 6.

Return Value

Returns True if the left operand if less than or equal to the right, or False if not.  See Relational Operators.


>

Boolean := Any > Any

Operator.  Precedence level 6.

Return Value

Returns True if the left operand is greater than the right, or False if not.  See Relational Operators.


>=

Boolean := Any >= Any

Operator.  Precedence level 6.

Return Value

Returns True if the left operand is greater than or equal to the right, or False if not.  See Relational Operators.


&

Numeric := Numeric & Numeric

Operator.  Precedence level 7.

Return Value

Returns bitwise AND of two numbers.  Bit result is 1 if both bits are 1, and 0 if not.  See Bitwise Operators.


|

Numeric := Numeric | Numeric

Operator.  Precedence level 7.

Return Value

Returns bitwise OR of two numbers.  Bit result is 1 if both bits are 1 or bits do not match, and 0 if both bits are 0.  See Bitwise Operators.


^

Numeric := Numeric ^ Numeric

Operator.  Precedence level 7.

Return Value

Returns bitwise XOR (exclusive OR) of two numbers.  Bit result is 0 if bits match, and 1 if not.  See Bitwise Operators.


:=

Variable := Any

Operator.  Precedence level 10.  Assigns a value to a variable.  See Assign.


=

Boolean := Any = Any

Any := Variable = AnyThe = operator has two functions.

Relational Operator

Operator.  Precedence level 6.

Return Value

Returns True if two operands are equal, or False if not.  See Relational Operators.

This operator is defined for values and arrays.  Two arrays are equal if they have the same number of dimensions and all corresponding elements are equal.

Examples

z := {1; 2; 3} = {1; 2; 3}

Result: z = True

z := {1; 2; 3} = {1; 3; 2}

Result: z = False

z := {1; 2; 3} = {1; 2; 3; 4}

Result: z = False

Operator Assigning Value

Operator.  Precedence level 10.

Assigns a value to a variable.  See Assign.


//

// <CommentText>

  Example

The compiler ignores all text between // and the next hard return [HRt].

Comment text does not affect macro execution.  The comment line, including spaces, has a maximum length of 512 characters.


[0]

Numeric := array[0]

Provides access to the number of elements in an array variable (this is not a command).  Specify zero as the index regardless of the number of dimensions.

The same value is returned by the command vElements := Dimensions (array[]; 0).  See Dimensions.

Example

Declare Array[3; 5; 6]

vElements := Array[0]

Result: vElements = 90


AbsVal

Numeric := AbsVal (Value: Numeric)

Returns the absolute value of a value.

Parameter

Value: Numeric

Value to get the absolute value of.


acos

Numeric := acos (Value: Numeric)

Returns an angle in radians for a specified inverse (arc) cosine.

Parameters

Value: Numeric

Cosine.


acosh

Numeric := acosh (Value: Numeric)

Returns an angle in radians for a specified inverse (arc) hyperbolic cosine.

Parameters

Value: Numeric

Hyperbolic cosine.


Address

Variable := Address (<VariableName> Variable)

Passes a variable address (DLL call in-line parameter function).  See DLLCall.


AND

Boolean := Boolean AND Boolean

Combines two relationship expressions.  Returns TRUE if both expressions are true, or FALSE if not.  See Logical Operators and Logical Expressions.


AnsiString

String := AnsiString (<Value> String)

Passes value as an ANSI string (DLL call in-line parameter function).  See DLLCall.


AppActivate

AppActivate (Window: Any)

 Related Topics  [image]  Example

Activates and displays a window, using the window title or the window handle.  Use AppLocate to get the window handle.

Example

Assign(hWnd; AppLocate("Program Manager"))

If(hWnd)  // if hWnd not equal to 0

AppActivate(hWnd)

Else

Quit

EndIf

Parameters

Window: Any

A window handle or title.  Titles must match a window title exactly unless you use an asterisk as a wildcard character.  Titles are case sensitive.  Use AppLocate to get the window handle.


AppClose

AppClose (Window: Any)

 Related Topics  [image]  Example

Closes an application by title or window handle.

Parameters

Window: Any

A title or window handle.  Titles must match window titles exactly unless you use an asterisk as a wildcard character.  Titles are case sensitive.  Use AppLocate to get the window handle.


AppExecute

AppExecute (CommandLine: String)

 Related Topics  [image]  Example

Starts an application and displays it.  It also supports non-application files using Windows' associations.

The macro terminates if the application is not successfully started.  AppExecute is the equivalent of the Windows* Run command.

Examples

AppExecute ("c:\...\textfile.txt")

AppExecute ("c:\...\calc.exe")

Parameters

CommandLine: String

The path and name of an application or file.


AppExecuteExt

Numeric := AppExecuteExt (CommandLine: String; State: Enumeration)

 Related Topics  [image]  Example

Starts an application and specifies how its window is displayed.

Return Value

The application handle (unique number) if the application is successfully started, or an error value less than or equal to 32 if not.  For the list of error values, see Windows* 95 documentation.

Check error values with code similar to the following:

vError := AppExecuteExt (String; Enumeration)

Switch(vError)

CaseOF 0: ...statement block...

CaseOF 2: ...statement block...

EndSwitch

Parameters

CommandLine: String

The path and name of an application.

State: Enumeration

Specifies how an application's window is displayed.  The values are:

Hide! Hide window.  AppLocate and DDEInitiate return the window handle of a hidden window.  DDEExecute sends a command string to a hidden window.  AppActivate activates a hidden window.  Accelerator keys choose a hidden window's menu options.

Normal! Show window at normal size.

Maximize! Maximize window to full screen size and active it.

Minimize! Minimize window to an icon and active it.

MinimizeNoActivate! Minimize to an icon.  The active window remains active.

MinimizeActivateTopLevel! Minimize window and activate the next window.

CurrentState! Activate and show window in current size and position.

CurrentStateNoActivate! Display window in current state.  Active window remains active.

RecentStateNoActivate! Display window in most recent size and position.  Active window remains active.

Restore! Activates and displays window, restoring the original size.

Default! The default state specified by the application.


Application

Application (<ProductPrefix> String; <ApplicationName> String; <Default> Enumeration; <Language> String)

 Related Topics  [image]  Example

Identifies, for the compiler, an application to use in a macro.

Application is a non-executable statement that can occur anywhere in a macro, but must precede product commands to the application it identifies.

Applications used in the macro automatically start unless already active.  The user cannot terminate an application used in a macro until the macro ends.

Parameters

<ProductPrefix> String

A word identifier that begins with a letter.  Characters after the first can be letters or numbers.  ProductPrefix directs product commands to non-default applications.  It is also used in NewDefault and EndApp statements.  Use a period to attach ProductPrefix to a product command.  If WordPerfect* is the application and WP the product prefix, WP.AboutDlg is a valid command statement.  A recorded macro returns the product name as the product prefix.

<ApplicationName> String

The name of an application.  For example, "WordPerfect" for WordPerfect 7 for Windows.

<Default> Enumeration (optional)

An enumeration that identifies the default application.  If not specified, ApplicationName is not the default.  There can be only one default application.

Product commands to the default application do not require a product prefix.

Default! Specifies ApplicationName as the default.

<Language> String (optional)

The application's language code.  For example, "US" is the language code for United States English.  If not specified, the command uses the language of the current macro system.


AppLocate

Numeric := AppLocate (WindowTitle: String)

 Related Topics  [image]  Example

Returns a window handle.

AppLocate compares a name to the title bar text of all open windows.  If a match is found, the window handle of the matching window is returned.  If the search criteria matches more than one window, the window handle of the most recently opened window is returned.  If no match is found, zero is returned.

You can use an asterisk (*) as a wildcard character at any position in the AppLocate parameter.  If the parameter contains only an asterisk, AppLocate returns the window handle of the active window.

Return Value

The window handle of the window found in the search, or 0 if no window is found.

Parameters

WindowTitle: String

A window title.  This parameter must match the window title exactly unless you use an asterisk as a wildcard character.  Titles are case sensitive.


AppShow

AppShow (Window: Any; State: Enumeration)

 Related Topics  [image]  Example

Specifies an application's display state.  Identifies the application by title or window handle.

Parameters

Window: Any

A title or window handle.  Titles must match window titles exactly unless you use an asterisk as a wildcard character.  Titles are case sensitive.  Use AppLocate to get the window handle.

State: Enumeration

Display states.

Hide! Hide window.  AppLocate and DDEInitiate return the window handle of a hidden window.  DDEExecute sends a command string to a hidden window.  AppActivate activates a hidden window.  Accelerator keys choose a hidden window's menu options.

Normal! Show window at normal size.

Maximize! Maximize window to full screen size and active it.

Minimize! Minimize window to an icon and active it.

MinimizeNoActivate! Minimize to an icon.  The active window remains active.

MinimizeActivateTopLevel! Minimize window and activate the next window.

CurrentState! Activate and show window in current size and position.

CurrentStateNoActivate! Display window in current state.  Active window remains active.

RecentStateNoActivate! Display window in most recent size and position.  Active window remains active.

Restore! Activates and displays window, restoring the original size.

Default! The default state specified by the application.


asin

Numeric := asin (Value: Numeric)

Returns an angle in radians for a specified inverse (arc) sine.

Parameters

Value: Numeric

Sine.


asinh

Numeric := asinh (Value: Numeric)

Returns an angle in radians for a specified inverse (arc) hyperbolic sine.

Parameters

Value: Numeric

Hyperbolic sine.


Assert

Assert (Condition: Enumeration or Numeric)

 Related Topics  [image]  Example

Creates a Cancel, Error, or Not Found condition, or user-defined condition.  See OnCondition.

A Cancel, Error, or Not Found condition stops a macro unless preceded by OnCancel, OnError, OnNotFound, or OnCondition, which direct macro execution to a specified Label.  Assert has no effect when preceded by Cancel(Off!), Error(Off!), NotFound(Off!), or OnCondition(<Condition>; Off!).

An error value is assigned to variable ErrorNumber when one of the three conditions occurs.  The values are:

1 Cancel condition.

2 Error condition.

7 Not found condition.

You cannot assign a value to ErrorNumber.

Use code similar to the following to check all three conditions with one subroutine (see Using Subroutines).

OnError(Condition)

OnCancel(Condition)

OnNotFound(Condition)

...other statements...

Label(Condition)

Switch(ErrorNumber)

CaseOF 1: ...statement block...

CaseOF 2: ...statement block...

CaseOF 7: ...statement block...

EndSwitch

Parameters

Condition: Enumeration or Numeric

A condition to assert.

CancelCondition! Stops a macro unless preceded by OnCancel.

ErrorCondition! Stops a macro unless preceded by OnError.

NotFoundCondition! Stops a macro unless preceded by OnNotFound.

UserDefinedCondition!  Stops a macro on a user-defined condition, unless preceded by OnCondition.  For example, if you define condition 101, Assert (101) directs macro execution to the Label identified by OnCondition.

See OnCondition for a description of how to specify a user-defined condition number.


Assign

Assign (<VariableName> Variable; <Value> Any)

 Related Topics  [image]  Example

Assigns a value to a variable.

Assign is equivalent to the assignment operator (:=).  Consider the following four statements and their equivalents:

Examples

Assign(A; B)

Explanation: Assign the contents of B to A.

Assign(A; 487)

Explanation: Assign 487 to A.

Assign(A; B + 487)

Explanation: Assign the contents of B + 487 to A.

Assign(A; "John Doe")

Explanation: Assign the name John Doe to A.

A := B

Explanation: Assign the contents of B to A.

A := 487

Explanation: Assign 487 to A.

A := B + 487

Explanation: Assign the contents of B + 487 to A.

A := "John Doe"

Explanation: Assign the name John Doe to A.

Parameters

<VariableName> Variable

Contains the contents of Value.

<Value> Any

A variable, constant, character string, or expression.  The source line has a maximum length of 512 characters.


atan

Numeric := atan (Value: Numeric)

Returns an angle in radians for a specified inverse (arc) tangent.

Parameters

Value: Numeric

Tangent.


atan2

Numeric := atan2 (Value: Numeric; Value2: Numeric)

Returns an angle in radians for a specified inverse (arc) tangent that is Value / Value2.

Parameters

Value: Numeric

Numerator of a tangent.

Value2: Numeric

Denominator of a tangent.


atanh

Numeric := atanh (Value: Numeric)

Returns an angle in radians for a specified inverse (arc) hyperbolic tangent.

Parameters

Value: Numeric

Hyperbolic tangent.


Average

Numeric := Average ({Value: Numeric})

Returns the average of a list of values.

Example

vAvg := Average (2; 4; 6; 8)

Result: vAvg = 5.0

Parameters

Value: Numeric

Use a semicolon to separate values.


Beep

Beep()

  Example

Causes a computer speaker or installed sound board to beep.

Beep is commonly used with warning messages, or to signal when a macro pauses or finishes a task.


BIFFilePath

String := BIFFilePath (BIFFileType: Enumeration)

 Related Topics

Retrieves the path and filename of a 16-bit Binary Initialization File (BIF).

This command is provided for backward compatibility only.  Settings are now located in the Windows* Registry (see Registry commands).

Return Value

The BIF path and filename.

Parameter

BIFFileType: Enumeration (optional)

The BIF type that is returned in BIFFilePath.  A user can have only two active BIF files. Default: Private!

Private! A BIF file containing settings that apply to a single user.

Public! A BIF file containing settings that are shared by many, possibly concurrent, users.


BIFInfo

Enumeration := BIFInfo (Status: Variable; Group: String; Section: String; Item: String; DateTime: Variable; ItemFlags: Variable; ItemLength: Variable; ItemType: Variable; UseCount: Variable; ItemInfoType: Enumeration; BIFFile: String)

 Related Topics

Retrieves information from a Binary Initialization File (BIF).

This command is provided for backward compatibility only.  Settings are now located in the Windows* Registry (see Registry commands).

Return Value

The status of a BIF call is returned in a variable.  As a function, you can use BIFInfo in an If statement. The values are:

Success!

BufferTooSmall! Length of Group, Section, or Item exceeds buffer size.

ItemNotFound!

UnknownError!

Parameters

Status: Variable (optional)

The status of a BIF call is returned in this variable (see Return Value above). The semicolon is still required if not used.

Group: String (optional)

The name of a Group.  If this parameter is not used, the number of Group names is returned in the UseCount parameter.

Section: String (optional)

The name of a Section.  If this parameter is not used, the number of Section names in the specified Group is returned in the UseCount parameter.

Item: String (optional)

The name of an Item.  If this parameter is not used, the number of Item names in the specified Group and Section is returned in the UseCount parameter.

Note

No data is returned unless you specified a Variable (following five parameters).

DateTime: Variable (optional)

The date and time the item was created is returned in this variable.

ItemFlags: Variable (optional)

The flags associated with an item are returned in this variable.  If Group, Section, and Item are not used, 0 is returned.

ItemLength: Variable (optional)

The length of an item entry is returned in this variable.  If Group, Section, and Item are not used, 0 is returned.

ItemType: Variable (optional)

The item type is returned in this variable.  If Group, Section, and Item are not used, 0 is returned.  This is the value sent to the ItemType parameter of BIFRead and BIFWrite.

UseCount: Variable (optional)

If Group, Section, or Item is not used, the number of Groups, Sections, or Items in a BIF is returned in this variable (see Group, Section, and Item parameters).  Otherwise, 0 is returned.

ItemInfoType: Enumeration (optional)

The standard BIF types to examine. Default: Private!

Both! Look in both standard BIFs.  Only valid when counting Groups, Sections, or Items.

Private! Look in Private BIF only.

Public! Look in Public BIF only.

BIFFile: String (optional)

The name of a non-standard BIF.  If not specified, the command uses the implicit BIF file.


BIFRead

Enumeration := BIFRead (Status: Variable ;Group: String; Section: String; Item: String; Value: Variable; ExpectedItemType: Enumeration; NameSeparator: String; NameListType: Enumeration; BIFFile: String)

 Related Topics

Reads a Binary Initialization File (BIF), and returns Group, Section, or Item names, or item value.

This command is provided for backward compatibility only.  Settings are now located in the Windows* Registry (see Registry commands).

Descriptions

Group, the highest BIF level.

Section, the next BIF level after Group, is associated with Group subdivisions.

Item, the lowest BIF level, is associated with a Section entry.

Items contain values.

Group, Section, and Item names are subject to change.

Return Value

The status of a BIF call is returned in a variable.  As a function, you can use BIFRead in an If statement.  The values are:

Success!

TypeMismatch! ItemType does not match returned item type (see ItemType parameter).

BufferTooSmall! Length of Group, Section, or Item exceeds buffer size.

ItemNotFound!

UnknownError!

Parameters

Status: Variable (optional)

The status of a BIF call is returned in this variable (see Return Value above). The semicolon is still required if not used.

Group: String (optional)

Contains a Group name.  If Group is not used, the BIF Group names are returned in a variable (see Value parameter).

Section: String (optional)

Contains a Section name.  If Group is used and Section is not, the BIF Section names for the specified Group are returned in a variable (see Value parameter).

Item: String (optional)

Contains an Item name.  If Group and Section are used and Item is not, the BIF Item names for the specified Group and Section are returned in a variable (see Value parameter).

Value: Variable (optional)

The Group, Section, or Item names are returned in this variable, depending on which one is not used.  If Group, Section, and Item are used, the Item value is returned.  If not specified, no data is returned.

ExpectedItemType: Enumeration

The expected item type to return in a variable (see Value parameter).  ItemType is not used if Group, Section, or Item is not used.  If not specified, the command uses the BIF ItemType.

Any!

Boolean!

SignedByte!

UnsignedByte!

SignedWord!

UnsignedWord!

SignedDWord!

UnsignedDWord!

Float4!

Float8!

Float32Bit!

Float64Bit!

AnsiString!

WPWordString!

BagOfBits!

NameSeparator: String (optional)

A delimiter string that separates Group, Section, or Item names.  The delimiter is not limited to a single character.  If missing, the default is a semicolon.  NameSeparator is not used when returning an item value (Group, Section, and Item are used).

NameListType: Enumeration (optional)

A standard BIF to read.  Standard BIFs are associated with WordPerfect* products (see BIFFile parameter).  Default: Both!. The values are:

Both! Look in both standard BIFs.

Private! Look in Private BIF only.

Public! Look in Public BIF only.  You cannot specify Public! to read an Item value.  Public! is ignored unless you are reading a list (Group, Section, or Item names).

BIFFile: String (optional)

The name of a non-standard BIF (a user-defined or non-WordPerfect product BIF).  If both parameters are used, BIFFile overrides NameListType.  If neither parameter is used, the default is NameListType.


BIFWrite

Enumeration := BIFWrite (Status: Variable; Group: String; Section: String; Item: String; Value: Any; ItemType: Enumeration; ItemFlags: Enumeration; BIFFile: String)

 Related Topics

Writes data to a Binary Initialization File (BIF), or deletes a group, section, or item from a BIF.

This command is provided for backward compatibility only.  Settings are now located in the Windows* Registry (see Registry commands).

Notes

See BIFRead for a description of BIF Groups, Sections, Items, and Values.To write data to a BIF, you must use the Group, Section, Item, and Value parameters.  If you do not specify a value for each parameter, you will delete a level or item from the BIF.  See parameter descriptions below.

BIFWrite calls to the public and private BIF fail if a PerfectOffice 3.0 application is running.

Return Value

The status of a BIF call is returned in this variable.  As a function, you can use BIFRead in an If statement.  The values are:

Success!

UnknownError! Unknown Group, Section, or Item type.

TypeUnknown!

ItemNotFound!

ItemNotFound!

StillInPublic!

Parameters

Status: Variable (optional)

The status of a BIF call is returned in this variable (see Return Value above). The semicolon is still required if not used.

Group: String (optional)

A Group name.  To delete a Group, specify the Group name and do not use the Section parameter.  To delete all Groups, Sections, and Items, do not use the Group parameter.

Section: String (optional)

A Section name.  The Group name must be used.  To delete a Section, specify the Section name and do not use the Item parameter.  If not used, Group is deleted.

Item: String (optional)

An Item name.  The Group and Section names must be used.  To delete an Item, specify the Item name and do not use the Value parameter.  If not used, Section is deleted.

Value: Any (optional)

The Item value to write to the BIF.  If not used, Item is deleted.

Do not write to a standard BIF while the associated WordPerfect* application is running.  Standard BIFs remain open while PerfectFit* is running.

ItemType: Enumeration (optional)

The Value data type to write to the BIF.

Any!

Boolean!

SignedByte!

UnsignedByte!

SignedWord!

UnsignedWord!

SignedDWord!

UnsignedDWord!

Float4!

Float8!

Float32Bit!

Float64Bit!

AnsiString!

WPWordString!

BagOfBits!

If you write a new value to a BIF item, you must specifiy the same type as the previous item.  If not specified, ItemType is determined by the current data value.

If ItemType does not match the current value type, it is converted if possible.  If not converted properly, you may not be able to read the value back later (see BIFRead).

ItemFlags: Enumeration (optional)

Flags (attributes) affect only the public BIF.  Value 4 is processed when an item is read from a BIF.  All other values are processed when Shared Code starts.  Default: None!

None! No flags.

DeletePrivate! Removes an item in a private BIF that has the same name as an item in the public BIF.

OverridePrivate! The public BIF item has precedence over an item with the same name in a private BIF.  Normally, the opposite is true.

DistributeToPrivate! An item is copied to the private BIF when opened.

OverridePrivate! The public BIF item has precedence over an item with the same name in a private BIF.  Normally, the opposite is true.

BIFFile: String (optional)

Contains the name of a non-standard BIF to write to.  If the BIF does not exist, it is created with specified Group, Section, and Item names, and Item value.  If missing, the command uses the private BIF (see BIFRead, NameListType parameter).


BinaryPack

Raw Binary Data := BinaryPack (Value: Any; TotalSize: Enumeration or Numeric; {Offset: Enumeration or Numeric; Type: Enumeration; Size: Enumeration or Numeric;})

Packs data into a raw binary data form.

Return Value

Raw binary data returned from BinaryPack.

Parameters

Value: Any

Value to be packed.

TotalSize: Enumeration or Numeric (optional)

The total size of the raw binary data value to produce.  This parameter may be specified as a numeric value, or as the enumeration value Auto!

If missing or Auto!, the raw binary data will be the size of all its parts combined.

Note

The next 3 parameters form an optional repeating group.  Currently, only 1 group is permitted.  If 1 parameter is used, all must be used.  Parameters specify the attributes of the value to be packed into the raw binary data value.  Multiple groups may be specified, each describing one value to be packed.

Offset: Enumeration or Numeric (optional)

Beginning offset (starting at 0) within the raw binary data value to pack Value into.  This is the offset of the first byte of the data value.  This parameter may be specified as a numeric value, or as the enumeration Auto!.  If missing, or specified as Auto!, the next available offset (starting at 0) is used.  Any gaps in the final raw binary data value may contain undefined data.

Type: Enumeration (optional)

Type that Value is packed into.  The default size for the Size parameter is shown in [].  If missing, Auto! is used.

Auto! Actual data type of Value is used.

Detect! Actual data type of Value is used.

Byte! Pack Value into bytes (1..n bytes [1]).

Word! Pack Value into a word (2 bytes [2]).

DWord! Pack Value into a double word (4 bytes [4]).

Real! Pack Value into a 'C' double (8 bytes [8]).

Integer! Pack Value into a 'C' long (1, 2, 4 bytes [4]).

Boolean! Pack Value into a Windows BOOL (1, 2, 4 bytes [4]).

WPString! Pack Value into a WordPerfect* string (2 byte characters [length+1]).

AnsiString! Pack Value into an ANSI string (1 byte characters [length+1]).

HexString! Pack Value into direct binary data from a string of hex characters (1 byte characters [length]).

Size: Enumeration or Numeric (optional)

Size in bytes of the raw binary data of Value.  This parameter may be specified as a numeric value, or as the enumeration value Auto!.  If missing, or specified as Auto!, the default size of Type is used (shown above in [ ]).

Note

If the Type parameter is Word!, DWord!, or Real!, the Size parameter must be Auto!, or it must agree with the default size for that type (shown in [] above).

If Type is Integer! or Boolean!, Size must be Auto!, or it must be 1, 2, or 4.

If Type is WPString! or AnsiString!, Auto! uses the full length of the string plus 1.  If Size is larger than the length, the excess data is zero filled.  If Size is smaller, only Size (number of) characters is used.

If Type is HexString!, each two-character pair is made into a bye.  If size is shorter , only Size (number of) bytes are produced.  If Size is longer, the excess data is zero filled.  If Type is Auto!, the full length of the string is used.


BinaryUnPack

Any := BinaryUnPack (Value: Raw Binary Data; {Offset: Enumeration or Numeric; Type: Enumeration; Size: Enumeration or Numeric;})UnPack data from a raw binary data form.

Return Value

Unpacked data returned by BinaryUnPack.

Parameters

Value: Raw Binary Data

Raw binary value to unpack.

Note

The next 3 parameters form a repeating group.   At least one group must be specified (only 1 group is permitted currently).  If 1 parameter is used, all must be used.  Parameters specify the attributes of the values to be unpacked from the raw binary data value.  Multiple groups may be specified, each describing one value to be unpacked.

Offset: Enumeration or Numeric

The beginning offset (starting at 0) of the value within the raw binary data to unpack.  This is the offset of the first byte of the data value.  If specified as Auto!, the next available offset (starting at 0) is used.

Type: Enumeration

Type of value to unpack from the raw binary data.  The default size for Size parameter is shown in [].

Byte! Unpack the value from a byte (1 byte [1]).

Word! Unpack the value from a word (2 bytes [2]).

DWord! Unpack the value from a double word (4 bytes [4]).

Real! Unpack the value from a 'C' double (8 bytes [8]).

Integer! Unpack the value from a 'C' long (4 bytes [1, 2, 4]).

Boolean! Unpack the value from a Windows BOOL (1, 2, 4 bytes [4]).

WPString! Unpack the value from a WordPerfect* string (2 byte characters [to first NULL character]).

AnsiString! Unpack the value from an ANSI string (1 byte characters [to first NULL character]).

HexString! Unpack the value forming a string of hex characters (1 byte [to length specified]).

Size: Enumeration or Numeric

Size in bytes that Value is unpacked from.  If specified as Auto!, the default size of the Type is used (shown above in [ ]).

Note

If the Type parameter is Word!, DWord!, or Real!, the Size parameter must be Auto!, or it must agree with the default size for that type (shown in [] above).

If Type is Intger! or Boolean!, Size must be Auto!, or it must be 1, 2, or 4.

If Type is WPString! or AnsiString!, Auto! uses the full length of the string plus 1.  If Size is larger than the length, the excess data is zero filled.  If Size is smaller, only Size (number of) characters is used.

If Type is HexString!, each two-character pair is made into a bye.  If size is shorter , only Size (number of) bytes are produced.  If Size is longer, the excess data is zero filled.  If Type is Auto!, the full length of the string is used.


Break

  Example

Ends a loop, and directs macro execution to the first statement after the ending loop statement (see Using Loop Statements).

In a Switch statement, Break directs macro execution to the first statement after EndSwitch.  Break bypasses the normal test expression of a loop or conditional statement.  Statements after Break are ignored.


Call

Call <Label> Label ({<Parameter>Any})

Calls macro code associated with a Label, Procedure, or Function (see Using Subroutines), and can pass one or more values to a Procedure or Function.

A Return statement in a Label, Procedure, or Function directs macro execution to the statement that follows the Label's caller.

Parameters

<Label> Label

A Label, Procedure, or Function name that begins with a letter and consists of one or more letters or numbers.  The format for calling Label is:

Call(LabelSub)

...other statements...

Label(LabelSub)

...statement block...

Return

The syntax for calling and passing a value to a Procedure or Function is:

Call <Label> Label ({<Parameter> Any})

The formats for callng Procedures and Functions are:

Call ProcSub(<Parameter>; <Parameter>)

...other statements...

Procedure ProcSub(<Parameter>; <Parameter>)

...statementblock...

EndProc

Call FuncSub(<Parameter>)

...other statements...

Function FuncSub(<Parameter>)

...statementblock...

Return(<Value>)

EndFunc


Call

Call (<Label> Label)

 Related Topics  [image]  Example

Calls macro code associated with a Label, Procedure, or Function (see Using Subroutines), and can pass one or more values to a Procedure or Function.

A Return statement in a Label, Procedure, or Function directs macro execution to the statement that follows the Label's caller.

Parameters

<Label> Label

A Label, Procedure, or Function name that begins with a letter and consists of one or more letters or numbers.  The format for calling Label is:

Call(LabelSub)

...other statements...

Label(LabelSub)

...statement block...

Return

The syntax for calling and passing a value to a Procedure or Function is:

Call <Label> Label ({<Parameter> Any})

The formats for calling Procedures and Functions are:

Call ProcSub(<Parameter>; <Parameter>)

...other statements...

Procedure ProcSub(<Parameter>; <Parameter>)

...statementblock...

EndProc

Call FuncSub(<Parameter>)

...other statements...

Function FuncSub(<Parameter>)

...statementblock...

Return(<Value>)

EndFunc


CallbackResume

CallbackResume()

  Example

Resumes macro execution paused by CallbackWait.  The macro continues to the next command after CallbackWait.

See example under CallbackWait.


CallbackWait

CallbackWait()

  Example

Replaces the loop statement after DialogShow, DialogDisplay, and CoachMessageBoxEx, pausing the macro to allow the callback to be executed.  Use this command with CallbackResume.

CallbackWait and CallbackResume are easier to use and more efficient than loops.

Example with CallbackWait and CallbackResume

DialogShow ("Dialog1"; "WordPerfect"; Msg)

CallbackWait

Quit

Label (Msg)

If (Msg[5] = 274)

DialogDestroy ("Dialog1")

CallbackResume

Return

Endif

If (Msg[3] = "OKBttn")

DialogDestroy ("Dialog1")

CallbackResume

Return

Endif

Return

Example with While loop

DialogShow ("Dialog1"; "WordPerfect"; Msg)

Loop = 1

While (Loop)

EndWhile

Quit

Label (Msg)

If (Msg[5] = 274)

DialogDestroy ("Dialog1")

Loop = 0

Return

Endif

If (Msg[3] = "OKBttn")

DialogDestroy ("Dialog1")

Loop = 0

Return

Endif

Return


Cancel

Enumeration := Cancel (State: Enumeration)

 Related Topics  [image]  Example

Determines how a macro responds to a Cancel condition.

Create a Cancel condition by pressing Esc, or with Assert(CancelCondition!).

Return Value

Off! Previous Cancel state was Off!

On! Previous Cancel state was On!

Parameters

State: Enumeration (optional)

Specifies the Cancel state.  Default: Cancel(On!).  If missing, the current state is returned without changing it.

Off! Ignores a Cancel condition.

On! Stops a macro unless preceded by OnCancel, which directs macro execution to a specified Label.


Case

Case (<Test> Any; {<Case> Any; <Label> Label}; <DefaultLabel> Label)

 Related Topics  [image]  Example

A conditional statement that tests for matching expressions.  If a match is found, a Label is executed.  See Using Conditional Statements.

Case compares <Test> to a set of <Cases> (values).  If the first comparison is true (if <Test> and <Case> match), the Label following <Case> is executed.  If the comparison is false, the next <Case> is evaluated and so forth.  If no comparison is true, DefaultLabel is executed.

Parameters

Test: Any

The control expression.  Variables are assigned values by commands such as GetString, GetNumber, or Menu.

Case: 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.

Label: Label

The Label to execute if <Case> matches <Test>.

DefaultLabel: Label (optional)

The Label to execute if no <Case> matches <Test>.  If not specified, the statement immediately following Case is executed.


Case Call

Case Call (<Test> Any; {<Case> Any; <Label> Label}; <DefaultLabel> Label)

 Related Topics  [image]  Example

A conditional statement that tests for matching expressions.  If a match is found, a Label is called.  See Using Conditional Statements.

Case Call compares <Test> to a set of <Cases> (values).  If the first comparison is true (if <Test> and <Case> match), the Label following <Case> is executed.  If the comparison is false, the next <Case> is evaluated and so forth.  If no comparison is true, <DefaultLabel> is executed.

Case is different from Case Call, in that a Return statement after Label directs macro execution to the statement that follows Case Call.

Parameters

Test: Any

The control expression.  Variables are assigned values by commands such as GetString, GetNumber, or Menu.

Case: 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.

Label: Label

The Label to execute if <Case> matches <Test>.

DefaultLabel: Label (optional)

The Label to execute if no <Case> matches <Test>.  If not specified, the statement immediately following Case Call is executed.


CaseOf:

CaseOf: ({<Selector> Any})

Identifies the code to execute when a CaseOf <Selector> matches the control expression in a Switch statement.  See Switch.


Ceiling

Numeric := Ceiling (Value: Numeric)

Returns the smallest integer that is greater than or equal to a specified value (the ceiling of a number).

Example

vInt := Ceiling (15.4)

Result: vInt = 16

Parameters

Value: Numeric


Chain

Chain (MacroFilename: String; {Parameter: Any})

 Related Topics  [image]  Example

Calls (starts) another macro when the parent macro ends.

PerfectScript automatically compiles uncompiled Chain macros.  Macro execution stops if the macro will not compile.  A Chain macro does not return to its caller (see Run).

Although Chain can occur anywhere in a macro, it is the last statement to execute.  You can cancel Chain (macro is not executed) with a Quit statement.  For example,

Chain(EnvPaths + "Test4.wcm")

...other statements...

Switch(Test)

CaseOF 1: Chain(EnvPaths + "Test1.wcm")

CaseOF 2: Chain(EnvPaths + "Test2.wcm")

CaseOF 3: Chain(EnvPaths + "Test3.wcm")

CaseOF 4: Call(DoSomethingElse)

Default: Quit

EndSwitch

Explanation: If <Test> equals 1, 2, or 3, the corresponding macro plays when the parent macro ends.  If <Test> equals 4, the DoSomethingElse subroutine is called and Test4.wcm plays when the parent macro ends.  If <Test> does not equal 1, 2, 3, or 4, the macro quits and a Chain statement does not execute.

Parameters

MacroFilename: String

The path and name of a compiled macro.

Parameter: Any (optional)

Enclose multiple parameters in braces ({}), separated by a semicolon.  For example: Chain ("macro"; {"a"; "b"; "c"}).  Parameter values are passed to a special array variable named MacroArgs.

If missing, MacroArgs[] is not defined in the new macro.


CharLen

Numeric := CharLen (String: String)

 Related Topics  [image]  Example

Returns the number of characters in a string, including codes.

The string can be a variable, constant, character string, or result of an expression.  See StrLen for examples.

Return Value

The number of characters, including codes, in a string.

Parameters

String: String

A variable, constant, character string, or result of an expression.


CharPos

Numeric := CharPos (String: String; SubString: String; Beginning: Numeric)

 Related Topics  [image]  Example

Returns the beginning character position of a substring in a string.

Return Value

The beginning character position of a substring, or zero if a substring is not found.

Examples

vPos := CharPos("WordPerfect"; "Perfect")

Result: vPos = 5

vPos := CharPos("WordPerfect"; "Scott")

Result: vPos = 0

vPos := CharPos("Corel WordPerfect"; "or"; 7)

Result: vPos = 8

Explanation: Search begins at character position 7, bypassing first occurrence of substring.

Parameters

String: String

A character string to evaluate.

Substring: String

A substring to locate in String.

Beginning: Numeric (optional)

Default: 1.  Begin looking for Substring at this character position (see example above).


CloseFile

Boolean := CloseFile (FileID: Numeric)

 Related Topics  [image]  Example

Closes one file or all files.

Note

Close file(s) when no longer needed, or system resources will be lost.  Files are closed automatically when macro ends.  See OpenFile.

Return Value

True if successful, False if not.

Parameters

FileID: Numeric (optional)

If not specified, all open files are closed.


CoachAnimate

CoachAnimate (Type: Enumeration; Specification: String)

Specifies mouse actions or keystrokes to execute without user intervention.  This allows a Coach macro to demonstrate how to perform a function.  You cannot use CoachAnimate when a filter is enabled.

Parameters

Type: Enumeration

Specifies whether CoachAnimate animates the mouse or the keyboard.

Mouse! Mouse movements are animated.

Keyboard! Keystrokes are animated.

Specification: String)

Wpstring: specifies actions to animate.  It contains a keystring or a Mouse String, depending on the value of Type.  See KeyString and Mouse String.


CoachFilterAdd

CoachFilterAdd (Name: String; Label: Label; LabelCondition: Enumeration; Type: Enumeration; Filter: String; AppName: String; Command: Command Name; {Parameter: Numeric; Compare: Enumeration; Value: Any})

 Related Topics

Defines a filter.

CoachFilterEnable enables defined filters, which monitor macro commands.

Compound Filters

To monitor more than one type of event, create a compound filter by using CoachFilterAdd several times, each time with the same filter name but with different filter specifications.  A compound filter can monitor several different commands.

For example, to create a compound filter that waits for either (1) the user to save the current document, r (2) the user to open the SaveAs dialog, use CoachFilterAdd twice with the same name each time.

You can enable only one command filter at a time (See CoachFilterEnable).

Filter Callback Procedure

Each filter can call one associated callback procedure, which the coach macro uses to determine if the command should be allowed or disallowed.  A callback procedure begins with a label name and ends with Return.

After an enabled filter compares the user's actions with those defined in the filter, it determines whether to execute the filter callback procedure.  LabelCondition in CoachFilterAdd determines when to call the callback:  (1) the user's actions match the filter definition, (2) the user's actions do not match the filter definition, and (3) all cases.

When the macro executes a callback, return and array variables are created by the macro system and are accessible to the callback.

Filter Array Variable

Contains information about the user's actions while a filter is enabled.  The callback can access the array values for information about the event.  The name of the array is formed from the label name.  For example, if the label is Label1@, the array elements are Label1[1], Label1[2] and so on.

The information in the array depends on the type of callback receiving the array.

Note

For more information, see Callback Data Description.

Filter Return Variable

Specifies whether to ignore an event or send it to the application.  Return variables have the same name as the callback label.

When a macro executes a callback's Return, the macro system checks the return variable, then passes the event to the application or throws it away.

Value (Action)

Default: 0

0 (Pass the event to the application.)

1 (Throw away the event.)

Parameters

Name: String

The name of the filter to define.  If a filter with this name already exists, the new filter definition is appended to the existing definition to create a compound filter (see Compound Filters above).

Label: Label

The macro label that is the name of a callback.  Macro execution moves to this label as determined by LabelCondition (see Filter Callback Procedure above).  For compound filters, the Label name must be the same for all entries in the filter.

LabelCondition: Enumeration

Specifies when to call the callback procedure marked by the Label label.

All! All user actions call the callback.

Match! All user actions that match the filter call the callback.

Nonmatch! Only user actions that do not match the filter call the callback.

Type: Enumeration

Specifies the type of filter.  Must be a token.

Filter: String (optional)

This parameter is ignored.

AppName: String

Non-translatable application name, such as "WordPerfect".

Command: Command Name

Name of a product command to filter.

RepeatingGroup (optional)

Filters parameter information for the product command specified in Command.

If any parameter in a repeating group is assigned a value, all parameters of the repeating group must be assigned a value.  You can specify more than one repeating group in the same CoachFilterAdd command.

Parameter: Numeric (First parameter of repeating group)

The parameter number to filter.  The Value command evaluates a parameter to a number.  For example, the Filename parameter of FileOpenDlg is "Value(FileOpenDlg.Filename)".

Compare: Enumeration (Second parameter of repeating group)

Specifies how to compare Parameter and Value.

Equal! Parameter is equal to Value.

NotEqual! Parameter is not equal to Value.

Less! Parameter is less than Value.

NotLess! Parameter is not less than Value.

Greater! Parameter is greater than Value.

NotGreater! Parameter is less than or equal to Value.

Exist! Parameter exists but can be any value.

NotExist! Parameter does not exist.

DontCare! Parameter may or may not exist.  If it exists, it can be any value.

Value: Any (Third parameter of repeating group)

Contains any value type to compare with Parameter.


CoachFilterDestroy

CoachFilterDestroy (Name: String)

 Related Topics

Removes the filter definition from memory.

Only one command filter can be enabled at a time.

When a filter is enabled, it compares a command to actions defined in the filter,  then calls a callback procedure or passes the event unchanged.

A filter must be defined by CoachFilterAdd before it can be enabled.  An enabled filter remains enabled until it is disabled by CoachFilterDisable or destroyed by CoachFilterDestroy.

Note

A filter should be destroyed after it is no longer needed. Destroying a filter removes it from memory.  If many filters are created but not destroyed, performance may be affected.  Filters are automatically destroyed when macro execution terminates.

Parameters

Name: String

The name of a filter to destroy.


CoachFilterDisable

CoachFilterDisable (Command: String; Interface: String) [image] Related Topics

Disables an active filter.  A filter definition remains in memory until CoachFilterDestroy destroys it, or until the macro ends.

Parameters

Command: String (optional)

The name of a command filter to disable.

Interface: String (optional)

The name of an interface filter to disable.


CoachFilterEnable

CoachFilterEnable (Command: String; Interface: String)

 Related Topics

Enables (activates) specified filters.

Parameters

Command: String (optional)

The name of a filter to enable.  Only one filter can be enabled at a time.

Interface: String (optional)

To filter multiple events, use a compound filter (see CoachFilterAdd).


CoachGetRegionInfo

CoachGetRegionInfo (Region: String; ExistVar: Variable; HwndVar: Variable; LeftVar: Variable; TopVar: Variable; RightVar: Variable; BottomVar: Variable)

Returns information about a named region, such as a window handle, rectangle, existence of the window, and control ID.

Note

If the optional parameters are missing, the specific item is not returned.

Parameters

Region: String

Name of the region to test.  For example:

"WordPerfect.Bookmark.GoToBttn"

ExistVar: Variable (optional)

Returns 0 if the region does not exist, and 1 if it does exist.

HwndVar: Variable (optional)

Windows handle value of a specified region.

LeftVar: Variable (optional)

Screen coordinates for the left edge of a specified region.

TopVar: Variable (optional)

Screen coordinates for the top edge of a specified region.

RightVar: Variable (optional)

Screen coordinates for the right edge of a specified region.

BottomVar: Variable (optional)

Screen coordinates for the bottom edge of a specified region.


CoachInputControl

Enumeration := CoachInputControl (State: Enumeration)

Sets state of user input.

Return Value

The previous state is returned in this variable.

Off!

On!

Parameters

State: Enumeration

Off! Disables all mouse clicks and keystrokes.  Use with caution.  Turning input off without turning it on effectively hangs the system.

On!


CoachMessageBoxClose

CoachMessageBoxClose (MessageBoxName: String)

 Related Topics

Closes a message box.  Required only for Modeless! or Modal! message boxes (see Modality in CoachMessageBoxEx).

Parameters

MessageBoxName: String

Name of a message box to close.  This should be the same name as in MessageBoxName of CoachMessageBox.


CoachMessageBoxEx

CoachMessageBoxEx (MessageBoxName: String; PosLeft: Numeric; PosTop: Numeric; Modality: Enumeration; Label: Label; ResultVariable: Variable; Style: Enumeration; Title: String; Text: String; Font: String; FontSize: Numeric; StdResourceDLL: Numeric; AddResourceDLL: Numeric; SmIconID: Numeric; LogoBitmapID: Numeric; LogoPosition: Enumeration; BitmapID: Numeric; BitmapPosition: Enumeration; ControlName: String; ControlType: Enumeration; ControlText: String)

Displays information and gets input.

To get user input you place buttons on the message box.  A Coach message box can include a title, informational text, up to two bitmap images, check boxes, and branch, radio, push, and Toolbar* buttons.

You can display more than one message box at a time, and drag them to different positions on the screen.

Message Box Callback Procedure

A callback procedure enables a macro to respond immediately and in specific ways to events such as selecting a radio button or check box, without waiting until the dialog box is dismissed.  For example, if the user clicks Close, the callback procedure can call CoachMessageBoxClose to dismiss the message box.  Without a callback procedure user input is acted upon only after the dialog box is dismissed and the macro resumes execution.

Note

For more information, see Callback Data Description.

Parameters

MessageBoxName: String

Name of the message box (ANSI string).

PosLeft: Numeric

Percent of the screen to the left of the message box.

PosTop: Numeric

Percent of the screen above the message box.

Modality: Enumeration

Simple! Parent window is disabled (no callback).  ResultVariable is required.

Modal! Parent window is disabled.  Label parameter is required.

Modeless! Never takes activation.  Label parameter is required.

Label: Label (optional)

Callback label.  Required by Modal and Modeless message boxes.  Ignored by Simple message boxes.

ResultVariable: Variable (optional)

Contains the name of the PushButton, BranchButton, or ToolButton pressed to dismiss a Simple message box.  ResultVariable is ignored by Modal and Modeless dialogs.

Style: Enumeration (optional)

Default: CoachColor!

CoachColor!

MessageColor! Uses Windows* 95 Message Box colors.  Background is not sunken.

ToolTipColor! Uses Windows 95 ToolTip colors.  Background is sunken.

Title: String (optional)

Title on the message box.

Text: String (optional)

Text displayed in the message box.  Formatting codes that can be used in the text string:

\n New line

\b Toggle bold

\u Toggle underline

\i Toggle italics

\\ Insert a backslash

Font: String (optional)

Name of the font used in the message box and on the controls.  If none is specified, uses Windows 95 Message Box font and font Size information.

FontSize: Numeric (optional)

Point size for message box text (ignored if Font not used).

StdResourceDLL: Numeric (optional)

Window handle of the Standard Coach Resource DLL.

AddResourceDLL: Numeric (optional)

Window handle of an additional resource DLL.  If an Icon or Bitmap ID is not in the standard library, the message box tries to load it from this DLL.

SmIconID: Numeric (optional)

Resource ID for the small icon displayed in the upper left corner of the title bar.

LogoBitmapID: Numeric (optional)

Bitmap resource ID (see LogoPosition).  The color of the first pixel (0,0) is used as a transparency color, which is replaced by the background color of the message box wherever it occurs in the bitmap.  To turn off transparency, set the first row of pixels to a color that is not used in the bitmap.

LogoPosition: Enumeration (optional)

Default: Top!

Left! The logo bitmap is placed at the left edge of the messagebox, aligned at the top of the window.  All other text and controls are placed to the right of the logo.

Top! The logo bitmap is placed at the top edge of the messagebox, aligned at the left edge of the window.  All other text and controls are placed below the logo.

BitmapID: Numeric (optional)

Bitmap resource ID (see BitmapPosition).  The color of the first pixel (0,0) is used as a transparency color, which is replaced by the background color of the message box wherever it occurs in the bitmap.  To turn off transparency, set the first row of pixels to a color that is not used in the bitmap.

BitmapPosition: Enumeration (optional)

Default: TopCenter!

Left! Bitmap is placed to the left of text and controls, aligned with the top edge of the text.

Top! Bitmap is placed above the text and controls, aligned with the left edge of the text.

Right! Bitmap is placed to the right of the text and controls, aligned with the top edge of the text.

Bottom! Bitmap is place at the bottom of the window above Push and Toolbar Buttons, aligned with the left edge of the text.

LeftCenter! Same as Left!, with Bitmap centered vertically between the top and bottom of text and controls.

TopCenter! Same as Top!, with Bitmap centered between the left and right edge of text and controls.

RightCenter! Same as Right!, with Bitmap centered vertically between the top and bottom of text and controls.

BottomCenter! Same as Bottom!, with Bitmap centered between the left and right edge of text and controls.

Note

The next 3 parameters form an optional repeating group.  If 1 parameter is used, all must be used.

ControlName: String (optional)

User-defined control name.  This name is sent to a callback procedure, or stored in ResultVariable (Simple message box), when the control is clicked.

ControlType: Enumeration (optional)

Controls are grouped in the message box in the following order: BranchButtons, RadioButtons. CheckBoxes.  Available controls:

RadioButton!

CheckBox!

PushButton! Right justified at the bottom of the window.

BranchButton! Descriptive text is placed to the right of a small push button.

ToolButton! Right justified at the bottom of the window.  Descriptive text is replaced by a bitmap and by QuickTip text (text displays when the mouse cursor moves over the button).  ToolButton bitmaps in the resource DLL must have Gray as their background [RGB(192,192,192)].

ControlText: String (optional)

Text placed on Push Buttons, or to the right of Branch Buttons, Radio Buttons, and Check Boxes.

A Tool Button string should contain the Bitmap ID, optionally followed by a colon and QuickTip text (see ControlType).  If the string is empty or if the Bitmap ID is not found in a resource DLL, a spacer (blank space the size of a button) is placed on the ToolBar.


CoachPrompt

CoachPrompt (PromptName: String; Message: String; Font: String; FontSize: Numeric; Library: Numeric; IdBitmap: Numeric; Location: Enumeration; Left: Numeric; Top: Numeric; Region: String)

 Related Topics

Displays a prompt.

The prompt can display a message and a bitmap image that points to an item, such as a prompt that points to the File menu with the text "Click the File menu item."

The prompt location is set relative to a region (see Location and Region below), or set to a fixed position in the document window.

When you set a location relative to a region, you can have a prompt display to the right, left, upper right, upper left, lower right, or lower left of the region.  The system adjusts the size of the prompt box to fit in the display area.  If the prompt is too large, the system checks for a suitable location by rotating the prompt clockwise.  For example, if the prompt is to display to the right of a region, but there isn't room, the system checks to the lower right.  If it will not fit there, the system checks the lower left, and so on.

CoachPrompt points to items with bitmap images.  The bitmap image is displayed between the prompt box and the item.

IdBitmap specifies the bitmap image ID.  For example, if the prompt is displayed at the upper left, and the bitmap is a pointing hand, the fingers point down and to the right.

Bitmaps for all 6 prompt locations must be defined in order, starting with the upper left bitmap and proceeding clockwise.  The transparency bitmap must immediately follow each bitmap.  IdBitmap should always contain the first bitmap ID (upper left).

Parameters

PromptName: String

A unique name for the prompt.

Message: String (optional)

Message to display in the prompt.  Formatting codes are optional:

Character (result)

\nInsert (Hard Return)

\bToggle (Bold)

\uToggle (Underline)

\iToggle (Italic)

Font: String (optional)

Name of the Windows* font for prompt text.  If no font is specified, the default Windows 95 ToolTip font is used.

FontSize: Numeric (optional)

Point size of the prompt text.  If no font is specified, the default Windows 95 ToolTip font is used.

Library: Numeric (optional)

The Windows handle of the DLL that contains the bitmap to display outside the prompt.  DLLLOAD retrieves the handle.  DLLFree removes the DLL from memory.

IdBitmap: Numeric (optional)

The identifier of the first bitmap image defined for CoachPrompt.

In the bitmap DLL library each bitmap specified by IdBitmap must be immediately followed by a transparency bitmap.  A transparency bitmap is a monochrome version of a bitmap.  White areas in the transparency bitmap are transparent; black areas are not transparent.

Location: Enumeration (optional)

Specifies where to display the prompt in relation to the region (see Region below).

UpperLeft! Display prompt upper left.

UpperRight!Display prompt upper right.

Right! Display prompt right.

LowerRight! Display prompt lower right.

LowerLeft! Display prompt lower left.

Left! Display prompt left.

Specify! Display prompt as specified by Top and Left.

Left: Numeric (optional)

Specifies the percentage of the document window's horizontal space left of the center of the message box.  Required only if Location is Specify!.

Top: Numeric (optional)

Specifies the percentage of the document window's vertical space above the center of the message box.  Required only if Location is Specify!.

Region: String (optional)

The named region the prompt points to.  Not required if Top and Left are specified.


CoachPromptClose

CoachPromptClose (PromptName: String)

 Related Topics

Closes a prompt.

Parameters

PromptName: String

Name of the prompt to close.  This is the same name specified in PromptName of CoachPrompt.


CoachRegister

Boolean := CoachRegister (AppName: String)

Register a coach macro with a specified application.

Return Value

True if a coach is not already registered with the application, False if not.

Parameters

AppName: String

Application name.


CoachRemoveDialogFilter

CoachRemoveDialogFilter (DialogRegionName: String)

 Related Topics

Disables a dialog box filter and removes it from memory.

Parameters

DialogRegionName: String

Specifies a dialog filter to remove.


CoachSetDialogFilter

CoachSetDialogFilter (DialogRegionName: String; Label: Label; DefaultAction: Enumeration)

 Related Topics

Defines a filter for a dialog box.  The filter definition remains in memory until removed by CoachRemoveDialogFilter or until the macro ends.  Whenever a dialog box is active, notification is sent to the dialog filter callback.  Actions in the dialog can be filtered (allowed or disallowed) by the callback.

Parameters

DialogRegionName: String

Specifies a dialog to filter.

Label: Label

Specifies the name of a callback label to call when the dialog box is displayed.

DefaultAction: Enumeration (optional)

Specifies whether the default action allows events or throws them away.  If a default action is not specified, all events are allowed.

Allow! Allow the event.

ThrowAway! Do not allow the event.

Returns

When the dialog is invoked or a control on the dialog is activated, a variable array is created indicating the actions the user is taking.  The dialog callback procedure can test each item in the array and perform appropriate operations.

The variable array's name is the same as the callback label.  For example, the variable array of TabSetCB@ is TabSetCB[array item].

The variable array contains the following information depending on the message sent in Callback[5].

Note

For more information, see Callback Data Description.


Condition

Enumeration := Condition (Condition: Enumeration or Numeric; State: Enumeration)

Determines how a macro responds to a Cancel, Error, NotFound, or user-defined condition.

Return Value

Off! Previous condition state was Off!

On! Previous condition state was On!

Example

If CancelCondition is On! to start, the following two lines return the following results.

vCnd1 := Condition (CancelCondition!; Off!)

Result := vCnd1 = On! (condition was On!, now is Off!)

vCnd2 := Condition (CancelCondition!; On!)

Result := vCnd2 = Off! (condition was Off!, now is On!)

Parameters

Condition: Enumeration or Numeric

Specifies a condition to change.  See OnCondition for a description of how to specify a user-defined condition number.

CancelCondition!

ErrorCondition!

NotFoundCondition!

UserDefinedCondition!

State: Enumeration (optional)

Sets the state of the specified condition.  Default: Condition(On!).  If missing, the current state is returned without changing it.

Off! Ignores the specified condition.

On! Stops a macro unless preceded by OnCondition, which directs macro execution to a specified Label.


Constant

Constant ({<Name> Variable := <Value> Any})

Defines a constant variable (an identifier whose value cannot change at run-time).

Constants make macros easier to read.  For example,

Constant (Start := 0; Stop := 1)

defines two constants.  Start is replaced by 0 wherever it occurs in the macro, and Stop by 1.

Constants are compile-time only commands that are constant from the point of declaration to the end of the macro.  All constants have a single value (array constants are not accepted), and cannot appear on the left side of subsequent assignment statements (compile-time error occurs).

Separate multiple definitions with a semicolon.  Parentheses are optional.

Examples

Constant (Inch := 2.54C; Diameter := Inch)

Constant Radius := 10I

Constant (Tel := "222-5555")

Constant Team := "Dan, Steve, Alan, Barry, Jimmy, Dave"


Constants

Numeric := Constants (Constant: Enumeration)

Returns various mathematical and physical constants.

Parameters

Constant: Enumeration

Math constant to return.

e! Napierian base of natural logarithm.

pi! Radio of the circumference of a circle to its diameter.

EulersConstant! Eulers constant (sometimes called oiler's constant).

GoldenRatio! Approximately (1+(square root of 5))/2.


Continue

Executes the code in the next CaseOf statement without evaluating its expression.  See Switch.


ConvertType

Any := ConvertType (Value: Any; Type: Enumeration; DefaultUnitsType: Enumeration)

Forces the macro system to convert a value to a specified data type.

Note

If Value is a number and Type is a measurement, or Value is a measurement and Type is a number, a measurement conversion is also applied to the magnitude of the value to convert between the measurement and the type specified by DefaultUnitsType.  You can prevent this by specifying None! for DefaultUnitsType.

If both Value and Type are measurements, or both are numbers, DefaultUnitsType is not used.

Return Value

Converted data type.

Example

vTestValue := 72

vResult = ConvertType (vTestValue; Centimeters!; Points!)

Result: vResult = 2.54C

Parameters

Value: Any

Value to convert.

Type: Enumeration

Convert Value to one of the following data types.

Boolean! Convert the value to a boolean value.

String! Convert the value to a WP string value.

WPString! Convert the value to a WP string value.

AnsiString! Convert the value to an Ansi string value.

OemString! Convert the value to an Oem string value.

Number! Convert the value to a number value, either a float or an integer. The Value is converted to an integer if the result has no fractional part and is in the range of an integer.

Float! Convert the value to a float value.

Integer! Convert the value to an integer value.

Measurement! Convert the value to the measurement type specified by the current default units type (see DefaultUnits).

Centimeters! Convert the value to a centimeters unit value.

Inches! Convert the value to an inches unit value.

Millimeters! Convert the value to a millimeters unit value.

Points! Convert the value to a points unit value.

WPUnits! Convert the value to a WPUnits unit value.

RawBinary! Convert the value to a raw binary data value.

DefaultUnitsType: Enumeration (optional)

Default units value to use when converting between measurements and numbers.  If both Value and Type are measurements, or both are numeric, this parameter is not used.  Default: DefaultUnits!

None! Do no number to measurement conversion.  This causes no conversion of the magnitude of the numeric value.  It only changes the type of the value.  See the None! value of the DefaultUnits command.

DefaultUnits! Assume that numbers are in the units specified by the current default units type.

Centimeters! Assume that numbers are in units of centimeters.

Inches!  Assume that numbers are in units of inches.

Millimeters! Assume that numbers are in units of millimeters.

Points!  Assume that numbers are in units of points.

WPUnits! Assume that numbers are in units of WPUnits.


CopyFile

Boolean := CopyFile (SourceFilename: String; DestinationFilename: String; Prompts: Enumeration)

 Related Topics  [image]  Example

Copies a file.

Return Value

True if successful, False if not.

Parameters

SourceFilename: String

A path and filename.

DestinationFilename: String

A path and filename.

Prompts: Enumeration (optional)

Default: NoPrompts!

NoPrompts!

Prompts! Confirm replacement if destination file exists.


cos

Numeric := cos (Angle: Numeric)

Returns the cosine of an angle in radians.

Parameters

Angle: Numeric

Angle in radians.


cosh

Numeric := cosh (Angle: Numeric)

Returns the hyperbolic cosine of an angle in radians.

Parameters

Angle: Numeric

Angle in radians.


CreateDirectory

Boolean := CreateDirectory (DirectoryName: String; Prompts: Enumeration)

 Related Topics  [image]  Example

Creates a directory.

Return Value

True if successful, False if not.

Parameters

DirectoryName: String

Include full path.

Prompts: Enumeration (optional)

Default: NoPrompts!

NoPrompts!

Prompts! Prompt if directory exists.


CToN

Numeric := CToN (Character: String)

 Related Topics  [image]  Example

Converts a keyboard character to its decimal equivalent.

Return Value

The decimal equivalent of a keyboard character.

Parameters

Character: String

A keyboard character to convert.  If a string is used, the decimal equivalent of the first character is returned.


CubeRoot

Numeric := CubeRoot (Value: Numeric)

Returns the cube root of a value.

Parameters

Value: Numeric

Return cube root of this value.


DateAndTime

Numeric := DateAndTime (Day: Numeric; Month: Enumeration or Numeric; Year: Numeric; Hour: Numeric; Minutes: Numeric; Seconds: Numeric; Hundredths: Numeric)

Returns a value representing the date and time.

The earliest valid date is January 1, 1601.

Return Value

A number representing the current day, month, year, hour, minute, second, and hundredths of a second is returned if the corresponding parameter is not used.

Examples

DateAndCurrentTime := DateAndTime()

MessageBox (x; "Date"; DateString (TodaysDate))

MessageBox (x; "Time"; TimeString (TodaysDate))

Explanation: MessageBox 1 displays current date.  MessageBox 2 displays current time.

vResult := DateAndTime (15; 10; 1994; 00; 10; 10; 10)

vDate := DateString (vResult)

vTime := TimeString (vResult)

MessageBox (x; "Date"; vDate)

MessageBox (x; "Time"; vTime)

Explanation: Messagebox 1 displays 10/15/94.  Messagebox 2 displays 12:10:10 AM.

Parameters

Day: Numeric (optional)

A number representing a day of the week.

Month: Enumeration or Numeric (optional)

One of the following enumerations, or a number representing a month (number in brackets).

January! [1]

February! [2]

March! [3]

April! [4]

May! [5]

June! [6]

July! [7]

August! [8]

September! [9]

October! [10]

November! [11]

December! [12]

Year: Numeric (optional)

A number representing a year.  Example: 1996.

Hour: Numeric (optional)

A number representing an hour.

Minutes: Numeric (optional)

A number representing a minute.

Seconds: Numeric (optional)

A number representing a second.

Hundredths: Numeric (optional)

A number representing hundredths of a second.


DateDay

Numeric := DateDay (Day: Numeric)

  Example

Returns a numeric value representing a day of the month.

Example

vDay := DateDay()

Messagebox (x; "Day of the Month"; vDay)

Result (current system day): 17

Parameters

Day: Numeric (optional)

A number representing a date, or the system date if not used.  For a number, see DateAndTime.


DateMonth

Enumeration or Numeric := DateMonth (Date: Numeric)

  Example

Returns an enumeration representing the month.

Return Value

January! [1]

February! [2]

March! [3]

April! [4]

May! [5]

June! [6]

July! [7]

August! [8]

September! [9]

October! [10]

November! [11]

December! [12]

Example

// Assume current month is February

vMonth := DateMonth()

MessageBox (x; "Month"; vMonth)

Result (current system month): 2

Parameters

Date: Numeric (optional)

A number representing a date, or the system date if not used.  For a number, see DateAndTime.


DateMonthName

String := DateMonthName (Date: Numeric; Type: Enumeration)

Returns the name of a month.

Examples

vDate := DateAndTime (1; 12; 1996)

vMonth := DateMonthName (vDate)

MessageBox (x; "Month"; vMonth)

Result: December

vDate := DateAndTime (1; 12; 1996)

vMonth := DateMonthName (vDate; Short!)

MessageBox (x; "Month"; vMonth)

Result: Dec

Parameters

Date: Numeric (optional)

A number representing a date, or the system date if not used.  For a number, see DateAndTime.

Type: Enumeration (optional)

Default: Long!

Short! Month abbreviated

Long! Month spelled out.


DateString

String := DateString (Date: Numeric; Type: Enumeration; Format: String)

Returns the date in a string.

Examples

vNmbrDate := DateAndTime (1; 1; 2000)

vDate := DateString (vNmbrDate; ; "dd/MM/yyyy (dddd)")

MessageBox (x; "Date String"; vDate)

Result: 01/01/2000 (Saturday)

vDate := DateString (; Short!)

MessageBox (x; "System Date"; vDate)

Result (system date): 2/17/96

vDate := DateString (; Long!)

MessageBox (x; "System Date"; vDate)

Result (system date): Saturday, February 17, 1996

Parameters

Date: Numeric (optional)

A number representing a date, or the system date if not used.  For a number, see DateAndTime.

Type: Enumeration (optional)

Default: Short!

Short! Date represented as digits.

Long! Date spelled out.

Format: String (optional)

Specifies a date string format.  If missing, the current system format from the Windows* Control Panel is used.  See example above.

Day (month)

d (digits without leading zeros for single digits days)

dd (digits with leading zeros for single digit days)

Day (week)

ddd (three-letter abbreviation)

dddd (day of the week)

Month

M (digits without leading zeros for single digit months)

MM (digits with leading zeros for single digit months)

MMM (three-letter abbreviation)

MMMM (month spelled out)

Year

y (last digit only)

yy (last two digits)

yyyy (four digits)

Period/Era

gg (ignored if era string is not associated)


DateWeekday

Enumeration := DateWeekday (Date: Numeric)

Returns an enumeration representing the day of the week.

Return Value

Sunday!

Monday!

Tuesday!

Wednesday!

Thursday!

Friday!

Saturday!

Example

vDate := DateAndTime (1; 1; 2000)

If(DateWeekday(vDate) = DateWeekday.Date.Saturday!)

MessageBox (x; "Day of the Week"; "Saturday")

Endif

Result: MessageBox displays "Saturday."

Parameters

Date: Numeric (optional)

A number representing a date, or the system date if not used.  For a number, see DateAndTime.


DateWeekdayName

String := DateWeekdayName (Date: Numeric; Type: Enumeration)

Returns the name of a day of the week.

Example

vDate := DateAndTime (17; 2; 1996)

vWeekday := DateWeekdayName (vDate; Short!)

MessageBox (x; "Weekday"; vWeekday)

Result: Sat

Parameters

Date: Numeric (optional)

A number representing a date, or the system date if not used.  For a number, see DateAndTime.

Type: Enumeration (optional)

Default: Long!

Short! Weekday abbreviated.

Long! Weekday spelled out.


DateYear

Numeric := DateYear (Date: Numeric)

  Example

Returns a value representing a year.

Example

vYear := DateYear()

MessageBox (x; "Year"; vYear)

Result (system date): 1996

Parameters

Date: Numeric (optional)

A number representing a date, or the system date if not used.  For a number, see DateAndTime.


DDEExecute

DDEExecute (ConversationID: Numeric; Command: String)

 Related Topics  [image]  Example

Sends a command string to a client application.

See the client application's documentation for command names and syntax.

Parameters

ConversationID: Numeric

A number that links the server and client applications.  DDEInitiate returns ConversationID in a variable.

Command: String

A command to execute.


DDEExecuteExt

Numeric := DDEExecuteExt (ConversationID: Numeric; Command: String; TimeOut: Numeric; Label: Label)

 Related Topics  [image]  Example

Sends a command to a client application, and returns a value that indicates if the command was successfully processed.

See the client application's documentation for command names and syntax.

Return Value

A number greater than 0 if successful, or 0 if not.

Parameters

ConversationID: Numeric

A number that links the server and client applications.  DDEInitiate returns ConversationID in a variable.

Command: String

A command to execute.

TimeOut: Numeric

Asychronous DDE: Set TimeOut to 0 or a negative value.  DDE returns immediately, and notifies the macro that the command was delivered.  When the client application acknowledges receiving the command, DDE notifies the macro and the macro calls Label.  The return value is invalid for asychronous DDE, because the client application has not yet processed the command.

Synchronous DDE: Set TimeOut to a positive integer, which specifies the maximum number of milliseconds to wait while the client application processes the command.  The result is returned when the command is processed or DDE times out (command is not processed within the specified time).  See Return Value above.

Label: Label (optional)

The Label to call when the client application acknowledges receiving the command (see TimeOut parameter above).  If the Label statement does not include Return, macro behavior is unpredictable.

If Label is missing, DDEExecuteExt works similar to DDEExecute.


DDEInitiate

Numeric := DDEInitiate (ServiceName: String; TopicName: String)

 Related Topics  [image]  Example

Starts a DDE conversation with a client application, and returns a conversation ID.

A conversation must be started between server and client applications before you can use commands such as DDEPoke, DDERequest, and DDEExecute.

Return Value

A number that links the server and client applications is returned, or 0 if the conversation is not started.

Parameters

ServiceName: String

A DDE service name.  See a client application's documentation.

WPWin7_Macros (WordPerfect 7)

Presentations (Presentations 7)

WPWin60_Macros (WordPerfect 6.1)

GroupWise* (GroupWise 4.1)

TopicName: String

A topic name.  See the client application's documentation.

Commands (WordPerfect 7)

Command (Presentations)

Commands (WordPerfect 6.1)

Command (GroupWise 4.1)


DDEPoke

DDEPoke (ConversationID: Numeric; ItemName: String; ItemData: String)

 Related Topics  [image]  Example

Assigns data to an item in a client application.

Parameters

ConversationID: Numeric

A number that links the server and client applications.  DDEInitiate returns ConversationID in a variable.

ItemName: String

A client application item.  See the client application's documentation for item names.

ItemData: String

The data to assign to a client application item.

Note

Check client application documentation to see if it supports XTYP_POKE transactions.  Many applications do not.


DDERequest

String := DDERequest (ConversationID: Numeric; ItemName: String)

 Related Topics  [image]  Example

Assigns the contents of a client application item to a macro variable.

Return Value

The contents of the client application item specified by ItemName.

Parameters

ConversationID: Numeric

A number that links the server and client applications.  DDEInitiate returns ConversationID in a variable.

ItemName: String

The name of a client application item.

Note

Check client application documentation to see if it supports XTYP_REQUEST transactions.  Many applications do not.


DDETerminate

DDETerminate (ConversationID: Numeric)

 Related Topics  [image]  Example

Ends a DDE conversation with a client application.

Parameters

ConversationID: Numeric

A number that links the server and client applications.  DDEInitiate returns ConversationID in a variable.


DDETerminateAll

DDETerminateAll()

 Related Topics  [image]  Example

Ends all DDE conversations.


Declare

Declare ({<VariableName> Variable := <Value> Any})

 Related Topics  [image]  Example

Creates a local variable or array, which stores as many variables, constants, or expressions as memory allows.

An array can have up to 10 dimensions, and up to 32,767 elements per dimension depending on the amount of available memory.  In the following example, Declare creates ArrayA with 10 elements and ArrayB with five elements.  An element in each array is assigned a value.  Parentheses are optional.

Examples

Declare(ArrayA[10]; ArrayB[5])

ArrayA[3] := "John"

Explanation: Assigns "John" to the third element in ArrayA.

ArrayB[5] := ArrayA[3]

Explanation: Assigns "John" to the fifth element in ArrayB.

In the next example, Declare creates a two-dimensional array (ArrayC) with 100 elements (10 rows and 10 columns).  One element is assigned a value.

Declare ArrayC[10;10]

ArrayC[2;3] := 3+6

Explanation: Assigns 9 to the element at row 2, column 3.

Parameters

<VariableName> Variable

The name of a local variable or array.  Use a semicolon to separate names when declaring more than one variable or array.  If an array is declared, enclose the array indices in brackets.  Use a semicolon to separate elements in a multi-dimensional array.

<Value> Any (optional)

Value assigned to <Variable> at time of declaration.  For example, Persist vTest = 20.  vTest equals 20 at run time.  If missing, the value of <Variable> is undefined.


Default:

Specifies the code to execute when no CaseOF <Selector> matches the control expression in a Switch statement.  See Switch.


DefaultUnits

Enumeration := DefaultUnits (Units: Enumeration)

  Example

DefaultUnits specifies the default unit of measure, and returns the previous unit of measure.  You can set a new value, and then restore the previous value.

Return Values

The previous unit value.

None!

Centimeters!

Inches!

Millimeters!

Points!

WPUnits!

Examples

In the first example, Advance uses the default unit of measure (WPUnits).  In the second, Advance overrides the default unit of measure and uses inches.  In the third, DefaultUnits specifies centimeters as the default unit of measure.

Advance(AdvanceFromTop!; 4)

Explanation: Advance insertion point 4 WPUnits.

Advance(AdvanceFromTop!; 4")

Explanation: Advance insertion point 4 inches.

DefaultUnits(Centimeters!)

Advance(AdvanceFromTop!; 4)

Explanation: Advance insertion point 4 centimeters.

The default unit of measure is effective until changed by another DefaultUnits command.  If not specified by DefaultUnits, the default unit of measure is WPUnits.

Discussion

None! has been added to the list of possible units.  Normally, when a non-units value such as 1200 is combined with a units value such as 1.0C, the non-units value assumes the default unit type.  If the default unit type is WPUnits,

1.0C + 1200 = 3.54C (1200 WPUnits = 2.54C)

If, however, the default unit is set to None!, the non-units value assumes the unit type of the value it is combined with (no conversion is performed).  For example,

1.0C + 1200 = 1201.0C

With the default unit set to None!, 1200 assumes the unit type of centimeter.

Parameters

Units: Enumeration (optional)

A unit of measure.  If missing, the current default unit of measure is returned, but no unit of measure is set.

None!

Centimeters!

Inches!

Millimeters!

Points! (One Point equals 1/72 of an inch)

WPUnits! (One WordPerfect unit equals 1/1200 of an inch)

WP1200ths! (Synonym for WPUnits!)


DegreesToRadians

Numeric := DegreesToRadians (Degrees: Numeric)

Converts an angle in degrees to radians.

Parameters

Degrees: Numeric

Angle in degrees.


DeleteDirectory

Boolean := DeleteDirectory (DirectoryName: String; Prompts: Enumeration)

 Related Topics  [image]  Example

Deletes a directory.

Return Value

True if successful, False if not.

Parameters

DirectoryName: String

Include full path.

Prompts: Enumeration (optional)

Default: NoPrompts!

NoPrompts!

Prompts! Prompt if directory does not exist.


DeleteFile

Boolean := DeleteFile (Filename: String; Prompts: Enumeration)

 Related Topics  [image]  Example

Deletes a file(s).

Return Value

True if successful, False if not.

Parameters

Filename: String

Include full path.  If file not specified, deletes all files in directory!

Prompts: Enumeration (optional)

Default: NoPrompts!

NoPrompts!

Prompts! Prompt if file does not exist.


DialogAddBitmap

DialogAddBitmap (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration; FileName: String; Name: String; TransparentColor: Numeric)

Adds a bitmap control to a dialog box.  After DialogLoad or DialogShow, bitmap controls can be added to a dialog created with the Dialog Editor.

Example

APPLICATION(A1; "WordPerfect"; Default; "US")

OnError (ErrorMsg)

DialogDefine ("Dialog1"; 50; 50; 200; 100; Percent! | OK! | Cancel!; "Dialog Example")

DialogAddPushButton("Dialog1"; "PushBttn1"; 153; 35; 38; 14; NonDefaultBttn!; "Add Ctrl 1")

DialogAddPushButton("Dialog1"; "PushBttn2"; 153; 55; 38; 14; NonDefaultBttn!; "Add Ctrl 2")

DialogShow ("Dialog1"; "WordPerfect"; Msg)

CallbackWait

Quit

Label(Msg)

If (Msg[5] = 274)

DialogDestroy ("Dialog1")

CallbackResume

Return

Endif

Switch (Msg[3])

CaseOf "OKBttn": MessageBox(x; "OK Button"; "You pressed OK"; IconInformation!)

CaseOf "CancelBttn":

DialogDestroy("Dialog1")

CallBackResume

Return

CaseOf "PushBttn1":

DialogAddBitmap ("Dialog1"; "BCtrl"; 10; 10; 50; 50; SizeBmpToCtl!; "c:\windows\cars.bmp")

CaseOf "PushBttn2":

RegionSetBitmapFilename ("Dialog1.BCtrl"; "c:\windows\arcade.bmp")

EndSwitch

Return

Label (ErrorMsg)

MessageBox (x; "Error"; "You pressed Add Ctrl 2 before Add Ctrl 1"; IconInformation!)

Quit

Parameters

Dialog: String

The name or number of the dialog box to contain the bitmap control (see DialogDefine).

Control: String

A name or number that identifies the bitmap control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the bitmap.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the bitmap.

Width: Numeric

Width of the bitmap control in dialog units.

Height: Numeric

Height of the bitmap control in dialog units.

Style: Enumeration (optional)

Specifies how the bitmap is displayed.

SizeCtlToBmp!

SizeBmpToCtl!

Transparent!

FileName: String

Path and name of a bitmap file, or resource file such as a .dll.

Name: String (optional)

Specifies a bitmap in a resource file such as "#1".

TransparentColor: Numeric (optional)

Any color between 0 and 16,777,215 (0 is black).  Colors are based on RGB colors.

R=Red (0-255 in bits 0-7)

G=Green (0-255 in bits 8-15)

B=Blue (0-255 in bits 16-23)


DialogAddCheckBox

DialogAddCheckBox (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Text: String; MacroVar: Varible; Style: Enumeration)

 Related Topics  [image]  Example

Adds a check box control to a dialog box.  After DialogLoad or DialogShow, a check box can be added to a dialog created with the Dialog Editor.

Parameters

Dialog: String

The name or number of the dialog box to contain the check box control (see DialogDefine).

Control: String

A name or number that identifies the check box control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the check box.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the check box.

Width: Numeric

Width of the check box control in dialog units.

Height: Numeric

Height of the check box control in dialog units.

Text: String

Text displayed to the right of the check box, unless TextOnLeft! style is used.  See Style below.

MacroVar: Variable

1 is returned in this variable when check box is checked, and 0 when not checked.  The default value is 0.  If MacroVar is assigned a value greater than 0 before the check box is added, the check box is checked when the dialog box is displayed.

Style: Enumeration (optional)

Checkbox styles are exclusive (choose only one).  Type | between enumerations to combine styles.

CheckboxAuto! Toggles between check and clear.

Checkbox! Can be one of two states: check or clear.  See RegionSetCheck.

Checkbox3State! Can be one of three states: check, clear, or gray.  See RegionSetCheck.

CheckboxAuto3State! Toggles between check, clear, and gray.

TextOnLeft! Positions text to the left of the check box.


DialogAddColorWheel

DialogAddColorWheel (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; MacroVar: Variable)

 Related Topics  [image]  Example

Adds a color wheel control to a dialog box, and returns a number that represents the selected color when the dialog is dismissed.  After DialogShow or DialogLoad, a color wheel can be added to a dialog created with the Dialog Editor.

The color selection consists of three color elements (red, green, and blue), separated into color values by the formula given below (see MacroVar parameter below).  These values are used in Windows* programming to specify the color of a pen or brush.

Parameters

Dialog: String

The name or number of the dialog box to contain the color wheel control (see DialogDefine).

Control: String

A name or number that identifies the color wheel control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the color wheel control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the color wheel control.

Width: Numeric

Width of the color wheel control in dialog units.

Height: Numeric

Height of the color wheel control in dialog units.

MacroVar: Variable

A number corresponding to a color selection is returned in this variable.  This number can be divided into three other numbers which correspond to red, green, and blue.  The formulas are:

vRed := MacroVar % 256 (vRed contains the red component, which is the remainder of MacroVar divided by 256)

vGreen := MacroVar / 256 % 256 (vGreen contains the green component, which is the remainder of MacroVar divided by 256 divided by 256)

vBlue := MacroVar / 256 / 256 (vBlue contains the blue component, which is the result of MacroVar divided by 256 divided by 256)

Preselect a color by assigning its value to MacroVar before adding the color wheel control.


DialogAddComboBox

DialogAddComboBox (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration; MacroVar: Variable; LimitText: Numeric)

 Related Topics  [image]  Example

Adds a combo box control to a dialog box.  After DialogShow or DialogLoad, a combo box can be added to a dialog created with the Dialog Editor.

The combo box displays an edit box and a list box.  You enter text in the edit box, or double-click a list item to insert.  Use DialogAddListItem to create list box items.

Parameters

Dialog: String

The name or number of the dialog box to contain the combo box control (see DialogDefine).

Control: String

A name or number that identifies the combo box control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the combo box.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the combo box.

Width: Numeric

Width of the combo box control in dialog units.

Height: Numeric

Height of the combo box control in dialog units.

Style: Enumeration

Combo box styles.  The first three styles are exclusive (choose only one).  Type | between enumerations to combine styles.

Droplist! Displays a read-only edit control.  Clicking the arrow to the right of the edit control displays a drop-down list box.

Dropdown! Displays an edit control.  Clicking the arrow to the right of the edit control displays a drop-down list box.

Simple! Displays an edit control and an opened drop-down list box.

Sort! Items are sorted alphabetically.  If Sort! is used by itself, Simple! is the default combo box style.  See DialogAddListItem.

WPChars! Non-keyboard characters allowed in a list item.  See DialogAddListItem.

AutoHScroll! Automatic horizontal scrolling.

OEMConvert! Convert ansi to OEM character set.

Example

Sort! | Simple!

Explanation: Name search allowed on a sorted list box.  A vertical scrollbar automatically appears when needed.

MacroVar: Variable

The selected combo box item is returned in this variable.  An item can be assigned to MacroVar before the control is added to a dialog.

LimitText: Numeric

Maximum number of characters the edit control accepts, up to the number of characters that fit in the edit box.  This number has no effect if you choose style DropList!.


DialogAddControl

DialogAddControl (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Class: String; Style: Numeric; WindowName: String; MacroVar: Variable; Instance: Numeric)

 Related Topics  [image]  Example

Adds a custom control to a dialog box.  After DialogShow or DialogLoad, a custom control can be added to a dialog created with the Dialog Editor.

The macro system knows nothing about custom controls.  The user is responsible for all control message processing and queries.

Parameters

Dialog: String

The name or number of the dialog box to contain the custom control (see DialogDefine).

Control: String

A name or number that identifies the custom control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the custom control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the custom control.

Width: Numeric

Width of the custom control in dialog units.

Height: Numeric

Height of the custom control in dialog units.

Class: String

The name of the control class.  Standard Windows* classes include Button, ComboBox, Edit, ListBox, ScrollBar, and Static.  Other controls such as Meters and Spin buttons must be defined in a DLL (see Instance parameter below).

Style: Numeric

A number that defines a valid style within the control Window class.  For example, an edit control includes styles such as left, multiline, and password.  The values for standard Windows styles are in the Windows SDK.

WindowName: String

Control text.  For example, the text that appears on a button control.  Set this value to "" if the control does not accept text.

MacroVar: Variable

The value returned by a control.  This variable is retained for backward compatibility.  You must query the control to retrieve needed values.

Instance: Numeric

This parameter is retained for backward compatibility.  If the DLL is loaded, the macro should be able to locate the control.


DialogAddCounter

DialogAddCounter (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric ; Format: Enumeration; MacroVar: Variable; CountMin: Any; CountMax: Any; CountStep: Any)

 Related Topics  [image]  Example

Adds a counter control to a dialog box.  After DialogShow or DialogLoad, a counter can be added to a dialog created with the Dialog Editor.

Click the counter button to insert a number in the edit box that is within a specified range (see CountMin and CountMax parameters below).

Parameters

Dialog: String

The name or number of the dialog box to contain the counter control (see DialogDefine).

Control: String

A name or number that identifies the counter control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the counter control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the counter control.

Width: Numeric

Width of the counter control in dialog units.

Height: Numeric

Height of the counter control in dialog units.

Format: Enumeration (optional)

Specifies counters of various unit values. When a value is entered without a unit of measure (24 instead of 24i), the value assumes the specified counter unit (not the default unit type). All the Display... enumerations are exclusive (use only one).

DisplayNormal! (-2147483647 to 2147483647)

DisplayWPU! (-2147483647 to 2147483647)

DisplayPoints! (-4294967.0 to 4294966.0)

DisplayCentimeters! (-151518.0 to 151519.0)

DisplayFixedPoint! (-32767.0 to 32767.0)

DisplayPercent! (-2147483647 to 2147483647)

DisplayInches! (-59651.0 to 59652.0)

DisplayInches2! (-59651.0 to 59652.0)

DisplayMillimeters! (-1515513.0 to 1515514.0)

DisplayI_Inches (-59651.0 to 59652.0)

AutoHScroll!

NoScroll!

AutoValidated!

Type | between enumerations to combine styles.  Use only one Display enumeration.

MacroVar: Variable

The selected counter number is returned in this variable.  A number can be assigned to MacroVar before the dialog is displayed.

CountMin: Any

The minimum number that you can insert by clicking the counter button.  Out of range values are replaced by the minimum value.

CountMax: Any

The maximum number that you can insert by clicking the counter button.  Out of range values are replaced by the minimum value.

CountStep: Any

The increment and decrement step value.  Out of range values are replaced by the minimum or maximum values.


DialogAddDate

DialogAddDate (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration; MacroVar: Variable; Year: Numeric; Month: Enumeration; Day: Numeric)

  Example

Adds a date to a dialog box.  After DialogShow or DialogLoad, a date can be added to a dialog created with the Dialog Editor.

Parameters

Dialog: String

The name or number of the dialog box to contain the date control (see DialogDefine).

Control: String

A name or number that identifies the date control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the date.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the date.

Width: Numeric

Width of the date control in dialog units.

Height: Numeric

Height of the date control in dialog units.

Style: Enumeration (optional)

Determines whether date is valid.

Validate!

MacroVar: Variable

Initial value when the control is displayed, and the value of the control when the dialog is dismissed.

Year: Numeric (optional)

Number representing the year.

Month: Enumeration (optional)

January!

February!

March!

April!

May!

June!

July!

August!

September!

October!

November!

December!

Day: Numeric (optional)

Number representing the day.


DialogAddEditBox

DialogAddEditBox (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration; MacroVar: Variable; LimitText: Numeric)

 Related Topics  [image]  Example

Adds an edit control to a dialog box.  After DialogShow, an edit box can be added to a dialog created with the Dialog Editor.

The text entered in the edit box is returned in MacroVar when the dialog is dismissed (see MacroVar parameter).

Parameters

Dialog: String

The name or number of the dialog box to contain the edit control (see DialogDefine).

Control: String

A name or number that identifies the edit control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the edit control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the edit control.

Width: Numeric

Width of the edit control in dialog units.

Height: Numeric

Height of the edit control in dialog units.

Style: Enumeration (optional)

Edit control styles.  Type | between enumerations to combine styles.  Not all combinations are possible.

Left! Text is left justified.

Right! Text is right justified if Multiline! style is set and WPChars! style is not set.

Center! Text is centered if Multiline! style is set and WPChars! style is not set.

VScroll! Edit control with a vertical scroll bar.  Use with Multiline!

HScroll! Edit control with a horizontal scroll bar.  Use with Multiline! or WPChars!.

WPChars! Can display WP Character box (press Ctrl+W).  Non-keyboard characters allowed.

Multiline! Multiple lines of input automatically wrap to the next line.  Press Enter to cause the default button action (see DialogAddPushButton).  If Enter2Hrtn! style is set in DialogDefine, press Enter to move the insertion point to the next line.

Uppercase! Text automatically converted to uppercase.

Lowercase! Text automatically converted to lowercase.

Password! Text automatically displayed with asterisk (*) characters.  The actual characters are stored by the edit control.

WordWrap! Text wraps if Multiline! is set.

SoftRet! Text contains Soft Return codes [SRt].

Attributes! Underline (press Ctrl+U) and italics (press Ctrl+I) allowed if WPChars! style is set.

NoTabs! Tab codes not exported with output.

NoWPChar! Cannot display WP Character dialog box.  Non-keyboard characters not allowed.

AutoVScroll! Automatic vertical scrolling.

AutoHScroll! Automatic horizontal scrolling.

OEMConvert! Convert ansi to OEM character set.

ReadOnly! Edit control is read only.

WantReturn! Pressing Enter produces a hard return.  Use with Multiline!.

MacroVar: Variable

The text entered in the edit box is returned in this variable.  Text can be assigned to MacroVar before the dialog is displayed.

LimitText: Numeric

The maximum number of characters the edit control accepts.


DialogAddFileNameBox

DialogAddFileNameBox (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration; MacroVar: Variable; DefaultDir: String; Template: String)

 Related Topics  [image]  Example

Adds a filename edit control to a dialog box.  After DialogShow or DialogLoad, a filename box can be added to a dialog created with the Dialog Editor.

The filename edit control consists of an edit control and a button control.  Clicking the button displays the Select Directory or Select File dialog box depending on the control style (see Style parameter).

Parameters

Dialog: String

The name or number of the dialog box to contain the filename edit control (see DialogDefine).

Control: String

A name or number that identifies the filename edit control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the filename edit control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the filename edit control.

Width: Numeric

Width of the filename edit control in dialog units.

Height: Numeric

Height of the filename edit control in dialog units.

Style: Enumeration (optional)

Filename edit control styles.  Default: FilesAndDirs!.  Type | between enumerations to combine styles.

FilesAndDirs! Directories and filenames allowed.

DirOnly! Only directories allowed.

FileDoesntHaveToExist!

MacroVar: Variable

The directory or filename entered in the edit box is returned in this variable.  A name can be assigned to MacroVar before the macro is displayed.

DefaultDir: String (optional)

The default directory when the Select File dialog box is displayed.

Template: String (optional)

The filenames to display in the Select File dialog box.  For example, "*.*" (all files) and "*.bat" (all batch files).


DialogAddFrame

DialogAddFrame (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration)

 Related Topics  [image]  Example

Adds a frame to a dialog box.  After DialogShow or DialogLoad, a frame can be added to a dialog created with the Dialog Editor.

You can combine frame styles by creating two frames the same size and at the same position.  For example, you can create a black frame and a white-filled frame (see Control and Style parameters).  You can also create custom controls by combining frames and hot spots (see DialogAddHotSpot and DialogShow).

Parameters

Dialog: String

The name or number of the dialog box to contain the frame control (see DialogDefine).

Control: String

A name or number that identifies the frame control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the frame control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the frame control.

Width: Numeric

Width of the frame control in dialog units.

Height: Numeric

Height of the frame control in dialog units.

Style: Enumeration (optional)

Frame styles.  Type | between enumerations to combine styles.  Not all combinations are possible.

Frame! Frame only.

Black! Black frame.

Gray! Gray frame.  Gray is the default DeskTop color of the Windows* Default color scheme.  To select a different color, choose Colors in the Windows Control Panel.

White! White frame.

Filled! Filled frame.

Examples

Frame! | White!

Explanation: White frame displayed.

Filled! | White!

Explanation: White-filled frame displayed.


DialogAddGroupBox

DialogAddGroupBox (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Title: String)

 Related Topics  [image]  Example

Draws a rectangle around related dialog controls such as buttons.  After DialogShow or DialogLoad, a group box can be added to a dialog created with the Dialog Editor.

Grouping related controls helps narrow user options.

Parameters

Dialog: String

The name or number of the dialog box to contain the group box control (see DialogDefine).

Control: String

A name or number that identifies the group box control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the group box control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the group box control.

Width: Numeric

Width of the group box control in dialog units.

Height: Numeric

Height of the group box control in dialog units.

Title: String

The title displayed at the top left corner.


DialogAddHLine

DialogAddHLine (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Length: Numeric)

 Related Topics  [image]  Example

Adds a horizontal line to a dialog box.  After DialogShow or DialogLoad, a horizontal line can be added to a dialog created with the Dialog Editor.

Parameters

Dialog: String

The name or number of the dialog box to contain the horizontal line control (see DialogDefine).

Control: String

A name or number that identifies the horizontal line control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the horizontal line control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the horizontal line control.

Length: Numeric

Length of the horizontal line control in dialog units.


DialogAddHotSpot

DialogAddHotSpot (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration)

 Related Topics  [image]  Example

Creates an invisible area (hot spot) in a dialog box that closes the dialog box when clicked.  After DialogShow or DialogLoad, a hot spot can be added to a dialog created with the Dialog Editor.

Other responses are possible when you use DialogAddHotSpot with a callback function (see DialogShow).

To create a hot spot within a frame (see DialogAddFrame), overlap size and position parameters.

Parameters

Dialog: String

The name or number of the dialog box to contain the hot spot control (see DialogDefine).

Control: String

A name or number that identifies the hot spot control (the "Named region" of a control created with the Dialog Editor).  The Control value is returned in the implicit variable MacroDialogResult (see DialogAddPushButton or DialogDefine) if the user chooses the hot spot to dismiss the dialog box.

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the hot spot control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the hot spot control.

Width: Numeric

Width of the hot spot control in dialog units.

Height: Numeric

Height of the hot spot control in dialog units.

Style: Enumeration (optional)

Hot spot styles.

Click! Single click closes dialog box.

DblClick! Double click closes dialog box.


DialogAddIcon

DialogAddIcon (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; IconName: String; Instance: Numeric)

 Related Topics  [image]  Example

Adds an icon to a dialog box.  After DialogShow or DialogLoad, an icon can be added to a dialog created with the Dialog Editor.

Parameters

Dialog: String

The name or number of the dialog box to contain the icon control (see DialogDefine).

Control: String

A name or number that identifies the icon control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the icon control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the icon control.

Width: Numeric

Width of the icon control in dialog units.

Height: Numeric

Height of the icon control in dialog units.

IconName: String

The name of an icon in a DLL.  If an icon is identified by a number, precede the number with a pound sign (#).  For example, "#160".

Instance: Numeric (optional)

The handle of the DLL that contains the icon.  The PerfectFit* default is 0.  DLLLoad returns the handle in a variable.


DialogAddListBox

DialogAddListBox (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration; MacroVar: Variable)

 Related Topics  [image]  Example

Adds a list box control to a dialog box.  After DialogShow or DialogLoad, a list box can be added to a dialog created with the Dialog Editor.

The item you choose is returned in MacroVar (see MacroVar parameter).  Use DialogAddListItem to create list box items.

Parameters

Dialog: String

The name or number of the dialog box to contain the list box control (see DialogDefine).

Control: String

A name or number that identifies the list box control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the list box control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the list box control.

Width: Numeric

Width of the list box control in dialog units.

Height: Numeric

Height of the list box control in dialog units.

Style: Enumeration (optional)

List box control styles.  Type | between enumerations to combine styles.

Unsorted! Items listed in order defined.  Type a keyboard character to give the input focus to the first item that begins with that character.  A vertical scrollbar automatically appears when needed.  See DialogAddListItem.

Sorted! Default.  Items sorted alphabetically.  Type a keyboard character to give the input focus to the first item that begins with that character.  See DialogAddListItem.

NameSearch! Item search allowed.  Begin typing the name of an item to select.  An edit control is displayed above the list box, and the input focus is given to the item that most closely matches the characters you type.

MultiColumn! Items automatically roll into other columns as needed.  A horizontal scrollbar automatically appears when needed.  Column width is set by Windows*.

WPChars! Non-keyboard characters allowed in a list item.  See DialogAddListItem.

ExtendedSelection! Click an item, press shift key and select another item.  Selects all items in between.

MultipleSelection! Click items to select or deselect.

Checkboxes! List box items have check boxes.  Use with WPChars!.

Examples

Sort! | NameSearch!

Explanation: Name search allowed on a sorted list box.  A vertical scrollbar automatically appears when needed.

Sort! | NameSearch! | MultiColumn!

Explanation: Name search allowed on a sorted list box.  Items automatically roll in other columns as needed.  A horizontal scrollbar automatically appears when needed.

MacroVar: Variable

The selected list box item is returned in this variable.  An item can be assigned to MacroVar before the dialog is displayed.  The item is highlighted (selected) if it exists in the control's list of items.  Otherwise, it is ignored.


DialogAddListItem

DialogAddListItem (Dialog: String; Control: String; Item: String)

 Related Topics  [image]  Example

Creates a list item for DialogAddComboBox, DialogAddListBox, or DialogAddPopupButton.  After DialogShow, a list item can be added to a list box in a dialog created with the Dialog Editor.

Parameters

Dialog: String

The name or number of the dialog box to contain the list item (see DialogDefine).

Control: String

The name or number of the control to contain the list item (the "Named region" of a control created with the Dialog Editor).

Item: String

A list box item.  Use NToC programming command to include non-keyboard characters in a list item for DialogAddComboBox and DialogAddListBox, when the WPChars! style is set.  For example,

DialogAddListItem(1000; 100; "Sample" + NToC(5;10))


DialogAddPopupButton

DialogAddPopupButton (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; MacroVar: Variable)

 Related Topics  [image]  Example

Adds a popup button control to a dialog box.  After DialogShow or DialogLoad, a popup button can be added to a dialog created with the Dialog Editor.

Use DialogAddListItem to create items for a popup button control.  Unless MacroVar is assigned a default item, the item displayed on the popup button is the first item created by DialogAddListItem.

Parameters

Dialog: String

The name or number of the dialog box to contain the popup button control (see DialogDefine).

Control: String

A name or number that identifies the popup button control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the popup button control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the popup button control.

Width: Numeric

Width of the popup button control in dialog units.

Height: Numeric

Height of the popup button control in dialog units.

MacroVar: Variable

The item displayed on the popup button is returned in this variable.  An item can be assigned to MacroVar before the dialog is displayed.


DialogAddProgress

DialogAddProgress (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric)

  Example

Adds a progress indicator to a dialog box.  After DialogShow or DialogLoad, a progress indicator control can be added to a dialog created with the Dialog Editor.  See RegionSetProgressPercent.

Parameters

Dialog: String

The name or number of the dialog box to contain the progress indicator control (see DialogDefine).

Control: String

A name or number that identifies the progress indicator control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the progress indicator.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the progress indicator.

Width: Numeric

Width of the progress indicator in dialog units.

Height: Numeric

Height of the progress indicator in dialog units.


DialogAddPushButton

DialogAddPushButton (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration; ButtonText: String)

 Related Topics  [image]  Example

Adds a push button to a dialog box.  After DialogShow or DialogLoad, a push button can be added to a dialog created with the Dialog Editor.

When you choose a user-defined push button or hot spot, the Control parameter value of the button or hot spot is returned in the implicit variable MacroDialogResult (see DialogDefine).  Other controls return the following Control parameter values: 1 for OK, 2 for Cancel, 2 for Close (system menu box), 2 if you double-click the system menu box, 2 if you press Alt+F4 or Esc.

Parameters

Dialog: String

A name or number that matches the Dialog parameter of the dialog box to contain the push button control (see DialogDefine).

Control: String

A name or number that identifies the push button control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the push button control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the push button control.

Width: Numeric

Width of the push button control in dialog units.

Height: Numeric

Height of the push button control in dialog units.

Style: Enumeration (optional)

Push button styles.

NonDefaultBttn! Creates a push button.

DefaultBttn! Creates a default push button, with a heavy black border, that dismisses the dialog box.  Press Enter to choose the default button.  If Enter2HRtn! style is specified in DialogDefine, pressing Enter in a multiline edit control produces a hard return rather than the default button action.

OKBttn! Creates a push button with ID OK style.

CancelBttn! Creates a push button with ID Cancel style.

HelpBttn! Creates a Help push button.

ButtonText: String

The text displayed on the push button.


DialogAddRadioButton

DialogAddRadioButton (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; ButtonText: String; MacroVar: Variable; Style: Enumeration)

 Related Topics  [image]  Example

Adds a radio button to a dialog box.  After DialogShow or DialogLoad, a radio button can be added to a dialog created with the Dialog Editor.

Radio buttons represent mutually exclusive choices.  Selecting one radio button deselects another.  Group them together by a control such as a group box or horizontal or vertical line.  For multiple selections, see DialogAddCheckBox.

Parameters

Dialog: String

The name or number of the dialog box to contain the radio button control (see DialogDefine).

Control: String

A name or number that identifies the radio button control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the radio button control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the radio button control.

Width: Numeric

Width of the radio button control in dialog units.

Height: Numeric

Height of the radio button control in dialog units.

ButtonText: String

The text displayed by the radio button (see Styles).

MacroVar: Variable

1 is returned in this variable if the radio button is selected, and 0 if not.  The default value is 0.  If MacroVar is assigned a value greater than 0 before the macro compiles, the radio button is automatically selected.

Style: Enumeration (optional)

Radio! Button not checked.  Use RegionSetCheck in a callback function to check or uncheck.  See DialogShow.

RadioAuto! Normal radio button.

RadioLeft! Positions text to the left of the radio button.


DialogAddScrollBar

DialogAddScrollBar (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration; MacroVar: Variable; Minimum: Numeric; Maximum: Numeric; Step: Numeric)

 Related Topics  [image]  Example

Adds a horizontal or vertical scroll bar to a dialog box.  After DialogShow or DialogLoad, a scroll bar can be added to a dialog created with the Dialog Editor.

A callback function (see DialogShow) can receive Windows* WM_HSCROLL and WM_VSCROLL messages from DialogAddScrollBar.

For more information, see Windows 95 documentation.

Parameters

Dialog: String

The name or number of the dialog box to contain the scroll bar control (see DialogDefine).

Control: String

A name or number that identifies the scroll bar control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the scroll bar control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the scroll bar control.

Width: Numeric

Width of the scroll bar control in dialog units (0 for vertical scroll bar).

Height: Numeric

Height of the scroll bar control in dialog units (0 for horizontal scroll bar).

Style: Enumeration

Scroll bar thumb position and type styles.  Type | between enumerations to combine styles.  Not all combinations are possible.

Left!

Top!

Right!

Bottom!

VScroll! Create a vertical scroll bar.

HScroll! Create a horizontal scroll bar.

Examples

Left! | VScroll!

Explanation: Creates a standard size vertical scroll control on the left side of the Window defined by Left, Top, Width, and Height.

Right! | HScroll!

Explanation: Creates a standard size vertical scroll control on the right side of the Window defined by Left, Top, Width, and Height.

VScroll!

A vertical scroll control that occupies the entire Window defined by Left, Top, Width, and Height.

HScroll! works the same as VScroll!, but uses the Top! and Bottom! styles.

MacroVar: Variable

The position of the thumb is returned in this variable.  To pre-select a thumb position, initialize MacroVar to the desired position. Default: the minimum position.

Minimum: Numeric

The minimum thumb position (default).  If the maximum position is 6 and the minimum position is 1, there are six positions on the scroll bar.  If the maximum position is 6 and the minimum position is 2, there are five positions on the scroll bar.

Maximum: Numeric

The maximum thumb position.  See Minimum parameter.

Step: Numeric


DialogAddText

DialogAddText (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration; Text: String)

 Related Topics  [image]  Example

Displays a line of text in a dialog box.  After DialogShow or DialogLoad, text can be added to a dialog created with the Dialog Editor.

Parameters

Dialog: String

The name or number of the dialog box to contain the text control (see DialogDefine).

Control: String

A name or number that identifies the text control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the text control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the text control.

Width: Numeric

Width of the text control in dialog units.  This parameter determines how much horizontal space the control occupies, not the text width which is fixed by the system.

Height: Numeric

Height of the text control in dialog units.  This parameter determines how much vertical space the control occupies, not the text height which is fixed by the system.

Style: Enumeration (optional)

Text control styles.  Type | between enumerations to combine styles.  Not all combinations are possible.

Left! Left justified.

Right! Right justified unless WPChars! style is set.

Center! Centered inside Width parameter value unless WPChars! style is set.

RecessBox! Recessed background.

ShadowBox! Shadowed background.

WPChars! Non-keyboard characters allowed.  See Text parameter.

Multiline! Text wraps if WPChars! is set.

Filename! Ellipsis truncate path and filename to length of Width parameter.

NoPrefix! The & character is not interpreted as an accelerator prefix (displays in the text).

Examples

Left! | RecessBox!

Explanation: Text is left justified in a recess box.

Center! | ShadowBox!

Explanation: Text is centered in a shadow box.

Text: String

Text to display on the dialog box.  Use NToC programming command to display a non-keyboard character.  For example,

Text: "A bullet character " + NToC(4; 0)


DialogAddViewer

DialogAddViewer (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Filename: String)

 Related Topics  [image]  Example

Adds a read-only edit control to a dialog box.  The edit control displays a file.  After DialogShow or DialogLoad, a viewer can be added to a dialog created with the Dialog Editor.

The edit control has horizontal and vertical scroll bars.  The horizontal scroll bar contains text that identifies the text file format and indicates whether text wraps.

Parameters

Dialog: String

The name or number of the dialog box to contain the viewer control (see DialogDefine).

Control: String

A name or number that identifies the viewer control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the viewer control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the viewer control.

Width: Numeric

Width of the viewer control in dialog units.

Height: Numeric

Height of the viewer control in dialog units.

Filename: String (optional)

The path and name of a file to view.


DialogAddVLine

DialogAddVLine (Dialog: String; Control: String; Left: Numeric; Top: Numeric; Length: Numeric)

 Related Topics  [image]  Example

Adds a vertical line to a dialog box.  After DialogShow or DialogLoad, a vertical line can be added to a dialog created with the Dialog Editor.

Parameters

Dialog: String

The name or number of the dialog box to contain the vertical line control (see DialogDefine).

Control: String

A name or number that identifies the vertical line control (the "Named region" of a control created with the Dialog Editor).

Left: Numeric

Number of dialog units from the left side of the dialog box to the left side of the vertical line control.

Top: Numeric

Number of dialog units from the top of the dialog box to the top of the vertical line control.

Length: Numeric

Length of the vertical line in dialog units.


DialogDefine

DialogDefine (Dialog: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric; Style: Enumeration; Caption: String)

 Related Topics  [image]  Example

Assembles dialog data in memory.  Use DialogShow to create and display the dialog box.

Region commands to a dialog or dialog control work only after DialogShow or DialogLoad.  DialogHandle works only after DialogLoad or Dialogshow.

Dialog names are limited to 25 characters.

Dialog sizes do not include caption and border space (in Windows* 95, dialog captions and borders can be sized by the user).

The value of the control that dismisses a dialog box is returned in an implicit variable named MacroDialogResult: 1 for OK, 2 for Cancel, 2 for Close (system menu box), 2 if you double-click the system menu box, 2 if you press Alt+F4 or Esc.  It also returns the value of the Control parameter of a user-defined push button or hot spot (see DialogAddPushButton, DialogAddHotSpot).

MacroDialogResult is replaced or destroyed when you close a dialog box or call DialogDestroy.  To save its value, assign it to a variable.  For example, vResult := MacroDialogResult.

Dialog boxes are positioned and sized in dialog units.  A vertical unit equals 1/8 of the font height, and a horizontal unit equals 1/4 of the font width.

Parameters

Dialog: String

A name or number that identifies the dialog box.  This name or number is used by DialogShow and by DIALOGADD commands.

Left: Numeric

Number of dialog units from the left side of the screen to the left side of the dialog box.  When used with Percent! (see Style parameter), this number is a percentage of the screen width minus the width of the dialog box.

Top: Numeric

Number of dialog units from the top of the screen to the top of the dialog box.  When used with Percent! (see Style parameter), this number is a percentage of the screen height minus the height of the dialog box.

Width: Numeric

Width of the dialog box in dialog units.

Height: Numeric

Height of the dialog box in dialog units.

Style: Enumeration

Dialog box styles.  Type | between enumerations to combine styles.  Not all combinations are possible.

OK! Create an OK button.

Cancel! Create a Cancel button.

Percent! Sets Top and Left parameters to a percentage of the screen width or height minus the width or height of the dialog box.  Use 50 to display the dialog box in the center of the screen.

NoFrame! Create a dialog box without a frame.  Style has no effect in Windows 95.

Sizeable! Resizing of dialog box allowed.

NoTitle! Remove the caption (title) bar.

Modeless! Dialog box can lose input focus without closing.  The WordPerfect* command, InhibitInput, must be Off!.  Default is modal dialog box.

Enter2HRtn! Press Enter in a multiline edit control (see DialogAddEditBox) to move the insertion point to the next line.  This does not cause the default button action (see DialogAddPushButton).

NoCloseBox!

Example

OK! | Percent! | NoTitle!

Explanation: Creates a modal dialog box without a title, and positions it in the center of the screen.

Caption: String

The text displayed in the caption (title) bar.


DialogDestroy

DialogDestroy (Dialog: String)

 Related Topics  [image]  Example

Removes an old-style dialog box from memory.

Discussion

A dialog created with the Dialog Editor, without a callback (see DialogShow), is removed from memory when any button is pushed.  Subsequent calls to the dialog create an error (macro system no longer knows anything about the dialog). For example, DialogDismiss in

DialogShow ("Dialog1"; "PerfectScript")

DialogDismiss ("Dialog1"; "OKBttn")

creates an error when OK is pressed (Dialog1).

The next example, which includes a callback function, displays the dialog, continuously executes instructions (callback function "CallHere"), is dismissed (hidden), and finally destroyed.

DialogShow ("Dialog1"; "PerfectScript"; CallHere)

DialogDismiss ("Dialog1"; "OKBttn")

DialogDestroy ("Dialog1")

Quit

Label (CallHere)

...other statements...

Return

Parameters

Dialog: String

The name or number of a dialog box to destroy (see DialogDefine).


DialogDismiss

DialogDismiss (Dialog: String; Control: String)

 Related Topics  [image]  Example

Hides a dialog box.  Use DialogShow to display a hidden dialog box.

Discussion

A dialog created with the Dialog Editor, without a callback (see DialogShow), is removed from memory when any button is pushed.  Subsequent calls to the dialog create an error (macro system no longer knows anything about the dialog). For example, DialogDismiss in

DialogShow ("Dialog1"; "PerfectScript")

DialogDismiss ("Dialog1"; "OKBttn")

creates an error when OK is pressed (Dialog1).

The next example, which includes a callback function, displays the dialog, continuously executes instructions (callback function "CallHere"), is dismissed (hidden), and finally destroyed.

DialogShow ("Dialog1"; "PerfectScript"; CallHere)

DialogDismiss ("Dialog1"; "OKBttn")

DialogDestroy ("Dialog1")

Quit

Label (CallHere)

...other statements...

Return

Parameters

Dialog: String

The name or number of the dialog box to hide (see DialogShow).

Control: String

OKBttn or 1 for OK, CancelBttn or 2 for Cancel, or the control value of a user-defined push button or hot spot.  CancelBttn cancels value assignments to control return variables.  For example, an edit control does not return the text entered in the edit box.  The value of Control is returned in MacroDialogResult as OKBttn, CancelBttn, or the control value of another push button or hot spot.


DialogHandle

Numeric := DialogHandle (Dialog: String; Control: String)

 Related Topics  [image]  Example

Returns the handle of a dialog box or dialog box control.  It does not work until after DialogLoad or DialogShow.

Return Value

The handle of a dialog box or dialog box control.

Parameters

Dialog: String

The name or number of a dialog box (see DialogDefine).

Control: String (optional)

The name or number of a dialog box control (see Control parameter of any dialog control).  If you omit this parameter, the handle of the dialog box is returned in MacroVar.


DialogLoad

Numeric := DialogLoad (Dialog: String; Parent: String)

  Example

Loads a dialog in memory without displaying it.  You can use Region commands on a dialog box that has been loaded.  See also DialogShow and Discussion under DialogDismiss.

Return Value

The window handle (HWND) if successful, or NULL if not.

Parameters

Dialog: String

The name or number of a dialog box (see DialogDefine).

Parent: String (optional)

The name of the parent window, such as "PerfectScript," or "WordPerfect" for WordPerfect 7 for Windows.


DialogSave

Boolean := DialogSave (Dialog: String; SaveAsName: String)

Saves specified dialog in the current macro file.

Return Value

True (1) if saved successfully, or False (0) if not.

Parameters

Dialog: String

The name or number of a dialog box (see DialogDefine).

SaveAsName: String (optional)

Name to save the dialog under.  If missing, the dialog is saved under the current dialog name.


DialogSetProperties

DialogSetProperties (Dialog: String; FontName: String; FontSize: Measurement; ClassName: String; HelpFile: String; HelpString: String)

  Example

Specifies additional properties for a dialog box.

This command should only be used on dialogs created with DialogDefine.  It should be called immediately after DialogDefine.

Example:

DialogDefine(....)

DialogSetProperties(....)

Parameters

Dialog: String

The name or number of a dialog box (see DialogDefine).

FontName: String (optional)

The font that dialog text will appear in.

FontSize: Measurement (optional)

Specify the font size using a measurement type, such as 12p.  If the measurement type specifier is not used, default units is assumed.  See DefaultUnits.

ClassName: String (optional)

Specifies another class name (see Dialog Editor).

HelpFile: String (optional)

Name of the help file associated with the dialog.

HelpString: String (optional)

The part of the help file to come up along with the dialog.


DialogShow

Numeric := DialogShow (Dialog: String; Parent: String; Callback: Label; Focus: String)

 Related Topics  [image]  Example

Displays a dialog box, and, optionally, identifies a callback function.

Use DialogDismiss to hide a dialog box.  See Discussion under DialogDismiss or DialogDestroy.

A callback function enables a macro to respond immediately and in specific ways to events such as selecting a radio button or check box, without waiting until the dialog box is dismissed.  Without a callback function, user input is acted upon only after the dialog box is dismissed and the macro resumes execution.

To create a callback function, use the Label parameter of DialogShow, and a loop statement after DialogShow.  For example,

DialogShow(1000; "WordPerfect"; Msgs)

CallbackWait

Label(Msgs)

... other statements ...

Return

The value of the control that dismisses a dialog box is returned in an implicit variable named MacroDialogResult: 1 for OK, 2 for Cancel, 2 for Close (system menu box), 2 if you double-click the system menu box, 2 if you press Alt+F4, or the value of the Control parameter of a user-defined push button or hot spot (see DialogAddPushButton, DialogAddHotSpot).

If DialogShow is used with Dialog commands, such as DialogDefine and DialogAddEitBox (old-style dialog box), the first control that can return a value has the input focus.

Parameters

Dialog: String

The name of a dialog box to display (see DialogDefine for old-style dialog boxes).

Parent: String (optional)

The name of the parent window, such as "WordPerfect" for WordPerfect* 7 for Windows.  The parameter is required by new-style dialog boxes (see WordPerfect for Windows, PerfectScript Help), and can be used by old-style dialog boxes.

Callback: Label (optional)

Identifies a callback function (Label to call) when the dialog box becomes active, or the user

Chooses Close from the system menu.

Presses Alt+F4.

Double-clicks the system menu box.

Chooses a push button, radio button, check box, hot spot, or scroll bar control.

The Windows* messages are:

WM_ACTIVATE

WM_COMMAND

WM_DESTROY

WM_HSCROLL

WM_INITDIALOG

WM_SYSCOMMAND

WM_VSCROLL

Note

For more information, see Callback Data Description.

Focus: String

Specifies the control to receive the initial focus.


Dimensions

Dimensions (<VariableName> Variable; <IndexNumber> Numeric)

  Example

Returns dimension information about an array variable.

Parameters

VariableName: Variable

Array variable.

IndexNumber: Numeric (optional)

If not specified, the number of array dimensions is returned. Use 0 to return the total number of array elements.  Use a dimension number to return the number of elements in that dimension.  Given the following declaration,

Declare array[4; 2; 5]

Dimensions returns the following values:

3 Dimension (array[]) // number of dimensions

40 Dimension (array[]; 0) // total elements

4 Dimension (array[]; 1) // elements in dimension 1

2 Dimension (array[]; 2) // elements in dimension 2

5 Dimension (array[]; 3) // elements in dimension 3

0 Dimension (array[]; 4) // out of range

0 Dimension (c) // not an array

0 Dimension (b[]) // doesn't exist


Discard

Discard ({<VariableName> Variable})

 Related Topics  [image]  Example

Removes Local, Global, and Persist variables from memory, in that order.

Discard does not specify a variable table.  If a variable by the same name exists in all three tables, call Discard three times.

While(Exists(VariableName))

Discard(VariableName)

EndWhile

Parameters

<VariableName> Variable

Begins with a letter and can include any other combination of letters or numbers.  Separate multiple variables with a semicolon.


DIV

Numeric := Numeric DIV Numeric

 Related Topics

Returns the integer quotient of two whole numbers.  See Arithmetic Operators.


DLLCall

DLLCall (<ModuleInstance> Numeric; <FunctionName> String; <ReturnVariable> Variable; <ReturnType> Enumeration; {<Parameter> Any})

 Related Topics

Calls a function in a Dynamic Link Library (DLL).

Note

Do not use this command unless you are familiar with Windows* programming.  Incorrect DLL calls can damage files and/or reset your computer.  Macros using DLLCalls written for Windows 3.x must be rewritten for Windows 95.

Parameters

<ModuleInstance> Numeric

A DLL handle.  DLLLoad returns the handle in a variable.

<FunctionName> String

A function name.  See DLL documentation for function names.

<ReturnVariable> Variable

The DLL function may return a value in this variable.  The ReturnType parameter defines the expected data type.

<ReturnType> Enumeration

The data type to return (see ReturnVariable parameter).

Data types and descriptions

AnsiString! (Windows type LPSTR)

Bool! (Windows type BOOL)

DWord! (Windows type DWord)

Integer! (Windows type LONG)

OemString! (Windows type LPSTR)

Real! (Microsoft* C type double)

String! (Windows type LPSTR)

Word! (Windows type WORD)

WPString! (WordPerfect 7 wordstring)

Void! (Nothing)

ReturnType must match the data type returned in ReturnVariable (see DLL function documentation for return types).  If it does not, an Unrecoverable Application Error or system crash may result.

{<Parameter> Any}

Parameter information passed to a DLL function, enclosed in braces and separated by a semicolon.  The type of information depends on the function being called (see DLL function documentation for parameter values to pass).  Use LoWord specifier to pass byte data.

Data types and descriptions

Integer (LONG or DWord)

String (FAR pointer to an ANSI string)

Boolean (BOOL)

Real (Microsoft c-type double)

AnsiString(String) (FAR pointer to an ANSI string)

OemString(String) (FAR pointer to an OEM string)

WPString(String) (FAR pointer to a WP 6.0 word string)

ADDRESS(Integer) (LPDWord)

ADDRESS(DWord(Integer))

ADDRESS(Boolean) (BOOL FAR*)

ADDRESS(String) (FAR pointer to an ANSI string)

ADDRESS(AnsiString(String)) (FAR pointer to an ANSI string)

ADDRESS(OemString(String)) (FAR pointer to OEM string)

ADDRESS(WPString(String)) (FAR pointer to a WP 6.0 word string.)

ADDRESS(Real) (FAR pointer to a Microsoft C-type double)

ADDRESS(Real(Real)) (FAR pointer to a Microsoft C-type double)


DLLCall Prototype

DLLCall Prototype <Name> Label (<ModuleFileName> String; <FunctionName> String; <ReturnType> Enumeration; {<Parameter> Any})

 Related Topics

Defines the calling format of a DLL routine (see example).

DLLCall Prototype accepts only literal strings (no expressions), and must occur before calling a DLL function.  The DLL library is loaded and freed each time the DLL function is called.

DLLCall Prototype makes a macro easier to read and provides safer DLL calls (routines can be called only as defined).

Note

Do not use this command unless you are familiar with Windows* programming.  Incorrect DLL calls can damage files and/or reset your computer.

Parameters

<Name> Label

The name used to call the DLL function.

<ModuleFileName> String

DLL library file containing the DLL function.

<FunctionName> String

A function name.  See DLL documentation for function names.

<ReturnType> Enumeration

The data type returned by the DLL function.  See DLLCall.

AnsiString!

Bool!

DWord!

Integer!

OemString!

Real!

String!

Word!

WPString!

Void!

<Parameter> Any

Parameter information passed to a DLL function, enclosed in braces and separated by a semicolon.  The type of information depends on the function being called (see DLL function documentation for parameter values to pass).  See DLLCall.


DLLFree

DLLFree (<ModuleInstance> Numeric)

 Related Topics

Removes a dynamic link library (DLL) from memory.

If you use DLL commands incorrectly, they can damage files and/or reset your computer.

Parameters

<ModuleInstance> Numeric

A DLL handle.  DLLLoad returns the handle in a variable.


DLLLoad

Numeric := DLLLoad (Filename: String)

 Related Topics

Loads a dynamic link library (DLL) into memory.

You should respond to error values with code similar to the following (see ModuleInstance parameter):

DLLLoad(vResult; Filename)

Switch(vResult)

CaseOF 0: ...statement block...

CaseOF 2: ...statement block...

EndSwitch

Note

If you use DLL commands incorrectly, they can damage files and/or reset your computer.

Parameters

<ModuleInstance> Numeric

A DLL handle if the DLL successfully loads, or an error value.  For example, 31 means a General Failure occurred; 1157 means the DLL was not found.

See Windows* 95 documentation for more information.

Filename: String

A DLL path and filename.


DoesDialogExist

Boolean := DoesDialogExist (Dialog: String)

  Example

Looks for a dialog in the current macro, then through the Use file list for the current macro.  See Use.

Return Value

True (1) if the dialog is found, False (0) if not.

Parameters

Dialog: String

The name or number of a dialog box (see DialogDefine).


DoesDirectoryExist

Boolean := DoesDirectoryExist (DirectoryName: String)

 Related Topics  [image]  Example

Returns True if a directory exists, False if not.

Return Value

True/False.

Parameters

DirectoryName: String

Include full path.


DoesFileExist

Boolean := DoesFileExist (Filename: String)

 Related Topics  [image]  Example

Returns True if a file exists, False if not.

Return Value

True/False.

Parameters

Filename: String

Include full path.


DWord

Numeric := DWord (<Value> Numeric)

Passes value as a DWord (DLL call in-line parameter function).  DWord or double word is an unsigned long integer.  See DLLCall.


Else

All statements between Else and Endif are executed when the If expression is False.  See If.


EndApp

EndApp (<ProductPrefix> String)

 Related Topics  [image]  Example

Identifies, for the compiler, an application that is no longer used in a macro (see Application).

EndApp is a non-executable statement that can occur anywhere in a macro.  After EndApp, a product command to the application specified by EndApp creates a compile-time syntax error.

Parameters

<ProductPrefix> String

A unique identifier that matches the ProductPrefix parameter of an Application statement.


EndFor

Closes a For control loop.  See For.


EndFunc

Closes a Function statement.  See Function.


EndFunction

Closes a Function statement.  See Function.


EndIf

Closes an If control statement.  See If.


EndIfPlatform

EndIfPlatform (<PlatformID> Enumeration)

Closes an IfPlatform conditional compile statement.  See IfPlatform.

The parameter is optional and ignored. Its only purpose is to document what it goes with.


EndProc

Closes a Procedure statement.  See Procedure.


EndProcedure

Closes a Procedure statement.  See Procedure.


EndPrompt

EndPrompt()

Terminates the current Prompt.  See Prompt.


EndSwitch

Closes a Switch control statement.  See Switch.


EndWhile

Closes a While control loop.  See While.


EnvVariableGet

String := EnvVariableGet (EnvVariableName: String; EnvType: Enumeration)

Returns the value of an environment variable.

Parameters

EnvVariableName: String

Environment variable name.

EnvType: Enumeration (optional)

Type of variable. Default: DOS!

DOS!


EnvVariableSet

EnvVariableSet (EnvVariableName: String; Value: String; EnvType: Enumeration)

Set the value of an environment variable, or delete it.

Parameters

EnvVariableName: String

Environment variable name.

Value: String (optional)

Value to assign to the variable.  If missing, the environment variable is deleted.

EnvType: Enumeration (optional)

Type of variable. Default: DOS!

DOS!


Error

Enumeration := Error (State: Enumeration)

 Related Topics  [image]  Example

Determines how a macro responds to an Error condition.

Create an Error condition with Assert(ErrorCondition!).

Return Value

Off! Previous state was Off!

On! Previous state was On!

Parameters

State: Enumeration (optional)

Specifies the Error state.  The default is Error(On!).  If missing, the current state is returned without changing it.

Off! Ignores an Error condition.

On! Stop a macro unless preceded by OnError, which directs macro execution to a specified Label.


ErrorNumber

Numeric := ErrorNumber

Returns the error value of a Cancel, Error, or Not Found condition.  See Assert and the ASSERT.WCM example (line 44).


Exists

Enumeration or Boolean:= Exists (<VariableName> Variable; <Pool> Enumeration)

 Related Topics  [image]  Example

Determines if a variable exists.

To exist, a variable must be declared and initialized.  Given that variable w is declared and not initialized, and that Local x is initialized to 5, Global y to 10, and Persist z to 15, the following statements are valid:

vNoInit := Exists(w)

Result: vNoInit equals 0

vLocal := Exists(x)

Result: vLocal equals 1

vGlobal := Exists(y)

Result: vGlobal equals 2

vPersist := Exists(z)

Result: vPersist = 3

Examples in shorthand notation

If(Exists(vLocal))

Beep

EndIf

Explanation: Computer beeps because Exists returns a value greater than 0.

If(Exists(vLocal) = 3)

Beep

EndIf

Explanation: The computer does not beep because Exists returns 1.  (vLocal is a Local variable, not a Persist variable.)

Return Value

If Pool is left off, the values are:

NotFound! Does not exist

Local!

Global!

Persist!

If Pool is specified, the return value is boolean.

Parameters

<VariableName> Variable

A variable declared as Local, Global, or Persist.  Variables begin with a letter and can include any other combination of letters or numbers.

<Pool> Enumeration (optional)

If missing, the command returns the Pool it is in.  If provided, the command returns a boolean indicating whether it is in the specified Pool.

Local!

Global!

Persist!


ExponentPart

Numeric := ExponentPart (Value: Numeric)

Returns the exponent portion of a numeric value.

For example, the exponent of 3.2e18 is 18.

Parameters

Value: Numeric

Fractional number (return exponent part of).


Factorial

Numeric := Factorial (Nth: Numeric)

Returns the Nth factorial (show first five or six values in the series).

Parameters

Nth: Numeric

Compute the Factorial of this value.


Fibonacci

Numeric := Fibonacci (Nth: Numeric)

Returns the Nth term in the Fibonacci sequence (show first five or six values in the series).

Parameters

Nth: Numeric

Term of the Fibonacci sequence to return.


FileError

Numeric := FileError()

 Related Topics  [image]  Example

Returns the error associated with the last file command.

Return Value

A number greater than 0 (last file error), -1 (unknown error), or 0 (no error).  Error numbers have loword and hiword values.  The loword contains an error code generated by WordPerfect's I/O routines, described in the WordPerfect* for Windows SDK (WError.H file).  The hiword contains a Windows specific error value, described in the Microsoft Windows* SDK.


FileFind

String := FileFind (Filename: String; Attributes: Enumeration; Context: Numeric)

 Related Topics  [image]  Example

Finds a file that matches user-defined search criteria (filename and DOS attributes).

Return Value

Filename, or an empty filename if no match is found.

Parameters

Filename: String (optional)

Include full path.  If missing, the next matching file is found (see Context below).

Attributes: Enumeration (optional)

Default: Normal!

Normal!

ReadOnly!

Hidden!

System!

Label!

Directory!

Archived!

Context: Numeric (optional)

User-defined number which identifies the search.  Default: 0.  To find the next file to match the search criteria, call FileFind with an empty filename.  For example,

vFilename = FileFind (Filename: "*.WPD"; Attributes: Normal!; Context: 1)

finds the first occurrence of a file with a WPD extension.  The following statement finds the next file to match the same search criteria:

vFilename = FileFind (Filename: ""; Context: 1)

Use different Context values to perform multiple searches simultaneously.  If you perform more than one search before the macro ends, you can repeat any search by using the appropriate Context value.  The subsequent search begins where it left off.


FileIsEOF

Boolean := FileIsEOF (FileID: Numeric)

 Related Topics  [image]  Example

Returns True if the insertion point is at the end of a file, or False if not.

The access mode must be Read! (see OpenFile).

Return Value

True/False.

Parameters

FileID: Numeric

See OpenFile.


FileNameDialog

String := FileNameDialog (StyleOptions: Enumeration; CaptionText: String; ButtonText: String; InitialFolder: String; InitialFileName: String; FileTemplate: String; RecentFiles: String)

Displays the Open or Save As dialog.

Return Value

The name of the file to open or save, or "" if Cancel is pressed.

Parameters

StyleOptions: Enumeration

Specifies type of dialog to open and options associated with the dialog.  Type | between enumerations to combine styles.  For example: OpenDialog! | FileMustExist!.

OpenDialog! Display the Open dialog.

SaveAsDialog! Display the Save As dialog.

FileMustExist! Use with OpenDialog!.  File selected for Open must exist.

PromptOnReplace! Use with SaveAsDialog!.  If file already exists, prompt displayed asking whether the file should be replaced.

CaptionText: String (optional)

Text displayed in the caption bar.  It missing or "", Open or Save As is displayed.

ButtonText: String (optional)

Text displayed on the Open button.  If missing or "", Open is displayed.

InitialFolder: String (optional)

Initial folder to display.  If missing or "", the current folder is displayed.

InitialFileName: String (optional)

Initial filename to display.  If missing or "", FileTemplate is displayed.

FileTemplate: String (optional)

Template for the files to display.  If missing or "", *.* files are displayed.

RecentFiles: String (optional)

Name of registry subkey (HKEY_CURRENT_USER\Software) containing a list of up to fifteen files selected in dialog.  If missing, no history is given.


FilePosition

Numeric := FilePosition (FileID: Numeric; NewPosition: Numeric; PositionFrom: Enumeration)

 Related Topics  [image]  Example

Returns the current marker position or sets a new position.

A user can preallocate file size by setting the position marker past the end-of-file marker.

Return Value

Position of old position marker, or negative number if error occurs.

Parameters

FileID: Numeric

See OpenFile.

NewPosition: Numeric (optional)

Number of bytes to move position marker.  Default: 0.

PositionFrom: Enumeration (optional)

Move position marker relative to one of the following positions.  Default: FromBeginning!

FromBeginning!

FromCurrentPosition!

FromEnd!


FileRead

Numeric := FileRead (FileID: Numeric; Data: Variable)

 Related Topics  [image]  Example

Reads text data from an open file.

Return Value

Number of bytes read, or negative number if error occurs.

Parameters

FileID: Numeric

See OpenFile.

Data: Variable

Starting from the position marker, one line of data is converted to a WP character string and returned in this variable.


FileSize

Numeric := FileSize (Filename: String)

 Related Topics  [image]  Example

Returns a file's size in bytes.

Return Value

File size in bytes, or negative number if error occurs.

Parameters

Filename: String

Include full path.


FileTruncate

Numeric := FileTruncate (FileID: Numeric)

 Related Topics  [image]  Example

Removes all text data after the position marker (see FilePosition).

Return Value

Truncated file size (bytes) if successful, or negative number if error occurs.

Parameters

FileID: Numeric

See OpenFile.


FileWrite

Numeric := FileWrite (FileID: Numeric; Data: String; NewLine: Enumeration; {ParameterData: String})

 Related Topics  [image]  Example

Writes text data to a file.

Return Value

Number of bytes written, or a negative number if error occurs.

Parameters

FileID: Numeric

See OpenFile.

Data: String

Text data is converted to the type specified when the file is opened.  A caret (^) followed by a number is replaced by the corresponding character string in the ParameterData parameter.  To write a caret, use two carets (^^).

NewLine: Enumeration

Default: NoNewLine!

NoNewLine! Inserts an end-of-line marker.

NewLine!

ParameterData: String (optional)

Text data inserted in the data string (see Data parameter).  Up to 10 strings separated by semicolons are allowed.  Numbering begins with 0.  For example,

FileWrite (FileID; Data: "My friend ^0 is ^1 years old."; NewLine: NewLine!; ParameterData: {"Dan"; "41"})

writes "My friend Dan is 41 years old." followed by an end-of-line marker.


Floor

Numeric := Floor (Value: Numeric)

Returns the largest integer that is less than or equal to a specified value (the floor of a number).

Parameters

Value: Numeric


For

For (<ControlVariable> Variable; <InitialValue> Any; <TerminateExp> Boolean; <IncrementExp> Any)

 Related Topics  [image]  Example

A control statement (loop) that executes a specified number of times (see Using Loop Statements).

The loop executes only if TerminateExp is true, and continues to execute until ControlVariable's value makes TerminateExp false.  EndFor closes a For statement.

The general form of a For statement is:

For (<ControlVariable>; <InitialValue>; <TerminateExp>; <IncrementExp>)

...statement block...

EndFor

For example, the following statement initializes vTest to one, repeats the statement block while vTest is less than ten, and increments vTest by two after each loop.

For(vTest; 1; vTest < 10; vTest + 2)

...statement block...

EndFor

Parameters

ControlVariable: Variable

Control variable.

InitialValue: Any

Value assigned to ControlVariable at the start of a loop.

TerminateExp: Boolean

The loop executes while TerminateExp is true.

IncrementExp: Any

The value to increment ControlVariable after each loop.


ForEach

ForEach (<ControlVariable> Variable; {<ValueList> Any})

 Related Topics  [image]  Example

A loop statement that executes a number of times equal to the number of specified expressions (see Using Loop Statements).

ControlVariable is assigned the first value before the first loop; the second value before the second loop; the third value before the third loop; and so forth.  The statement block uses the value of ControlVariable to direct macro execution.  EndFor closes a ForEach statement.

The general form of a ForEach statement is:

ForEach (ControlVariable; {ValueList; ...})

...statement block...

EndFor

For example, the following statement repeats three times.  The variable vTest is initialized to "Apples" before the first loop, to "Oranges" before the second, and to "Bananas" before the third.

ForEach(vTest; {"Apples"; "Oranges"; "Bananas"})

... statement block ...

EndFor

Parameters

ControlVariable: Variable

Control variable.

ValueList: Any

Variables, constants, or expressions, enclosed in braces and separated by a semicolon.


ForNext

ForNext (<ControlVariable> Variable; <InitialValue> Any; <FinalValue> Any; <IncrementValue> Any)

 Related Topics  [image]  Example

A loop statement that executes a specified number of times (see Using Loop Statements).

The loop executes if ControlVariable is less than or equal to FinalValue, and executes until ControlVariable is greater than FinalValue.  If you use a negative value in IncrementValue, the loop executes until ControlVariable is less than FinalValue.  EndFor closes a ForNext statement.

The general form of a ForNext statement is,

ForNext (<ControlVariable>; <InitialValue>; <FinalValue>; <IncrementValue>)

...statement block...

EndFor

The following statement initializes vTest to one, repeats the statement block while vTest is less than or equal to five, and increments vTest by two after each loop.

ForNext(vTest; 1; 5; 2)

...statement block...

EndFor

Parameters

ControlVariable: Variable

Control variable.

InitialValue: Any

The value assigned to ControlVariable at the start of a loop.

FinalValue: Any

A variable, constant, or expression.  The loop executes while FinalValue is greater than ControlVariable, or less than ControlVariable if IncrementValue is a negative value.

IncrementValue: Any (optional)

The value to increment ControlVariable after each loop.  Default is 1.


Fraction

Numeric := Fraction (Value: Numeric)

 Related Topics  [image]  Example

Returns the fractional portion of a real number.

Return Value

A fraction.

vFraction := Fraction(1.5)

Result: vFraction equals 0.5

vResult := Fraction(1.77 * 2)

Result: vResult = 0.54

Parameters

Value: Numeric

A real number.


FractionalPart

Numeric := FractionalPart (Value: Numeric)

Returns the fractional portion of a numeric value.

Example

vFrac := FractionalPart (3.2)

Result: vFrac = 0.2

Parameters

Value: Numeric

Fractional number.


FractionStr

String := FractionStr (Value: Numeric; Denominator: Numeric; Option: Enumeration)

 Related Topics

Returns a fraction string representing a value.

Examples

vStr := FractionStr (4.5; 0; MixedFraction!)

Result: vStr = "4 1/2"

vStr := FractionStr (4.5; 8; MixedFraction!)

Result: vStr = "4 4/8"

Parameters

Value: Numeric

Numerical value to be converted.

Denominator: Numeric (optional)

Denominator (the nearest fraction using this denominator is returned).  If missing, or less than or equal to zero, the nearest denominator is used.

Option: Enumeration (optional)

Specifies the fraction form used for values greater than 1.  Default: ImproperFraction!

ImproperFraction! Numerator is larger than the denominator.

MixedFraction! A whole number, followed by a proper fraction (numerator is smaller than the denominator).


Function Prototype

Function Prototype <Name> Label ({<Parameter> Any})

 Related Topics  [image]  Example

Verifies the syntax of a Function statement (see Function).

If the syntax of a function contained in a Use macro file is incorrect and the function is called from the main macro, you get a run-time error but not a compile-time error (see Macro Errors).  Using Function Prototype at the start of a main macro ensures that you get a compile-time error.

Parameters

<Name> Label

The name of the function.  It begins with a letter and consists of one or more letters or numbers.

{<Parameter> } Any

Receives a value from a calling statement (see Using Calling Statements).  If an ampersand precedes the calling statement variable, an ampersand must precede the corresponding function variable (see Address Mode under Function).  Multiple variables are separated by a semicolon.


Function

Function <Name> Label ({<Parameter> Any})

 Related Topics  [image]  Example

Identifies a macro subroutine that can receive one or more values from a calling statement (see Using Calling Statements).  Function also returns a value to the calling statement (caller).

Functions contain one or more statements that execute when the function is called.  Unlike Label statements, functions do not execute unless called.  A calling statement consists of the function's name, and can have one or more parameters that pass values to the function.  Return, EndFunc, or EndFunction direct macro execution to the statement that follows the function's caller.  Return also returns the result of a function operation, or 0 if no result is specified.  For example,

y := 5

x := Add(y) // calling statement

Function Add(z)

z := z + 5

Return(z)

EndFunc

assigns the value 10 to variable x.   Add is the name of the function, and y contains a value to pass.  Variable z has no value until the function is called, when the value of z is 5 (the value of variable y).  The first function statement assigns 10 to variable z.  The next statement returns the value of z to the calling statement, which is then assigned to variable x.  If the function did not contain a Return statement, or if Return did not return a value, x would be equal to 0.

Address Mode

In the above example, the value of y does not change.  The function returns the value of z in variable x.  To change the value of a variable passed to a function, precede the calling statement parameter and its corresponding function parameter with an ampersand (&).  For example,

y := 5

x := Add(&y)

Function Add(&z)

Assign(z; z + 5)

Return(z)

EndFunc

assigns the value 10 to both x and y.  The ampersand before variable x means the variable's address (location in memory) is passed to the function, not the variable's value.  Changes made at the address of x are made to the contents of x.

Arrays

You pass arrays to functions the same way you pass variables.  If you are passing the entire array, every array element must be assigned a value.  If not, a run-time error identifies a reference to the undefined element.  For example,

Declare w[10]

ForNext(x; 1; 9; 1) // assign only 9 elements

w[x] = x

EndFor

Function Test(z[])

ForNext(x; 1; 10; 1)

x[z] = x * 10

EndFor

Return(z[]) // the value of 10 elements returned

EndFunc

y[] = Test(w[]) // 10 elements returned in array y[]

Type(y[10]) // y[10] equals 100

Type(w[10]) // Run-time error: Undefined variable "W[10]"

In the previous example, if you precede the calling statement parameter and the corresponding function parameter with an ampersand (&), 100 is returned in w[10].  No run-time error occurs.  You are passing the address of array w[], not its value.  The value is assigned inside the function (see Address Mode above).  The two statements look like this:

Function Test(&z[])

and

y[] = Test(&w[])

Pass the value of an array element, the same way you pass a variable.  For example,

Declare w[10]

ForNext(x; 1; 10; 1)

w[x] = x

EndFor

Function Test(z)

z := z * 10

Return(z)

EndFunc

y = Test(w[1])

Type(y + " - ")

Type(w[1])

The value of y equals 10.  The value of w[1] equals 1.  If you precede the calling statement parameter and the corresponding function parameter with an ampersand (&), the value of y equals 10 and the value of w[1] equals 10.  Passing the address of w[1] causes its value to change inside the function.  The two statements look like this:

Function Test(&z)

and

y = Test(&w[1])

The general form of a Function statement is:

Function <Name> (<Parameter>; <Parameter>; ... <Parameter>)

...statement block...

EndFunc

The syntax accepts EndFunc or EndFunction.

Parameters

<Name> Label

The name of a function.  It begins with a letter and consists of one or more letters or numbers.

{<Parameter> } Any

Receives a value from a calling statement (see Using Calling Statements).  If an ampersand precedes the calling statement variable, an ampersand must precede the corresponding function variable (see Address Mode above).  Multiple variables are separated by a semicolon.


gcf

Numeric := gcf ({Value: Numeric})

Returns the greatest common factor of a list of values.

The greatest common factor is the largest number that will divide evenly into all the specified values.  If the values have no common factor, 1 is returned.

Parameters

Value: Numeric

List of values.  Multiple values are separated by a semicolon.


GetCurrentDirectory

String := GetCurrentDirectory()

 Related Topics  [image]  Example

Returns name of current directory.

Return Value

Name of current directory.


GetFileAttributes

Enumeration := GetFileAttributes (Filename: String)

 Related Topics  [image]  Example

Returns DOS file attributes.

Return Value

One of the following values, or a negative number if error occurs.  GetFileAttributes can return more than one value at a time.  Use bitwise operators to determine the values.

Error!

Normal!

ReadOnly!

Hidden!

System!

Label!

Directory!

Archived! (file has changed since last save)

Parameters

Filename: String

Include full path.


GetFileDateAndTime

Numeric := GetFileDateAndTime (Filename: String)

 Related Topics  [image]  Example

Returns a number representing the date and time a file was last written to.  Use DateString and TimeString functions to convert the number to a string.

Return Value

A number representing a date and time, or -1 if an error occurs.

Example

vNumber = GetFileDateAndTime("c:\...\<filename>")

vDate = DateString(vNumber)

vTime = TimeString(vNumber)

MessageBox(;; vDate + " -- " + vTime)

Explanation: Displays date and time <filename> was created.

Parameters

Filename: String

Include full path and filename.


GetNumber

GetNumber (VariableName: Variable; Prompt: String; Title: String)

 Related Topics  [image]  Example

Displays a dialog box that contains an edit control to enter an integer or real number.

Parameters

VariableName: Variable

The number entered in the edit box is returned in this variable.

Prompt: String (optional)

Text displayed above the edit control.  Use NToC(0F90Ah) to insert a hard return code in the prompt string.  For example,

GetNumber(vAns; "First line" + NToC(0F90Ah) + "Second line"; "Title")

creates two lines above the edit box.  The next example creates three lines, including one blank line:

Assign(HdReturn; NToC(0F90Ah))

GetNumber(vAns; "First line" + HdReturn + HdReturn + "Second line"; "Title")

Title: String (optional)

Text displayed in the title bar.


GetString

GetString (VariableName: Variable; Prompt: String; Title: String; Length: Numeric)

 Related Topics  [image]  Example

Displays a dialog box that contains an edit control to enter a character string.

Parameters

VariableName: Variable

The character string entered in the edit box is returned in this variable.

Prompt: String (optional)

The text displayed above the edit control.  Use NToC(0F90Ah) to insert a hard return code in the prompt string.  For example,

GetString(vAns; "First line" + NToC(0F90Ah) + "Second line"; "Title")

creates two lines above the edit box.  The next example creates three lines, including one blank line:

Assign(HdReturn; NToC(0F90Ah))

GetString(vAns; "First line" + HdReturn + HdReturn + "Second line"; "Title")

Title: String (optional)

The text displayed in the title bar.

Length: Numeric (optional)

The maximum number of characters the edit control accepts.  Default is unlimited.


GetUnits

GetUnits (VariableName: Variable; Prompt: String; Title: String)

 Related Topics  [image]  Example

Displays a dialog box that contains an edit control to enter a number and unit of measure.

The units of measure are " (inches); i (inches); c (centimeters); m (millimeters); p (points-72 per inch); and w (WordPerfect units-1200 per inch).  If a unit of measure is not specified, the default is WordPerfect units.  To change the default, use DefaultUnits.

Parameters

VariableName: Variable

The number and unit of measure entered in the edit box is returned in this variable.  If no unit of measure is specified, the default is returned.

Prompt: String (optional)

The text displayed above the edit control.  Use NToC(0F90Ah) to insert a hard return code in the prompt string.  For example,

GetUnits(vAns; "First line" + NToC(0F90Ah) + "Second line"; "Title")

creates two lines above the edit box.  The next example creates three lines, including one blank line:

Assign(HdReturn; NToC(0F90Ah))

GetUnits(vAns; "First line" + HdReturn + HdReturn + "Second line"; "Title")

Title: String (optional)

The text displayed in the title bar.


Global

Global ({<VariableName> Variable := <Value> Any})

 Related Topics  [image]  Example

Declares global variables and arrays, and assigns them to the global variable table.

Global variables can be used in Run or Chain macros.

Parameters

<VariableName> Variable

One or more user-defined variables separated by a semicolon.  Variables must begin with a letter and can include any other combination of letters or numbers.  Parentheses are optional.  For example,

Global Variable; Variable

Global(Variable; Variable)

are both valid statements.  The following example declares global arrays with 10 elements and 20 elements:

Global FirstArray[10]; NextArray[20]

The last example simultaneously declares a variable and assigns a value:

Global x := 2

or...

Global x

x := 2

If you create two variables with the same name (for example, Global x and Persist x), the following statement

Global x := 5

specifies which variable x is assigned the value 5.

<Value> Any (optional)

Value assigned to <Variable> at time of declaration.  For example, Global vTest = 20.  vTest equals 20 at run time.  If missing, the value of <Variable> is undefined.


Go

Go (<Label> Label)

 Related Topics  [image]  Example

Jumps to a Label statement and does not return.

Go is generally used to exit multiple layers of nested statements, or to create a loop.

Parameters

<Label> Label

The name of a label.  It begins with a letter and consists of one or more letters or numbers.


lcm

Numeric := lcm ({Value: Numeric})

Returns the least common multiple of a list of values.

The least common multiple is the smallest number that all specified values are multiples of.  If the values have no common multiple, 1 is returned.

Parameters

Value: Numeric

List of values.  Multiple values are separated by a semicolon.


If

If (<Test> Boolean)

 Related Topics  [image]  Example

A conditional statement that determines whether a statement (or statement block) is executed.  See Using Conditional Statements.

If <Test> is true, the statements between If and Else are executed.  If false, the statements between Else and EndIf are executed.

Else is optional.  If <Test> is false and Else is not used, the macro skips the statements between If and EndIf, and executes the first statement after EndIf.

EndIf closes an If statement.

The general form of an If statement is:

If (<Test> )

...statement block...

Else

...statement block...

EndIf

Parameters

<Test> Boolean

Evaluates to true or false.


IfPlatform

IfPlatform ({<PlatformID> Enumeration})

  Example

A conditional statement that specifies a platform or platforms for which subsequent statements are compiled.

If the current platform matches one of the specified platforms, the statements between IfPlatform and EndIfPlatform are compiled and executed.

EndIfPlatform closes an IfPlatform statement.

The general form of an IfPlatform statement is:

IfPlatform (<PlatformID> )

...statement block...

EndIfPlatform

Parameters

<PlatformID> Enumeration

One or more platform identifiers.  Separate multiple platforms with a semicolon.  See platform documentation for other identifiers.

DG!

DOS!

MAC!

NEXT!

NONE!

OS2!

UNIX!

VAX!

WIN!

Win32!

Win95!

WinNT!


IN

Boolean := Value IN Array

Operator.  Precedence level 6.

Return Value

Returns True if the left operand is contained in the right operant.  The left operand may be a value or an array; the right operand must be an array.

If the left operand is a value equal to one of the elements in the right operand array, True is returned.

If the left operand is an array, and every element in the array is equal to some element in the right operand array, True is returned.

Examples

z := 3 IN {1; 2; 3}

Result: z = True

z := 3 IN (1; 2; 4}

Result: z = False

z := {1; 2; 3} IN {1; 2; 3}

Result: z = True

z := {1; 2; 3} IN {1; 2; 3; 4}

Result: z = True

z := {1; 2; 3} IN {1; 2; 4}

Result: z = False


Include

Include (<FileName> String)

 Related Topics  [image]  Example

Specifies a file with executable statements, functions, and/or procedures to include in a macro.  The functions and procedures can be called from the macro.

Include is a non-executable statement that can occur anywhere in a macro.  Include files are automatically compiled with the macro.  All statements in an Include file are executed before macro execution returns to the parent macro.  Return or Quit statements in an Include file end all macro execution.

Parameters

<FileName> String

The path and name of a macro file.  You cannot substitute String with a variable.


Indirect

Any := Indirect (<VariableName> String)

 Related Topics  [image]  Example

Creates variable and label names out of a combination of character strings and/or numbers.

You can use Indirect wherever you use a variable.  The actual variable must be declared and initialized before Indirect.  You can use Indirect to call a Label, but not to create one.

State1 := "Utah"

x := Indirect("State" + 1) // x equals Utah

Variable example in shorthand notation

State1 := "Utah"

State2 := "Idaho"

State3 := "Arizona"

ForNext(Nmbr; 1; 3; 1)

Type("State of " + Indirect("State" + Nmbr))

HardReturn

EndFor

Explanation: Types three lines, State of Utah, State of Idaho, and State of Arizona.

Label example

ForNext(x; 1; 3; 1)

Call(Indirect("Lab" + x))

EndFor

Quit

Label(Lab1)

...statement block...

Return

Label(Lab2)

...statement block...

Return

Label(Lab3)

...statement block...

Return

Explanation: Call three Labels with a single Call statement in a ForNext loop.

Return Value

The contents of <VariableName>.

Parameters

<VariableName> String

Character strings and/or numbers are concatenated to form variable and Label names.  You cannot use Indirect to create a subroutine name.


Integer

Numeric := Integer (Value: Numeric)

 Related Topics  [image]  Example

Returns the integer portion of a real number.

If Value does not contain an integer, 0 is returned.  A negative real number is rounded up to the next integer value, and a positive real number is rounded down.

Return Value

An integer.

vInteger := Integer(1.5)

Result: vInteger equals 1

vResult := Integer(1.77 * 2)

Result: vResult equals 3

vZero := Integer(.7)

Result: vZero equals 0

vNegative := Integer(-1.77)

Result: vNegative equals -2

Parameters

Value: Numeric

A real number.


IntegerPart

Numeric := IntegerPart (Value: Numeric)

Returns the integer portion of a numeric value (the integer of 3.2 is 3.0).

Example

vInt := IntegerPart (3.2)

Result: vInt = 3.0

Parameters

Value: Numeric

Fractional number (return integer part of).


KeyString

Specifies one or more keystrokes in CoachAnimate and SendKeys.  In CoachAnimate, a keystring specifies keys to press during animation.  Metasymbols can be combined.  For example, {Alt + A} or {Ctrl + PageDown}.

The following metasymbols specify a key or keystring in CoachAnimate.

{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}

{NumEnter}

{Num0}...{Num9}  // Numpad numbers

{Left}

{Right}

{Up}

{Dn}

{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}  //  "}"

{LeftButton}  // Mouse clicks

{MiddleButton}

{RightButton}

Metasymbols are translated into keydown messages (WM_KEYDOWN or WM_SYSKEYDOWN) and keyup messages (WM_KEYUP or WM_SYSKEYUP).

Metasymbols are not case-sensitive.  Spaces, plus (+) and minus (-) symbols are delimiters.  For example, "A B C Enter" in CoachAnimate sends "ABC[Enter]" to the application.  A filter that specifies this keystring waits for the user to press "ABC[Enter]".

Plus (+) and minus (-) operators combine metasymbols.  The + delays the keyup message of the first keystroke until the second keystroke is processed.  For example, {Shift + Tab} presses and holds Shift while Tab is pressed and released.  The Shift key is then released.

If a metasymbol does not follow +, then keys previously combined with + remain down until released.  For example, {Shift+Control+} leaves Shift and Control down.

The - releases keys.  For example,

{-Control-Shift} releases Control, then Shift.

The + and - can be combined.  For example,

{Shift+Del-Del+Ins} cuts selected text to the Clipboard (Shift+Del), then pastes it at the insertion point (Shift+Ins).

{Home Shift+End}{Control+B End}{Enter}{Alt+F O} *.doc {Enter}{Escape}{Ctrl+Home}{Shift+}{Ctrl+End Del}{-Shift}

Result:

1 Move to the beginning of the line and select the entire line.

2 Bold the line and move to the end of the line (cancelling the selection).

3 Create a new line.

4 Call the File Open dialog, list all *.DOC files, and then exit the dialog.

5 Go to the top of the document.

6 Hold down Shift.

7 Go to the end of the text and copy the selection to the Clipboard.

8 Release Shift.


Label

Label (<Label> Label)

 Related Topics  [image]  Example

Identifies a macro subroutine, which generally includes a statement block followed by Return or Quit.  See Using Subroutines.

You can pass a Label to a function or procedure.  Label must be preceded by @.  For example,

Call Macro(@Test)

Procedure Macro(@x)

Call(x)

EndProc

Label(Test)

...statements...

Return

Label is used by Call, Case, Case Call, Go, OnCancel, OnCancel Call, OnError, OnError Call, OnNotFound, OnNotFound Call, OnDDEAdvise Call, DDEExecuteExt.

Parameters

<Label> Label

The name of a label.  It begins with a letter and consists of one or more letters or numbers.


lg

Numeric := lg (Value: Numeric)

Returns the base 2 binary logarithm of a value.

Parameters

Value: Numeric

Return the binary logarithm of this value.


ln

Numeric := ln (Value: Numeric)

Returns the base 'e' (natural or napierian) logarithm of a value.

Parameters

Value: Numeric

Return the natural logarithm of this value.


Local

Local ({<VariableName> Variable; <Value> Any})

 Related Topics  [image]  Example

Declares local variables and arrays, and assigns them to the local variable table.

Variables are Local by default.  The Local variable table is removed from memory when the macro ends.

Parameters

<VariableName> Variable

One or more user-defined variables separated by a semicolon.  Variables must begin with a letter and can include any other combination of letters or numbers.  Separate multiple variables with a semicolon.  Parentheses are optional.  For example,

Local VariableName; VariableName

Local(VariableName; VariableName)

are both valid statements.  The next example declares local arrays with 10 elements and 20 elements:

Local FirstArray[10]; NextArray[20]

The last example simultaneously declares a variable and assigns a value:

Local x := 2

or...

Local x

x := 2

If you create two variables with the same name (for example, Global x and Local x), the following statement

Local x := 5

specifies which variable x is assigned the value 5.

<Value> Any (optional)

Value assigned to <Variable> at time of declaration.  For example, Local vTest = 20.  vTest equals 20 at run time.  If missing, the value of <Variable> is undefined.


log

Numeric := log (Value: Numeric)

Returns the base 10 (common) logarithm of a value.

Parameters

Value: Numeric

Return the common logarithm of this value.


logn

Numeric := logn (Value: Numeric; Base: Numeric)

Returns the base n logarithm of a value.

Parameters

Value: Numeric

Return the logarithm of this value.

Base: Numeric

Base of the logarithm to return.


MacroArgs[]

Value := MacroArgs[<Index> Numeric]

An array variable that contains parameter arguments passed to it by Chain, Nest, or Run.

Example

// Macro: MAIN.WCM

// Include full path if macro not in default

// macros directory

RUN("TSTMACRO"; {"x"; "y"; "z"})

// Macro: TSTMACRO.WCM

// Compile, then play MAIN.WCM

vElements := DIMENSIONS(MacroArgs[]; 0)

IF(vElements != 0)

FORNEXT(x; 1; vElements; 1)

MESSAGEBOX(z; "Element Values"; "MacroArgs[" + x + "] = " + MacroArgs[x])

ENDFOR

ELSE

BEEP

MESSAGEBOX(z; "Error"; "No values passed"; IconExclamation!)

ENDIF

Result: x y z


MacroDialogResult

String := MacroDialogResult

 Related Topics

Returns the Control value of the button that dismisses a dialog box.


MacroInfo

Any := MacroInfo (InfoItem: Enumeration; CallLevel: Enumeration or Numeric; {ItemData: Any})

Returns information about the system, the state of a macro, or information about a label or routine within a macro.

Return Value

Any depending on the information requested.  For example, String if the platform name is requested, or Numeric if the platform version is requested.

Discussion

The macro system keeps track of called labels and routines, the data that is specific to each one, and the call depth of each one.  If the main section of a macro calls label "A" which calls procedure "B" which calls function "C", the following is true:

Call depth is 2 (call depth is 0 when the macro starts), and the data for A, B, and C is maintained by the macro system.  The current label/routine is C.  If data for C is needed, specify CallLevel as Current!.  If data for B is needed, specify CallLevel as Previous! (B was the routine that called C).  If data for A is needed, specify CallLevel as Previous! + 1.  Whenever data is needed for a routine before Previous!, specify CallLevel as Previous! + 1, Previous + 2, and so forth.

You may also specify a numeric value for CallLevel parameters, which simplifies getting data on all active label or routine calls using a For loop.  For example, specify Current! as 0, Previous! as 1, the label or routine before Previous! as 3, and so forth.  Start the loop at 0, and use MacroInfo (CallDepth!) to end the loop at the call depth return value.

Parameters

InfoItem: Enumeration

Specifies an InfoItem (the data type returned is in italics).

System Information

PlatformName! String Name of the current platform - Currently the platform names that are returned are:

        "Win32s" for Windows* 3.1 with Win32s

        "Win95" for Windows 95

        "WinNT" for Windows NT

PlatformVersion! Numeric Version of the platform.

PlatformVersionString! String Version of the platform.

PerfectFitVersion! Numeric Version of PerfectFit*.

PerfectFitVersionString! String Version of PerfectFit.

PerfectScriptVersion! Numeric Version of PerfectScript.

PerfectScriptVersionString! String Version of PerfectScript.

PerfectScriptLanguageCode! String Language code of PerfectScript.

PerfectScriptLanguageName! String Language name of PerfectScript.

Macro Information

DialogsExist! Boolean Do macro dialogs exist.

BreakpointsExist! Boolean Do macro break points exist.

ErrorNumber! Numeric ERRORNUMBER value.

MacroDialogResult! Any Same as MacroDialogResult.

MacroArgs! Array MacroArgs array.

CallDepth! Numeric The current call depth: 0 = main.

Label or Routine Information

InRoutine! Boolean Are you in a routine (or label).

InCallback! Boolean Is this a callback.

InAssert! Boolean Is this an Assert call.

FileName! String File the routine is in.

LineNumber! Numeric Source line number.

LabelOrRoutineName! Label Label or routine name.

ChainFileName! String Name of any Chain file.

ChainFileArgs! Array Arguments to any Chain file.

DefaultUnits! Numeric Default units type.

PersistAllOn! Boolean State of PersistAll.

VarErrChkOn! Boolean State of VarErrChkOn.

CancelOn! Boolean State of Cancel condition.

CancelSetup! Boolean Does Cancel condition have an associated label.

CancelCall! Boolean Will Cancel call or goto an associated label.

CancelHandler! Label Label of the cancel handler.

ErrorOn! Boolean Sate of Error condition.

ErrorSetup! Boolean Does Error condition have an associated label.

ErrorCall! Boolean Will Error call or goto an associated label.

ErrorHandler! Label Label of the error handler.

NotFoundOn! Boolean State of NotFound condition.

NotFoundSetup! Boolean Does NotFound condition have an associated label.

NotFoundCall! Boolean Will NotFound call or goto an associated label.

NotFoundHandler! Label Label of the NotFound handler.

UserDefinedConditonOn! Boolean Is a user-defined condition on.

UserDefinedConditionSetup! Boolean Does a user-defined condition have an associated label.

UserDefinedConditionCall! Boolean Will UserDefinedCondition call or goto an associated label.

UserDefinedConditionHandler! Label Label of the UserDefined condition.

CallLevel: Enumeration or Numeric (optional)

Used by some InfoItem types; specifies the label or routine call data is requested for.  See Discussion above.  Default: Current!

Current!

Previous!

{ItemData: Any} (Optional)

Used by some InfoItem types; specifies additional data needed by the specified item.  For example, UserDefinedCondition types require the user-defined condition number for which to return information.  See OnCondition for specifying a user-defined condition number.


MantissaPart

Numeric := MantissaPart (Value: Numeric)

Return the mantissa portion of a numeric value.

Example

vMntsa := MantissaPart(3.2e18)

Result: vMntsa = 3.2

Parameters

Value: Numeric

Fractional number (return the mantissa part of).


Max

Numeric := Max ({Value: Numeric})

Returns the maximum value of a list of values.

Parameters

Value: Numeric

List of values.  Separate multiple values with a semicolon.


Menu

Menu (<MenuPick> Variable; <MnemonicType> Enumeration; <HorizontalPosition> Numeric; <VerticalPosition> Numeric; {<MenuChoice> String})

 Related Topics  [image]  Example

Displays a menu of user-defined items.

Menu is used with statements such as Case, Case Call, and If to execute a statement that corresponds to a selected menu item.  To dismiss a menu, press Alt or Esc.

Parameters

<MenuPick> Variable

A number is returned in this variable, whether numbers or letters are used to reference menu items (see MenuType parameter).   For numbers, the range is 1 to 9.  For letters, the range is 1 to 26.  A returns 1, B returns 2, and so forth.  0 is returned if Alt or Esc is pressed.

<MnemonicType> Enumeration

Determines whether a letter or number is displayed to the left of a menu item.

Digit! Numbers (1-9)

Letter! Alphabetic characters (A-Z)

<HorizontalPosition> Numeric (optional)

The number of pixels from the left side of the main window to the left side of the menu.  To center the menu horizontally, leave this parameter blank.

<VerticalPosition> Numeric (optional)

The number of pixels from the top of the main window to the top of the menu.  To center the menu vertically, leave this parameter blank.

{<MenuChoice> String}

The menu item text.  You may list up to 9 menu items referenced by numbers, or up to 26 referenced by letters.  Enclose menu items in braces ({}) separated by a semicolon.

Menu(vSelection; Letter!; 50; 50; {"Option 1"; "Option 2"; "Option 3"})

To select an item: click it, select it with Tab and press Enter, or press the corresponding letter or number.


MenuList

MenuList (<VariableName> Variable; {<MenuChoice> String}; <Title> String; <HorizontalPosition> Numeric; <VerticalPosition> Numeric)

 Related Topics  [image]  Example

Displays a menu of user-defined items.

This command is included for DOS compatibility.  The Windows* equivalent is Menu.

MenuList is used with statements such as Case, Case Call, and If to execute a statement that corresponds to a selected menu item.  To dismiss a menu, press Alt or Esc.

Parameters

<VariableName> Variable

A number is returned in this variable, whether numbers or letters are used to reference menu items (see MenuChoice parameter).   For numbers, the range is 1 to 9.  For letters, the range is 1 to 26.  A returns 1, B returns 2, and so forth.  0 is returned if Alt or Esc is pressed.

{<MenuChoice> String}

The menu item text, enclosed in braces ({}) and separated by a semicolon.

MenuList(vSelection; ; ; {"Option 1"; "Option 2"; "Option 3"})

To select an item: click it, select it with Tab and press Enter, or press the corresponding letter or number.  Nine items or less are displayed with a number to the left of the menu item.  More than nine are displayed with a letter.  The range is 1 to 26.

<Title> String

The text displayed in the title bar.

<HorizontalPosition> Numeric (optional)

The number of pixels from the left side of the main window to the left side of the menu.  To center the menu horizontally, leave this parameter blank.

<VerticalPosition> Numeric (optional)

The number of pixels from the top of the main window to the top of the menu.  To center the menu vertically, leave this parameter blank.


MessageBox

Enumeration := MessageBox (Status: Variable; Caption: String; Message: String; Style: Enumeration; {ParameterData: String})

 Related Topics  [image]  Example

Displays a message box.

Provides a limited set of buttons and icons, and an option to include up to 10 different parameter strings in the message.

Return Value

The control value of the button that dismisses the message box is returned in this variable.  As a function, you can use MessageBox in an If statement.  The return button values are:

Error!

OKButton!

CancelButton!

AbortButton!

RetryButton!

IgnoreButton!

YesButton!

NoButton!

If there is not enough memory to create the message box, 0 is returned.

Parameters

Status: Variable (optional)

The control value of the button that dismisses the message box (see Return Value above). The semicolon is still required if not used.

Caption: String (optional)

The title bar text.  Default: "PerfectScript"

Message: String

The message box text.  Icons appear to the left of the message.  Control buttons are centered below the message.  If HasParameters! style is used, a caret (^) followed by a number inserts the corresponding ParameterData message in its place (see ParameterData parameter below).  Use two carets (^^) to insert a caret as part of the message string.  Use NToC(0F90Ah) to insert a hard return code in the message string.  For example,

MessageBox(vAns; "Title"; "First line" + NToC(0F90Ah) + "Second line"; IconInformation!)

creates two lines above the control button.  The next example creates three lines, including one blank line:

Assign(HdReturn; NToC(0F90Ah))

MessageBox(vAns; "Title"; "First line" + HdReturn + HdReturn + "Second line"; IconInformation!)

Style: Enumeration (optional)

Message box styles.  Type | between enumerations to combine styles.  Select only one style from each group

Default: OK! | IconNone! | DefButton1!

Button enumerations are:

AbortRetryIgnore! (Abort, Retry, and Ignore)

OK! (OK - default if no button is specified)

OKCancel! (OK and Cancel)

RetryCancel! (Retry and Cancel)

YesNo! (Yes and No)

YesNoCancel! (Yes, No, and Cancel)

Icon enumerations are:

IconNone! (No icon (default if no icon is specified))

IconAsterisk! (Lowercase "i" in a blue circle)

IconExclamation! (Exclamation point in a yellow circle)

IconHand! (Stop sign in a red circle)

IconInformation! (Lowercase "i" in a blue circle)

IconQuestion! (Question mark in a green circle)

IconStop! (Stop sign in a red circle)

Default button enumerations are:

DefButton1!

DefButton2!

DefButton3!

Modality enumerations are:

ApplicationModal! (You can switch to another application, but you must dismiss the message box (click a control button) before the macro resumes.  ApplicationModal! is the default if either SystemModal! or TaskModal! is not specified.)

SystemModal! (You must dismiss the message box before the macro resumes, and before you can switch to another application.)

TaskModal! (You can switch to another application, but you must dismiss the message box (click a control button) before the macro resumes.)

Miscellaneous enumerations are:

Beep! (Beep when the message box is displayed.)

HasParameters! (Notifies MessageBox box that a caret (^) followed by a number in the Message parameter is to be replaced by the corresponding character string in the ParameterData parameter.)

{ParameterData: String} (optional)

The text for the Message parameter (numbering begins with 0).  Up to 10 parameters separated by semicolons are allowed.  For example,

v0 := "Yes to continue, or"

v1 := "No to quit."

MessageBox(x; "Title"; "Select ^0 ^1"; YesNo! | IconStop! | HasParameters!; {v0; v1})

fills the Message parameter with "Select Yes to continue, or No to quit.".  If HasParameters! is not used, Message contains "Select ^0 ^1".

If not specified, no parameters are substituted into Message.


Min

Numeric := Min ({Value: Numeric})

Returns the minimum value of a list of values.

Parameters

Value: Numeric

List of values.  Separate multiple values with a semicolon.


MMPlay

Numeric := MMPlay (Filename: String; Options: Enumeration)

 Related Topics  [image]  Example

Plays a sound file.

Plays a audio (WAV) file, an Audio-Visual Interleave (AVI) movie file, or a Musical Instrument Digital Interface (MIDI) file, or speaks an ASCII text file (see MMSpeak).  Speech requires text-to-speech drivers like those shipped with some sound boards.  Audio and MIDI files require the appropriate sound card.

Return Value

A handle that can be passed to MMStopPlay.

Parameters

Filename: String

The path and name of a sound file.  The appropriate driver for each file type must be installed.

Options: Enumeration (optional)

Default: DontWait!

DontWait! Start playing and go immediately to the next macro statement (has no effect on some systems).

Wait! Start playing and wait for play to finish before going to the next macro statement.


MMSpeak

MMSpeak (String: String)

 Related Topics  [image]  Example

Speaks an ASCII file or ASCII text.

Parameters

String: String

The path and name of an ASCII file, or a string, or a variable containing a string.  A text-to-speech driver must be installed in the Windows* 95 System directory.  Products supported are: Lernout and Hauspie, Centigram TruVoice, and CreativeTextAssist (SoundBlaster).


MMSpeakClipboard

MMSpeakClipboard()

 Related Topics  [image]  Example

Speaks text saved to the Clipboard.

A text-to-speech driver must be installed.  Products supported are: Lernout and Hauspie, Centigram TruVoice, and the Creative TextAssist.


MMStopPlay

MMStopPlay (Handle: Numeric)

Stops a multimedia file started with MMPlay, with DontWait! option set.  With Wait! option set, MMStopPlay has no effect.

Parameter

Handle: Numeric

Returned by MMPlay.


MMStopSpeech

MMStopSpeech()

 Related Topics  [image]  Example

Stops a speech (text) file started with MMPlay (ASCII file), MMSpeak, or MMSpeakClipboard.

After a text file begins to speak, control immediately returns to the macro.  Use MMStopSpeech to stop speaking a text file.


MOD

Numeric := Numeric MOD Numeric

 Related Topics

Returns the integer remainder of the quotient of two numbers.  See Arithmetic Operators.


Mouse String

Represents a mouse event or action.  CoachAnimate specifies the animated mouse actions.

Syntax

The syntax for mouse events for CoachAnimate is:

[Ctrl|Control]  [Shift]  [Alt]

[Left|Middle|Right]

Click|DoubleClick|Press|Release|Move

[To|In|Inside|On NamedRegion]

[At (x,x)|(x,x,x,x)]

Arguments are not case-sensitive.  Brackets ([]) enclose optional values.  A vertical bar | separates values when only one can be chosen.  A space separates arguments.

Mouse String Arguments

Keys (optional)  ([Ctrl|Control]  [Shift]  [Alt])

Specifies keys to press with the mouse event, such as holding down Shift and Control when the mouse is clicked.  These values can occur in any order.

Button (optional)  ([Left|Middle|Right])

Indicates whether to use the left, middle, or right mouse button.  Left is the default.

Action

(Click|DoubleClick|Press|Release|Move)

Indicates how to click or press the mouse button, or whether to move the mouse pointer.

Argument (explanation)

Click (one click)

DoubleClick (double-click)

Press (press and hold button down)

Release (release button after it is pressed)

Use Press with Release for drag (use two Animate commands).

Move (move pointer to specified location)

Relative Location ([To|In|Inside|On])

Specifies a screen position for a mouse event.

Argument (meaning)

To (moves the pointer to the named region if the Action argument is Move; otherwise, To means In)

In (Mouse action occurs within the specified named region)

See Named Region below.

Inside (same as In)

On (same as In)

Named Region ([NamedRegion])

Specifies a window or location where the mouse action occurs.  Required only if a relative location is specified.  For example, you may want to specify a mouse click in the Open button of the Open Dialog.  The named region specifies a name for the Open button.

Named regions are defined by the application.  The region consists of the application name, followed by a period (.), followed by additional words that narrow the named region to the appropriate window.  For example, the named region of the Open button on the Open dialog of WordPerfect* is: WordPerfect.FileServicesDlg.BrowsePage.OpenBttn

Use the WordPerfect Help system to find a region name.

Add the following DWord value to your registry: "HKEY_CURRENT_USER\Software\PerfectOffice\PerfectFit\Help\HelpInformation" and set the value to 1.

To find a named region:

1	Press Shift+F1.

2	Click the desired menu item or dialog box.

A Help Information screen is displayed containing the NamedRegion.

Narrowed Location (optional)  ([At (x,x)|(x,x,x,x)])

Specifies an exact point (x,x), or rectangle (x,x,x,x) where a mouse event occurs.  Point and rectangle positions are relative to the window specified in Named Region.  Pixels are the default unit of measure.  For example, in CoachAnimate,

Move To WordPerfect.FileServicesDlg.BrowsePage.OpenBttn At (10,5)

moves the pointer to a point 10 pixels right and 5 pixels down from the upper left corner of the Open button.

You can specify the percentage from the upper left corner of the window by placing a percent sign % after values.  For example,

Move To WordPerfect.FileServicesDlg.BrowsePage.OpenBttn At (50%, 50%)

moves the pointer to the center of the Open button.

To specify dialog units, place the letter d after values.

Examples

Two Mouse String examples follow.  Named regions do not represent actual WordPerfect names.

Shift Right DblClick

Result: Shift is held down while the right mouse button is double-clicked (the mouse pointer may be anywhere on the screen).

Move at (50%, 50%)

When this string is specified in COACHANIMATE, the mouse pointer moves to the center of the display.


Nest

Nest (MacroFileName: String; {Parameter: Any})

 Related Topics  [image]  Example

Calls (starts) a nested macro.

This command is included for DOS compatibility.  The Windows* equivalent is Run.

A nested macro starts immediately when called.  When a nested macro ends, the first statement following Nest is executed.

PerfectScript automatically compiles uncompiled Nest macros.  Macro execution stops if the macro will not compile.

Parameters

MacroFileName: String

The path and name of a compiled macro.

{Parameter: Any} (optional)

Enclose multiple parameters in braces ({}), separated by a semicolon.  For example: Nest ("macro"; {"a"; "b"; "c"}).  Parameter values are passed to a special array variable named MacroArgs[].

If missing, MacroArgs[] is not defined in the new macro.


NetAddConnection

Numeric := NetAddConnection (RemoteName: String; LocalName: String; Provider: String; Type: Enumeration; Password: String; UserName: String; Options: Enumeration)

Connects to a network resource.

Return Value

0 if the connection was successful, or a non-zero value that represents an error code if not.

Example

NetAddConnection ("wpc35\dev1:win32sh"; "I:")

Parameters

RemoteName: String

Name of a network resource (see network provider's naming conventions).

LocalName: String (optional)

Name of network resource on local system (not case sensitive).  For example, F: or LPT1.  If this parameter is missing, a connection to the network resource is made without redirecting a local device.

Provider: String (optional)

Specifies a network provider to connect to.  If missing or "", the operating system parses RemoteName to try to determine the correct provider.  Only use this parameter when a network provider must be specified.  Otherwise, Windows* should determine which provider the network name maps to.  If this parameter is present, Windows will only try to connect to the named provider.

Type: Enumeration (optional)

Default: Disk!

Disk!

Printer!

Password: String (optional)

Password to use when making the connection.  If not present, the default password associated with UserName is used.  If this parameter is missing or "", no password is used.

UserName: String (optional)

The username to use when making a connection.  If not present, the default UserName is used (user context provides the default user name).  Use this parameter when the user wants to connect to a network resource and they have been assigned a user name or account.  UserName may be specific to a network provider, and can be used in a security context.

Options: Enumeration (optional)

Default: DontAutoRestore!

DontAutoRestore! Do not remember the connection to restore it automatically every time you log in.

AutoRestore! Remember the connection and restore it automatically every time you log in.


NetCancelConnection

Boolean := NetCancelConnection (ResourceName: String; Options: Enumeration; Force: Boolean)

Terminates a connection to a network resource.

Return Value

True if successful, or False if not.

Example

NetCancelConnection ("I:")

Parameters

ResourceName: String

Specifies a remote network resource or a redirected local device.  See NetAddConnection.

Options: Enumeration (optional)

Default: DontAutoRestore!DontAutoRestore! No information about the connection is stored.

AutoRestore! Windows will not restore connection in subsequent attempts to log on.

Force: Boolean (optional)

True disconnects even though there are open files or jobs on the connection.  If missing or False, disconnect fails if there are open files or jobs on the connection.


NetConnectionDlg

Numeric := NetConnectionDlg (Type: Enumeration)

Opens a dialog box for connecting to network resources.

Return Value

The status code returned by the dialog.

Parameters

Type: Enumeration (optional)

Default: Disk!


NetDisconnectDlg

Numeric := NetDisconnectDlg (Type: Enumeration)

Opens a dialog box for disconnecting from network resources.

Return Value

The status code returned by the dialog.

Parameters

Type: Enumeration (optional)

Default: Disk!

Disk!

Printer!


NetGetConnection

String := NetGetConnection (LocalName: String)

Returns the name of a network resource associated with a local device.

Return Value

String is empty when an error occurs.

Example

vNetResource := NetGetConnection ("M:")

Parameter

LocalName: String

Name of a local device.


NetGetUniversalName

String := NetGetUniversalname (LocalPath: String)

Returns the UNC name of a local file.

Parameter

LocalPath: String

Local name of the file.


NetGetUser

String := NetGetUser()

Returns a user network ID.


NewDefault

NewDefault (<ProductPrefix> String)

 Related Topics  [image]  Example

Specifies a macro's new default application.

The compiler verifies that each product command is valid for the default application.  Invalid product commands produce a syntax error during compilation.

Product commands to the default application do not require a product prefix.  A product command to a non-default application, without a product prefix, creates a compile-time syntax error.

Parameters

<ProductPrefix> String

A unique identifier that matches the ProductPrefix parameter of an Application statement.


Next

 Related Topics  [image]  Example

Advances a loop iteration before the end of the loop.

Use Next inside a conditional statement such as If or Switch in a loop to advance a loop iteration when a specified condition is met.  Statements after Next are ignored.


NOT

Boolean := NOT Boolean

Inverts the result of a relational expression.  Returns TRUE if the inverted value is TRUE, or FALSE if not.  See Logical Operators and Logical Expressions.


NotFound

Enumeration := NotFound (State: Enumeration)

 Related Topics  [image]  Example

Determines how a macro responds to a Not Found condition.

A Not Found condition is generally the result of a failed search.  Create a Not Found condition with Assert(NotFoundCondition!).

Return Value

Off! Previous condition was Off!

On! Previous condition was On!

Parameters

State: Enumeration (optional)

Specifies the Not Found state.  The default is NotFound(On!).  If missing, the current state is returned without changing it.

Off! Ignores a Not Found condition.

On! Stops a macro unless preceded by OnNotFound, which directs macro execution to a specified Label.


NthRoot

Numeric := NthRoot (Value: Numeric; Root: Numeric)

Returns the Nth root of a value.

Parameters

Value: Numeric

Value (return the Nth root of).

Root: Numeric

Root to return.


NToC

String := NToC (CharacterOrCharSet: Numeric; Character: Numeric)

  Example

Converts a number from a WordPerfect* character set to its character equivalent.

Return Value

The character equivalent of a number in a WordPerfect character set.

Parameters

CharacterOrCharSet: Numeric (optional)

The number of a WordPerfect character set.  If this parameter is not used, the default is 0 (ASCII set).

Character: Numeric

The number of a character in a WordPerfect character set.


NToC

String := NToC (Character: Numeric)

 Related Topics  [image]  Example

Converts a number to its character equivalent.

Return Value

The character equivalent of an ANSI decimal value.

Parameters

Character: Numeric

ANSI decimal value.


NumStr

String := NumStr (Value: Any; RightDigits: Numeric; LeftDigits: Numeric)

 Related Topics

Converts a number to a character string of numbers.

Return Value

A character string of numbers.

vText := NumStr(999; 0) // vText = "999"

vText := NumStr(3+7; 0) // vText = "10"

Parameters

Value: Numeric

A number or expression that results in a number.

RightDigits: Numeric (optional)

The number of digits to the right of the decimal returned as a character string.  The range is 0-16.  The default is 6.  If the value of this parameter is greater than the number of decimal places, NumStr rounds up the entire expression.  The decimal point returned by NumStr is defined by the sDecimal setting in the [intl] section of the Windows* WIN.INI file.

LeftDigits: Numeric (optional)

This parameter is currently ignored.  Default: Use as many digits as needed.


OemString

String := OemString (<Value> String)

Passes value as an OEM string (DLL call in-line parameter function).  See DLLCall.


OnCancel

Label := OnCancel (Label: Label)

 Related Topics  [image]  Example

Specifies a Label or routine (function or procedure) to execute when a Cancel condition occurs.

A macro with more than one OnCancel executes the last OnCancel before a Cancel condition occurs.  A Cancel condition stops a macro unless preceded by OnCancel.

Return Value

The previous Label set to execute by the OnCancel command.  If there is no label, "" is returned.

Parameters

Label: Label (optional)

A Label to execute when a Cancel condition occurs.  If a label is not specified, the macro halts when a Cancel condition occurs.  For example: OnCancel().


OnCancel Call

Label := OnCancel Call (Label: Label)

 Related Topics  [image]  Example

Specifies a Label-Return statement or routine (function or procedure) to execute when a Cancel condition occurs.

Return directs macro execution to the first statement after the Cancel condition.

A macro with more than one OnCancel Call executes the last OnCancel Call before a Cancel condition occurs.  A Cancel condition stops a macro unless preceded by OnCancel Call.

Return Value

The previous Label set to execute by the OnCancel Call command.  If there is no label, "" is returned.

Parameters

Label: Label

A Label to call when a Cancel condition occurs.


OnCondition Call

Label := OnCondition Call (Conditon: Enumeration or Numeric; Label: Label)

Specifies a Label-Return statement or routine (function or procedure) to execute when a specified condition occurs.  See Condition.

Return directs macro execution to the first statement after the specified condition.

A macro with more than one OnCondition Call executes the last Condition command before a Cancel, Error, NotFound, or user-defined condition occurs.  One of these conditions stops a macro unless preceded by OnCondition Call.

Note

A user-defined condition number must be greater than or equal to 100.  It is expressed as UserDefinedCondition! + Numeric, or as a Numeric.  For example, UserDefinedCondition! + 1 is equal to the numeric value 101.  Use Assert to cause the user-defined condition.

Return Value

The previous Label set to execute by the OnCancel Call command.  If there is no label, "" is returned.

Parameters

Condition: Enumeration or Numeric

Associates a condition with Label.  Use one of the enumerations below, or any numeric value greater than or equal to 100 (user-defined condition).  See Note above.

CancelCondition!

ErrorCondition!

NotFoundCondition!

UserDefinedCondition! Adds 100 to a user-defined condition value (see Note above).  For example, OnCondition Call (UserDefinedCondtion! + 1; Label101), sends macro execution to a label named Label101 on Assert (101).

Label: Label

A Label to execute when the specified condition occurs.  If a Label is not specified, the macro halts on the associated condition.  For example: Label := OnCondition Call (ErrorCondition!).


OnCondition

Label := OnCondition (Conditon: Enumeration or Numeric; Label: Label)

Specifies a Label or routine (function or procedure) to execute when a Cancel, Error, NotFound, or user-defined condition occurs.

A macro with more than one OnCondition executes the last Condition command before a Cancel, Error, NotFound, or user-defined condition occurs.  One of these conditions stops a macro unless preceded by OnCondition.

Note

A user-defined condition number must be greater than or equal to 100.  It is expressed as UserDefinedCondition! + Numeric, or as a Numeric.  For example, UserDefinedCondition! + 1 is equal to the numeric value 101.  Use Assert to cause the user-defined condition.

Return Value

The previous Label set to execute by the OnCondition command.  If there is no label, "" is returned.

Parameters

Condition: Enumeration or Numeric

Associates a condition with Label. Use one of the enumerations below, or any numeric value greater than or equal to 100 (user-defined condition).  See Note above.

CancelCondition!

ErrorCondition!

NotFoundCondition!

UserDefinedCondition! Adds 100 to a user-defined condition value (see Note above).  For example, OnCondition (UserDefinedCondtion! + 1; Label101), sends macro execution to a label named Label101 on Assert (101).

Label: Label (optional)

A Label to execute when the specified condition occurs.  If a Label is not specified, the macro halts on the associated condition.  For example: Label := OnCondition (CancelCondition!).


OnDDEAdvise Call

Enumeration := OnDDEAdvise Call (ConversationID: Numeric; ItemName: String; Label: Label)

 Related Topics

Establishes a link with an application and tests for changes in the value of the DDERequest ItemName parameter.

Return Value

One of the following enumerations:

Success!

AdvActTimeout!

Busy!

DataAckTimeout!

DllNotInitialized!

DllUsage!

ExeAckTimeout!

InvalidParameter!

LowMemory!

MemoryError!

NotProcessed!

NoConvEstablished!

PokeAckTimeout!

PostMsgFailed!

Reentrancy!

ServerDied!

SysError!

UnAdvAckTimeout!

UnfoundQueueId!

See Microsoft* SDK (DdeGetLastError function) for detailed information on each enumeration.

Parameters

ConversationID: Numeric

The value of the DDERequest ConversationID parameter.

ItemName: String

The value of the DDERequest ItemName parameter.

Label: Label

The Label to call when the value of ItemName changes.


OnError

Label := OnError (Label: Label)

 Related Topics  [image]  Example

Specifies a Label or routine (function or procedure) to execute when an Error condition occurs.

A macro with more than one OnError statement executes the last OnError before an Error condition occurs.  An Error condition stops a macro unless preceded by OnError.

Return Value

The previous Label set to execute by the OnError command.  If there is no label, "" is returned.

Parameters

Label: Label (optional)

A Label to execute when an Error condition occurs.  If a label is not specified, the macro halts when an Error condition occurs.  For example: OnError().


OnError Call

Label := OnError Call (Label: Label)

 Related Topics  [image]  Example

Specifies a Label-Return statement or routine (function or procedure) to execute when an Error condition occurs.

Return directs macro execution to the first statement after the Error condition.

A macro with more than one OnError Call statement executes the last OnError Call before an Error condition occurs.  An Error condition stops a macro unless preceded by OnError Call.

Return Value

The previous Label set to execute by the OnError Call command.  If there is no label, "" is returned.

Parameters

Label: Label

A Label to call when an Error condition occurs.


OnNotFound Call

Label := OnNotFound Call (Label: Label)

 Related Topics  [image]  Example

Specifies a Label-Return statement or routine (function or procedure) to execute when a Not Found condition occurs.

Return directs macro execution to the first statement after the Not Found condition.

A macro with more than one OnNotFound Call statement executes the last OnNotFound Call before a Not Found condition occurs.  A Not Found condition stops a macro unless preceded by OnNotFound Call.

Return Value

The previous Label set to execute by the OnNotFound Call command.  If there is no label, "" is returned.

Parameters

Label: Label

A Label to call when a Not Found condition occurs.


OnNotFound

Label := OnNotFound (Label: Label)

 Related Topics  [image]  Example

Specifies a Label or routine (function or procedure) to execute when a Not Found condition occurs.

A macro with more than one OnNotFound statement executes the last OnNotFound before a Not Found condition occurs.  A Not Found condition stops a macro unless preceded by OnNotFound.

Return Value

The previous Label set to execute by the OnNotFound command.  If there is no label, "" is returned.

Parameters

Label: Label (optional)

A Label to execute when a Not Found condition occurs.  If a label is not specified, the macro halts when a Not Found condition occurs.  For example: OnNotFound().


OpenFile

Numeric := OpenFile (Name: String; AccessMode: Enumeration; ShareMode: Enumeration; DataType: Enumeration)

 Related Topics  [image]  Example

Opens a file for reading and writing text data.

Close file when no longer needed, or system resources will be lost.  The file is closed automatically when the macro ends.  See CloseFile.

Return Value

File ID, or a negative number if error occurs.  The following file I/O (input/output) commands require a file ID:

CloseFile

FileIsEOF

FilePosition

FileRead

FileTruncate

FileWrite

Parameters

Name: String

Include full path.  If path not included, the file is searched for in the following directories: the shared PerfectFit* directory, current, Windows* system, Windows, DOS PATH, network (mapped).

AccessMode: Enumeration (optional)

Default: Read!

Read!

ReadWrite!

Write! Overrides existing data if position marker not at end of file (see FilePosition).

WriteNew! Deletes existing data and creates a new file.

Append!

Exists! Opens and closes file to test if file exists.

If file does not exist: Read! and ReadWrite! cause macro to fail; Write!, WriteNew!, and Append! create a new file.

ShareMode: Enumeration (optional)

Default: None!

None!

Compatibility! Allows one or more macros to open a file any number of times.

Exclusive! Denies read and write access to more than one macro.

DenyNone! Does not deny other macros read and write access.

DenyRead! Denies other macros read access.

DenyWrite! Denies other macros write access.

DataType: Enumeration (optional)

Default: AnsiText!

AnsiText!

OEMText!

WPText! Reads or writes WP character strings.  It does not create a WP document.


OR

Boolean := Boolean OR Boolean

Combines two relationship expressions.  Returns TRUE if at least one expression is true, or FALSE if not.  See Logical Operators and Logical Expressions.


Pause

Pause()

 Related Topics  [image]  Example

Pauses a macro, returning computer control to the user.

To resume macro execution, press Enter, or choose Tools, Macro, Pause.  To stop a macro, choose Tools, Macro, Play.  When Pause follows a Prompt statement, choose OK to resume macro execution or Cancel to create a Cancel condition.


Persist

Persist ({<VariableName> Variable := <Value> Any})

 Related Topics  [image]  Example

Declares PerfectFit* variables and arrays, and assigns them to the persist variable table.

Persist variables are available to any PerfectFit application while PerfectFit is running.

Parameters

<VariableName> Variable

One or more user-defined variables separated by a semicolon.  Variables must begin with a letter and can include any other combination of letters or numbers.  Separate multiple variables with a semicolon.  Parentheses are optional.  For example,

Persist <VariableName>; <VariableName>

Persist (<VariableName>; <VariableName>)

are both valid statements.  The next example declares persist arrays with 5 elements and 15 elements:

Persist FirstArray[5]; NextArray[15]

The last example simultaneously declares a variable and assigns a value:

Persist x := 2

or...

Persist x

x := 2

If you create two variables with the same name (for example, Global x and Persist x), the following statement

Persist x := 5

specifies which variable x is assigned the value 5.

<Value> Any (optional)

Value assigned to <Variable> at time of declaration.  For example, Persist vTest = 20.  vTest equals 20 at run time.  If missing, the value of <Variable> is undefined.


PersistAll

Enumeration := PersistAll (State: Enumeration)

 Related Topics  [image]  Example

Assigns a macro's variables and arrays to the Persist variable table.

Persist variables are available to any PerfectFit* application while PerfectFit is running.

Return Value

Off! Previous state was Off!

On! Previous state was On!

Only variables assigned values after PersistAll or declared Persist are Persist variables.  Variables assigned values before PersistAll, and variables declared Local or Global, are not Persist variables.  In the following example, only var6 and var7 are Persist variables:

Application(A1; "WordPerfect"; Default; "US")

Local var1; var2

Assign(var3; 0)

Global var4

Persist var7

Assign(var7; "Persist Variable")

PersistAll

Local var5

Assign(var4; 2)

Assign(var6; "Persist Variable")

Parameters

State: Enumeration (optional)

If missing, the current state is returned without changing it.

Off!

On!


pi

Numeric := pi()

Returns 'pi' (3.14.... ratio of the circumference of a circle to its diameter).


Procedure

Procedure <Name>Label ({<Parameter>Any})

 Related Topics  [image]  Example

Identifies a macro subroutine that can receive one or more values from a calling statement (see Using Calling Statements).

Procedures contain one or more statements that execute when the procedure is called.  Unlike Label subroutines, procedures do not execute unless called.  A calling statement consists of the procedure's name, and can have one or more parameters that contain values passed to the procedure.  Return, EndProc, or EndProcedure direct macro execution to the statement that follows the procedure's caller.

Address Mode

To change the value of a variable passed to a procedure, precede the calling statement parameter and its corresponding procedure parameter with an ampersand (&).  In the following example, the value of x is 5 after calling Test:

x := 5

Test(x) // calling statement

Procedure Test(z)

z := z + 5

EndProc

In the next example, the value of x is 10 after calling Test:

x := 5

Test(&x) // calling statement

Procedure Test(&z)

z := z + 5

EndProc

The ampersand before variable x means the variable's address (location in memory) is passed to the procedure, not the variable's value.  Changes made at the address of x are made to the contents of x.

The general form of a Procedure statement is:

Procedure <Name> (<Parameter>; <Parameter>)

...statement block...

EndProc

The syntax accepts EndProc or EndProcedure.

Parameters

<Name> Label

The name of the procedure.  It begins with a letter and consists of one or more letters or numbers.

{<Parameter> Any}

Receives a value from a calling statement (see Using Calling Statements).  If an ampersand precedes the calling statement variable, an ampersand must precede the corresponding procedure variable (see Address Mode above).  Multiple variables are separated by a semicolon.


Procedure Prototype

Procedure Prototype <Name> Label ({<Parameter> Any})

 Related Topics  [image]  Example

Verifies the syntax of a Procedure statement (see Procedure).

If the syntax of a procedure contained in a Use macro file is incorrect and the procedure is called from the main macro, you get a run-time error but not a compile-time error (see Macro Errors).  Use Procedure Prototype at the start of a main macro so that syntax errors will appear as compile-time errors instead of run-time errors.

Parameters

<Name> Label

The name of the procedure.  It begins with a letter and consists of one or more letters or numbers.

<Parameter> Any

Receives a value from a calling statement (see Using Calling Statements).  If an ampersand precedes the calling statement variable, an ampersand must precede the corresponding procedure variable (see Address Mode under Procedure).  Multiple variables are separated by a semicolon.


Product

Numeric := Product ({Value: Numeric})

Returns the product of a list of values.

Parameters

Value: Numeric

List of values.  Separate multiple values with a semicolon.


Prompt

Prompt (Title: String; Prompt: String; Style: Enumeration; HorizontalPosition: Numeric; VerticalPosition: Numeric)

 Related Topics  [image]  Example

Displays a message box with OK and Cancel button controls.

Pause following Prompt displays a Prompt message box until the user selects OK or Cancel.  OK removes the prompt and resumes macro execution.  Cancel removes the prompt and creates a Cancel condition (see OnCancel).

If Prompt is not followed by Pause, the message box is displayed until an EndPrompt occurs or the macro ends.  You can display only one message box at a time.  Calling a second message box replaces the first.

The general form of a Prompt statement is:

Prompt (Title; Prompt; Style; HorizontalPosition; VerticalPosition)

Pause

A Prompt statement can have another form:

Prompt (Title; Prompt; Style; HorizontalPosition; VerticalPosition)

...other statements...

EndPrompt

Parameters

Title: String

The text displayed in the title bar.

Prompt: String (optional)

The text displayed in the prompt box.  If missing, the title is displayed as the prompt and "PerfectScript" as the title.

Style: Enumeration (optional)

The icon to display to the left of Prompt.  The default value is no icon.  Type | between enumerations to combine styles (not all combinations are possible).  The values are:

NoIcon!

StopSign!

QuestionMark!

ExclamationPoint!

InformationIcon!

Pause! Prompt command pauses until button is pressed (same as following Prompt command with a Pause command).

Beep!

NoButtons! Shows prompt without OK and Cancel buttons.  Use the EndPrompt command to remove the prompt (not the Pause command).

Example

Prompt ("No Button Example"; "Please Wait"; StopSign! | NoButtons! | Beeps!)

...other statements...

EndPrompt()

Explanation: Prompt displays a stop sign icon, no buttons, and beeps.  It waits until other statements have executed before disappearing.

HorizontalPosition: Numeric (optional)

The number of pixels from the left side of the main window to the left side of the message box.  If you omit this parameter, the prompt is centered horizontally in the main window.

VerticalPosition: Numeric (optional)

The number of pixels from the top of the main window to the top of the message box.  If you omit this parameter, the prompt is centered vertically in the main window.


Quit

Quit()

 Related Topics  [image]  Example

Ends a macro.

Chain does not execute if Quit occurs before Chain.


RadiansToDegrees

Numeric := RadiansToDegrees (Radians: Numeric)

Convert an angle in radians to degrees.

Parameters

Radians: Numeric

Angle in radians


Randomize

Numeric := Randomize (Seed: Numeric)

Randomize a random number seed.

Parameters

Seed: Numeric (optional)

Seed value that starts the random number generator.  If missing, the current system clock is used to pick a starting seed.


RandomNumber

Numeric := RandomNumber (Minimum: Numeric; Maximum: Numeric)

Returns a random number in a range.

If only a Minimum or Maximum value is given (see Parameters), a number between 0.0 and that value is returned.  The range includes 0.0; it does not include the value.  If no values are given, a number between 0.0 and 1.0 is returned.  The range includes 0.0; it does not include 1.0.

Parameters

Minimum: Numeric (optional)

Minimum number to generate.  Default: 0.0

Maximum: Numeric (optional)

Maximum number to generate.  Default: 1.0


Real

Numeric := Real (<Value> Numeric)

Passes value as an 8-byte float (DLL call in-line parameter function).  See DLLCall.


RegionAddListItem

RegionAddListItem (NamedRgn: String; Item: String)

 Related Topics  [image]  Example

Adds an item to a list box, combination box, popup button, or custom control.

The only way to add a list item to a custom control is with RegionAddListItem, or by sending the custom control a message.  DialogAddListItem does not work on custom controls.

Controls added with DialogAddControl are considered custom controls.  The user is responsible for the use of these controls.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.

Item: String

A list item.


RegionEnableWindow

RegionEnableWindow (NamedRgn: String; State: Enumeration)

 Related Topics  [image]  Example

Enables or disables mouse and keyboard input to a dialog box or control.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.  If a control ID is not specified, State affects the entire dialog box.

State: Enumeration

Mouse and keyboard input state.

Disable!

Enable!


RegionGetCheck

Enumeration := RegionGetCheck (NamedRgn: String)

 Related Topics  [image]  Example

Reports the state of a check box control.

Return Value

Up!

Down!

Checked!

Unchecked!

Indeterminate!

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.


RegionGetHandle

Numeric := RegionGetHandle (NamedRgn: String)

  Example

Returns the window handle of a named region.

Return Value

If named region does not exist, use OnError to handle error message.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.

If the control ID is not specified, the Window handle of the dialog box is returned.


RegionGetListCount

Numeric := RegionGetListCount (NamedRgn: String)

  Example

Returns the number of items in a list or combo box, or popup button.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.


RegionGetModified

Boolean := RegionGetModified (NamedRgn: String)

  Example

Specifies whether an edit control's contents have been modified (DialogAddCounter, DialogAddDate, DialogAddEditBox, DialogAddFilenameBox).  See RegionSetModified.

Return Value

True if an edit control has been modified, False if not.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.


RegionGetSelectedText

String := RegionGetSelectedText (NamedRgn: String)

 Related Topics  [image]  Example

Assigns selected text to an output variable.

The selected text is in a control such as a list box, combination box, or counter.

Return Value

Output variable contains the selected text.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.


RegionGetWindowText

String := RegionGetWindowText (NamedRgn: String)

 Related Topics  [image]  Example

Gets caption bar, static text, or edit box text.

Return Value

Output variable contains the text.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.   To get the caption bar text, leave off the Control ID or named region.  For example, vText := RegionGetWindowText ("Dialog1").


RegionIsVisible

Boolean := RegionIsVisible (NamedRgn: String)

 Related Topics  [image]  Example

Determines the visibility state of a region or window.

Return Value

The visibility state is returned in this variable: a nonzero number if the window is visible, or 0 if not.  Window's WS_VISIBLE flag determines the return value, which can be nonzero even if the window is hidden by other windows.  See Windows* 95 documentation for more information.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.


RegionMoveWindow

RegionMoveWindow (NamedRgn: String; Left: Numeric; Top: Numeric; Width: Numeric; Height: Numeric)

 Related Topics  [image]  Example

Moves and/or resizes a dialog box or control.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.  To move or resize the dialog box, leave off the Control ID or named region.  For example, RegionMoveWindow ("Dialog1"; ...)

Left: Numeric

Number of dialog units from the left side of the screen to the left side of the dialog box, or number of dialog units from the left side of the dialog box to the left side of the control.

Top: Numeric

Number of dialog units from the top of the screen to the top of the dialog box, or number of dialog units from the top of the dialog box to the top of the control.

Width: Numeric

Width of the dialog box or control in dialog units.

Height: Numeric

Height of the dialog box or control in dialog units.


RegionRemoveListItem

RegionRemoveListItem (NamedRgn: String; Item: String)

 Related Topics  [image]  Example

Removes a list item from a list box, combination box, or popup button.  Exact match items are removed before partial match items.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.

Item: String

A list item.


RegionResetList

RegionResetList (NamedRgn: String)

 Related Topics  [image]  Example

Clears the contents of a list box, combination box, or popup button.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.


RegionSelectListItem

RegionSelectListItem (NamedRgn: String; Item: String)

 Related Topics  [image]  Example

Selects an item in a list box, combination box, or popup button.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.

Item: String

A list item.


RegionSetBitmapFilename

RegionSetBitmapFilename (NamedRgn: String; Filename: String)

Sets a new bitmap file in a bitmap control.

Example

APPLICATION(A1; "WordPerfect"; Default; "US")

OnError (ErrorMsg)

DialogDefine ("Dialog1"; 50; 50; 200; 100; Percent! | OK! | Cancel!; "Dialog Example")

DialogAddPushButton("Dialog1"; "PushBttn1"; 153; 35; 38; 14; NonDefaultBttn!; "Add Ctrl 1")

DialogAddPushButton("Dialog1"; "PushBttn2"; 153; 55; 38; 14; NonDefaultBttn!; "Add Ctrl 2")

DialogShow ("Dialog1"; "WordPerfect"; Msg)

CallbackWait

Quit

Label(Msg)

If (Msg[5] = 274)

DialogDestroy ("Dialog1")

CallbackResume

Return

Endif

Switch (Msg[3])

CaseOf "OKBttn": MessageBox(x; "OK Button"; "You pressed OK"; IconInformation!)

CaseOf "CancelBttn":

DialogDestroy("Dialog1")

CallBackResume

Return

CaseOf "PushBttn1":

DialogAddBitmap ("Dialog1"; "BCtrl"; 10; 10; 50; 50; SizeBmpToCtl!; "c:\windows\cars.bmp")

CaseOf "PushBttn2":

RegionSetBitmapFilename ("Dialog1.BCtrl"; "c:\windows\arcade.bmp")

EndSwitch

Return

Label (ErrorMsg)

MessageBox (x; "Error"; "You pressed Add Ctrl 2 before Add Ctrl 1"; IconInformation!)

Quit

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.

Filename: String

Include full path and filename.


RegionSetCheck

RegionSetCheck (NamedRgn: String; State: Enumeration)

 Related Topics  [image]  Example

Selects/deselects a check box.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.

State: Enumeration

Sets the state of a check box control.

Unchecked!

Check!

Gray! Check box control must be Three-state or Auto three-state.  See DialogAddCheckBox.


RegionSetFocus

RegionSetFocus (NamedRgn: String)

 Related Topics  [image]  Example

Gives input focus to a specified control.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.


RegionSetModified

RegionSetModified (NamedRgn: String; State: Enumeration)

Sets the modified state of an edit control (DialogAddCounter, DialogAddDate, DialogAddEditBox, DialogAddFilenameBox).  See RegionGetModified.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.

State: Enumeration

Modified!

NotModified!


RegionSetProgressPercent

RegionSetProgressPercent (NamedRgn: String; Percent: Numeric)

  Example

Sets the percentage to display in a progress control.  See DialogAddProgress.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.

Percent: Numeric

Percentage to set.


RegionSetWindowText

RegionSetWindowText (NamedRgn: String; Item: String)

 Related Topics  [image]  Example

Replaces caption bar, static text, or edit box text.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.  To replace the caption bar text, leave off the Control ID or named region.  For example, RegionSetWindowText ("Dialog1")

Item: String

Replacement text.


RegionShowWindow

RegionShowWindow (NamedRgn: String; State: Enumeration)

 Related Topics  [image]  Example

Shows/hides a dialog box or control.

Parameters

NamedRgn: String

Dialog ID and control ID, or Dialog ID and name of a named region.  Enclose IDs in double quotation marks, separated by a period.  If you do not use the control ID, the command works on the dialog box.

State: Enumeration

The display state.

Hide!

Show!

ShowMinimized!

ShowMaximized!

Maximize!

ShowNoActivate!

Normal!

ShowNormal!

Minimize!

ShowMinNoActive!

ShowNA!

ShowRestore!

ShowDefault!


RegistryCloseKey

Numeric := RegistryCloseKey (Hkey: Numeric)

Closes an open key in the Windows* Registry.

Return Value

0 if successful, an error code if not.

Example

RegKey = RegistryOpenKey(LocalMachine!; "Software\PerfectOffice\PerfectScript\7\Location of Help Files\US")

RegistryCloseKey(RegKey)

Parameters

Hkey: Numeric

Handle of key to close.


RegistryCreateKey

Numeric := RegistryCreateKey (Hkey: Enumeration; SubKey: String)

Creates or opens a key in the Windows* Registry.

Example

RegKey = RegistryOpenKey(LocalMachine!; "Software\PerfectOffice\PerfectScript\7\")

CreateKey:= RegistryCreateKey(RegKey; "MyKey")

Prompt("RegistryCreateKey"; CreateKey;)

Pause

Parameters

Hkey: Enumeration

ClassesRoot!

CurrentUser!

LocalMachine!

Users!

SubKey: String


RegistryDeleteKey

Numeric := RegistryDeleteKey (Hkey: Numeric; SubKey: String)

Deletes a key from the Windows* Registry.

Example

RegKey = RegistryOpenKey(LocalMachine!; "Software\PerfectOffice\PerfectScript\7\")

DeleteKey:= RegistryDeleteKey(RegKey; "MyKey")

Prompt("RegistryDeleteKey"; DeleteKey;)

Pause

Parameters

Hkey: Numeric

SubKey: String


RegistryDeleteValue

Numeric := RegistryDeleteValue (Hkey: Numeric; Value: String)

Deletes a value from the Windows* Registry.

Example

RegKey = RegistryOpenKey(LocalMachine!; "SOFTWARE\PerfectOffice\PerfectScript\7\My Key\My Other SubKey")

DeleteValue:=RegistryDeleteValue(RegKey; )

Prompt("RegistryDeleteValue";DeleteValue;)

Pause

Parameters

Hkey: Numeric

Value: String


RegistryEnumKey

String := RegistryEnumKey (Hkey: Numeric; SubKeyNumber: Numeric)

Enumerates a key from the Windows* Registry.

Example

RegKey = RegistryOpenKey(LocalMachine!; "Software\PerfectOffice\PerfectScript\7")

EnumString:=RegistryEnumKey(RegKey; 100)

RegError = RegistryQueryLastError()

Prompt("RegistryEnumKey"; "RegistryEnumKey was "+EnumString+".  RegistryQueryLastError was "+RegError+".")

Pause

Parameters

Hkey: Numeric

SubKeyNumber: Numeric


RegistryEnumValue

String := RegistryEnumValue (Hkey: Numeric; ValueNumber: Numeric)

Enumerates a value from the Windows* Registry.

Example 1

RegKey = RegistryOpenKey(LocalMachine!; "Software\PerfectOffice\PerfectScript\7\Applications")

EnumString:=RegistryEnumValue(RegKey; 1)

Prompt("RegistryEnumValue"; EnumString)

Pause

Example 2

//Test RegistryEnumValue with errors

RegKey = RegistryOpenKey(CurrentUser!; "Software\PerfectOffice\PerfectScript\7\Macro Help Files")

EnumString:=RegistryEnumValue(RegKey; 25)

RegKey:= RegistryQueryLastError()

Prompt("RegistryEnumValue Failure"; EnumString; Pause!)

Prompt("RegistryQueryLastError"; RegKey)

Pause

Parameters

Hkey: Numeric

ValueNumber: Numeric


RegistryOpenKey

Numeric := RegistryOpenKey (Hkey: Enumeration; SubKey: String)

Opens a key in the Windows* Registry.

Example

RegKey = RegistryOpenKey(LocalMachine!; "Software\PerfectOffice\PerfectScript\7\Location of Help Files")

Parameters

Hkey: Enumeration

ClassesRoot!

CurrentUser!

LocalMachine!

Users!

SubKey: String


RegistryQueryKeyCount

Numeric := RegistryQueryKeyCount (Hkey: Numeric)

Returns count of subkeys under a key in the Windows* Registry.

Example

RegKey = RegistryOpenKey(LocalMachine!; "Software\PerfectOffice\PerfectScript\")

KeyCount:=RegistryQueryKeyCount(RegKey)

Prompt("RegistryQueryKeyCount"; KeyCount)

Pause

Parameters

Hkey: Numeric


RegistryQueryLastError

Numeric := RegistryQueryLastError()

Returns count of subkeys under a key in the Windows* Registry.

Example

RegKey:= RegistryQueryLastError()

Prompt("RegistryQueryLastError"; RegKey)

Pause


RegistryQueryValue

Any := RegistryQueryValue (Hkey: Numeric; Value: String; Type: Variable)

Obtains a value from the Windows* Registry.

Example

RegKey = RegistryOpenKey(LocalMachine!; "SOFTWARE\PerfectOffice\PerfectScript\7\PIDS")

QueryString:=RegistryQueryValue(RegKey; "PerfectScript")

Prompt("RegistryQueryValue"; QueryString)

Pause

Parameters

Hkey: Numeric

Value: String

Type: Variable


RegistryQueryValueCount

Numeric := RegistryQueryValueCount (Hkey: Numeric)

Returns count of values under a key in the Windows* Registry.

Example

RegKey = RegistryOpenKey(LocalMachine!; "Software\PerfectOffice\PerfectScript\7\Location of Help Files")

QueryKey=RegistryQueryValueCount(RegKey)

Prompt("RegistryQueryValueCount"; QueryKey)

Pause

Parameters

Hkey: Numeric


RegistrySetValue

Numeric := RegistrySetValue (Hkey: Numeric; Value: String; Data: Any; Type: Enumeration)

Saves a value in the Windows* Registry.

Example 1

RegKey = RegistryOpenKey(LocalMachine!; "Software\PerfectOffice\PerfectScript\7\MyKey")

//CreateKey:= RegistryCreateKey(RegKey; "My SubKey")

SetKey:=RegistrySetValue(RegKey; "My SubKey"; "Working"; PFString!)

Prompt("RegistrySetValue - PFString!"; "If RegistrySetValue was successful this should be a zero: "+SetKey;)

Pause

Example 2

CreateKey:= RegistryCreateKey(RegKey; "My Other SubKey")

SetKey:=RegistrySetValue(RegKey; "My Other SubKey"; "Really Working"; PFDWord!)

Prompt("RegistrySetValue - PFDWord!"; "If RegistrySetValue was successful this should be a zero: "+SetKey;)

Pause

Example 3

CreateKey:= RegistryCreateKey(RegKey; "My Other Other SubKey")

SetKey:=RegistrySetValue(RegKey; "My Other Other Key"; "It's Working"; DWord!)

Prompt("RegistrySetValue - DWord!"; "If RegistrySetValue was successful this should be a zero: "+SetKey;)

Pause

Parameters

Hkey: Numeric

Value: String

Data: Any

Type: Enumeration

Binary! Free form binary.

DWord! 32-bit number.

String! Null-terminated string.

ExpandableString! Null-terminated string with environment variable references.

PFBinary! Free form binary.

PFDWord! 32-bit number.

PFString! Null-terminated string.

PFExpandableString!

PFWPString! WordPerfect* word string.

PFByte! 8-bit number.

PFWord! 16-bit number.

PFBool! Boolean.


RenameDirectory

Boolean := RenameDirectory (OldDirectoryName: String; NewDirectoryName: String; Prompts: Enumeration)

 Related Topics  [image]  Example

Renames a directory.

Return Value

True if successful, False if not.

Parameters

OldDirectoryName: String

Include full path.

NewDirectoryName: String

Include full path.

Prompts: Enumeration (optional)

Default: NoPrompts!

NoPrompts!

Prompts! Prompt if directory does not exist.


RenameFile

Boolean := RenameFile (OldFilename: String; NewFilename: String; Prompts: Enumeration)

 Related Topics  [image]  Example

Renames and/or moves a file.

Return Value

True if successful, False if not.

Parameters

OldFilename: String

Include full path.

NewFilename: String

Include full path.

Prompts: Enumeration

Default: NoPrompts!

NoPrompts!

Prompts! Prompt if old file does not exist, or path is incorrect.


Repeat

 Related Topics  [image]  Example

A loop statement that executes until the expression at the bottom of the loop is true (see Using Loop Statements).

The loop executes at least once, because it is not tested until the bottom of the loop.  When <Test> is true, the first statement after Until is executed.

Syntax

The general form of a Repeat statement is:

Repeat

...statement block...

Until (<Test> Boolean)

Parameters

<Test> Boolean

Evaluates to true or false.


Return

Return (<Condition> Enumeration; <Value> Any)

 Related Topics  [image]  Example

Ends Label, Function, and Procedure subroutines, or a macro (see Run), and then directs macro execution to the statement that follows the subroutine or macro's caller, or creates a Cancel, Error, or Not Found condition.

Return generally ends a Label statement called by statements such as Call or Case Call.

Call(StartMacro)

Call(QuitMacro)

Label(StartMacro)

... statement block...

Return // directs macro execution to Call(QuitMacro)

Label(QuitMacro)

Quit

If there is no caller to return to, and the macro containing Return is nested (called by another macro), Return directs macro execution to the statement that follows the macro's caller (see Run).  Return ends a macro if there is no caller to return to, and the macro containing the Return statement is not nested.

Parameters

<Condition> Enumeration (optional)

Creates a Cancel, Error, or Not Found condition (see Assert).  <Condition> stops a macro unless preceded by OnCancel, OnError, or OnNotFound, which direct macro execution to a specified Label.  <Condition> has no effect when preceded by Cancel(Off!), Error(Off!), or NotFound(Off!).  The enumerations (return types) are:

CancelCondition! (Stops a macro unless preceded by OnCancel.)

ErrorCondition! (Stops a macro unless preceded by OnError.)

NotFoundCondition! (Stops a macro unless preceded by OnNotFound.)

<Value> Any (optional)

Returns the result of a function operation (see Function).


Return

Return (<Value> Any)

Ends Label, Function, and Procedure subroutines, or a macro (see Run), and then directs macro execution to the statement that follows the subroutine or macro's caller.

Return generally ends a Label statement called by statements such as Call or Case Call.

Call(StartMacro)

Call(QuitMacro)

Label(StartMacro)

... statement block...

Return // directs macro execution to Call(QuitMacro)

Label(QuitMacro)

Quit

If there is no caller to return to, and the macro containing Return is nested (called by another macro), Return directs macro execution to the statement that follows the macro's caller (see Run).  Return ends a macro if there is no caller to return to, and the macro containing the Return statement is not nested.

Parameters

<Value> Any (optional)

Returns the result of a function operation (see Function).


RoundOff

Any := RoundOff (Value: Any; RoundTo: Any)

Return a value rounded to number of digits.

Example

vResult := RoundOff(12.63; 0.75)

Result: vResult equals 12.75

Parameters

Value: Any

Value to round off.

RoundTo: Any (optional)

Round Value to the nearest multiple of this number.  Default: 1.0


Run

Run (MacroFile: String; {Parameter: Any})

 Related Topics  [image]  Example

Calls (starts) a nested macro.

A nested macro starts immediately when it is called.  When a nested macro ends, control returns to the calling macro.  If Quit ends a nested macro, control does not return to the calling macro.

PerfectScript automatically compiles uncompiled Run macros.  Macro execution stops if the macro will not compile.

Parameters

MacroFile: String

The path and name of a compiled macro.

{Parameter: Any} (optional)

Enclose multiple parameters in braces ({}), separated by a semicolon.  For example: Run ("macro"; {"a"; "b"; "c"})  For example: Run ("macro"; {"a"; "b"; "c"}).  Parameter values are passed to a special array variable named MacroArgs.

If missing, MacroArgs[] is not defined in the new macro.


SendKeys

SendKeys (KeyCode: String; MarkupLanguage: Enumeration)

Sends 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 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 WordPerfect* Open File dialog box.

Note

In WordPerfect, set InhibitInput(Off!) for SendKeys to operate correctly.

Parameters

KeyCode: String

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}

{Dn}

{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)

Specifies which language interprets the key codes.  Default: New! The values are:

Old!

New!


SetCurrentDirectory

Boolean := SetCurrentDirectory (DirectoryName: String)

 Related Topics  [image]  Example

Specifies new default directory.

Return Value

True if successful, False if not.

Parameters

DirectoryName: String

Include full path.


SetFileAttributes

Boolean := SetFileAttributes (Filename: String; Attributes: Enumeration; Prompts: Enumeration)

 Related Topics  [image]  Example

Changes file attributes.

Return Value

True if successful, False if not.

Parameters

Filename: String

Attributes: Enumeration (optional)

Default: Normal!

Normal!

ReadOnly!

Hidden!

System!

Label!

Directory!

Archived!

Prompts: Enumeration (optional)

Prompts if attribute does not exist. Default: NoPrompts!

NoPrompts!

Prompts!


SetFileDateAndTime

Boolean := SetFileDateAndTime (Filename: String; DateAndTime: Numeric)

 Related Topics  [image]  Example

Changes the date and time a file was last written to.

Return Value

True if successful, False if not.

Parameters

Filename: String

Include full path and filename.

DateAndTime: Numeric

This value is returned from DateAndTime.


Sign

Numeric := Sign (Value: Numeric)

Returns the sign of a value.

Return Value

Sign returns -1 if Value is less than 0, 0 if Value equals 0, and 1 if Value is greater than 0.

Parameters

Value: Numeric

Return sign of this value.


sin

Numeric := sin (Angle: Numeric)

Returns the sine of an angle in radians.

Parameters

Angle: Numeric

Angle in radians.


sinh

Numeric := sinh (Angle: Numeric)

Returns the hyperbolic sine of an angle in radians.

Parameters

Angle: Numeric

Angle in radians.


SizeOf

Numeric := SizeOf (Value: Any)

Returns the size needed to store the specified data value.

This command is mostly used with BinaryPack and BinaryUnpack.

Parameters

Value: Any (optional)

Value to compute the size of.  If missing, the size of the PerfectScript system overhead for storing a value is returned.


Speed

Speed (TenthsOfSeconds: Numeric)

 Related Topics  [image]  Example

Slows 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

Parameters

TenthsOfSeconds: Numeric

A number from zero to 600.  Divide the number by 10 to calculate the number of seconds.


SquareRoot

Numeric := SquareRoot (Value: Numeric)

Returns the square root of a value.

Parameters

Value: Numeric

Value must be greater than or equal to 0.0.


Step

Step (State: Enumeration)

Turns on Macro Debugger single stepping.

See PerfectScript for Help on the debugger itself.

Parameters

State: Enumeration

Off!

On!


StrFill

String := StrFill (Count: Numeric; String: String)

Fill (duplicate) a string a specified number of times.

Return Value

Duplicated string.

Examples

vStr := StrFill (2; "PerfectScript")

MessageBox (x; "StrFill"; "..." + vStr + "...")

Result: ...PerfectScriptPerfectScript...

vStr := StrFill (2)

MessageBox (x; "StrFill"; "..." + vStr + "...")

Result: ...  ...

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

Numeric := StrFraction (String: String)

 Related Topics

Returns the numeric value of a string representing a fraction.

Examples

vFrac := StrFraction ("1/2")

Result: vFrac = 0.5

vFrac := StrFraction ("187 7/8")

Result: 187.875

Parameters

String: String

String to convert.  The form of the string is "n/n" or "n n/n".


String

String := String (<Value> String)

Passes value as an ANSI string (DLL call in-line parameter function).  See DLLCall.


StrInsert

String := StrInsert (String: String; SubString: String; Beginning: Numeric; NumberOfChars: Numeric)

Inserts a substring into a string, replaces characters in a string, or removes 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...

Parameters

String: String

Original string.

SubString: String (optional)

String to insert into String.  If missing, characters are removed from String.

Beginning: Numeric (optional)

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 example above.

NumberOfChars: Numeric (optional)

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 replaced by SubString or removed.


StrIsChar

Boolean := StrIsChar (String: String; Position: Numeric; Option: Enumeration; CharSet: String or Enumeration)

Specifies whether a string or character is of a specified type.

Return Value

True if String is of type CharSet, or False if not.

Parameters

String: String

String to test.

Position: Numeric (optional)

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)

Specifies matching criteria.  If missing, EqualTo! is used.  If CharSet is also missing, NotEqualTo! is used and WhiteSpace! is used for CharSet.

EqualTo! Tests for a character in the specified character set.

NotEqualTo! Tests for a character that is not in the specified character set.

CharSet: String or Enumeration (optional)

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

String := StrLeft (String: String; Length: Numeric)

Returns the left part of a string.

Examples

vStr := StrLeft ("Corel Corporation"; 5)

MessageBox (x; "StrLeft"; "..." + vStr + "...")

Result: ...Corel...

vStr := StrLeft ("Corel Corporation    ")

MessageBox (x; "StrLeft"; "..." + vStr + "...")

Result: ...Corel Corporation...

Parameters

String: String

Original string.

Length: Numeric (optional)

Length of string to return from the left 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.


StrLen

Numeric := StrLen (String: String)

 Related Topics  [image]  Example

Returns the number of characters in a string.

The string can be a variable, constant, character string, or result of an expression.

Examples

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

Return Value

The number of characters in a string.

Parameters

String: String

A variable, constant, character string, or result of an expression.


StrNum

String := StrNum (String: String)

 Related Topics  [image]  Example

Converts a character string of numbers to a numeric equivalent.

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

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

String := StrPad (String: String; Length: Numeric; Option: Enumeration; PadString: String)

Pads (lengthens) 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

Parameters

String: String

String to be padded.

Length: Numeric

Final length of padded string.  If length is less than or equal to zero, or less than the length of String, the original string is returned.

Option: Enumeration (optional)

Specifies 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 padding between words, expanding String to 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 (is not limited to a single character).  If missing, spaces are used.  If the string is empty (""), no padding is done. See examples above.


StrPos

Numeric := StrPos (String: String; SubString: String; Beginning: Numeric)

 Related Topics  [image]  Example

Determines whether a character string is also a substring.

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 first occurrence of substring.

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 example above).


StrReverse

String := StrReverse (String: String)

Reverses all characters in a string.

Return Value

String in reverse character order.

Parameters

String: String

Original string.


StrRight

String := StrRight (String: String; Length: Numeric)

Returns the right part of a string.

Examples

vStr := StrRight ("Corel Products"; 8)

MessageBox (x; "StrRight"; "..." + vStr + "...")

Result: ...Products...

vStr := StrRight ("   Corel Products")

MessageBox (x; "StrRight"; "..." + vStr + "...")

Result: ...Corel Products...

Parameters

String: String

Original string.

Length: Numeric (optional)

Length of 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

Numeric := StrScan (String: String; Beginning: Numeric; Option: Enumeration; CharSet: String or Enumeration)

Returns 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).

Parameters

String: String

String to scan.

Beginning: Numeric (optional)

Position at which to start 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)

Specifies matching criteria.  If missing, EqualTo! is used.  If CharSet is also missing, NotEqualTo! is used and WhiteSpace! is used for CharSet.

EqualTo! Scans until a character in the specified character set is found.

NotEqualTo! Scans until a character not in the specified character set is found.

CharSet: Any (optional)

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

String := StrToChars (String: String; Option: Enumeration; CharSet: String or Enumeration)

Removes characters from a string.

Return Value

Replacement 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

Parameters

String: String

Original string.

Option: Enumeration (optional)

Specifies 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)

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

String := StrTransform (String: String; FromChars: String; ToChars: String)

Transforms a string of characters into other characters.

Return Value

Replacement string.

Parameters

String: String

String to transform.

FromChars: String

Characters in String to transform.

ToChars: String (optional)

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.


StrTrim

String := StrTrim (String: String; Length: Numeric; Option: Enumeration; TrimChars: String or Enumeration)

Trims (removes) characters from a string.

Return Value

String trimmed of characters to a specified length.

Parameters

String: String

String to be trimmed.

Length: Numeric (optional)

Final length of 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 Options).  If the length of String after trimming exceeds Length, no further trimming is done.

Option: Enumeration (optional)

Specifies 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)

Characters to be trimmed from String (all matching characters from 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

String := Structure (<Value> String)

Passes a value as a C struct (DLL call in-line parameter function).  See DLLCall.


StrUnit

Numeric := StrUnit (String: String)

 Related Topics  [image]  Example

Converts 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.

Examples

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)

Return Value

A unit of measure.

Parameters

String: String

A number or character string of numbers.


SubChar

String := SubChar (String: String; Beginning: Numeric; NumberOfChars: Numeric)

 Related Topics  [image]  Example

Extracts a substring from a character string.

Use CharPos to locate a substring.

Return Value

A character string.

// vSub = "Word"

vSub := SubChar("WordPerfect"; 1; 4)

Parameters

String: String

A character string to evaluate.

Beginning: Numeric

The starting position of a substring.

NumberOfChars: Numeric

The number of characters to extract.


SubStr

String := SubStr (String: String; Beginning: Numeric; NumberOfChars: Numeric)

 Related Topics  [image]  Example

Extracts a substring from a character string.

Use StrPos to locate a substring.

Return Value

A character string.

// vSub = "Word"

vSub := SubStr("WordPerfect"; 1; 4)

Parameters

String: String

A character string to evaluate.

Beginning: Numeric

The starting position of a substring.

NumberOfChars: Numeric

The number of characters to extract.


Sum

Numeric := Sum ({Value: Numeric})

Returns the sum of a list of values.

Parameters

Value: Numeric

List of values.  Separate multiple values with a semicolon.


Switch

Switch (<Test> Any)

 Related Topics  [image]  Example

A conditional statement that tests for matching expressions.  If a match is found, a statement (or statement block) is executed.  See Using Conditional 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>; <Selector>:

...statement block...

Default:

...statement block...

EndSwitch

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.


tan

Numeric := tan (Angle: Numeric)

Returns the tangent of an angle in radians.

Parameters

Angle: Numeric

Angle in radians


tanh

Numeric := tanh (Angle: Numeric)

Returns the hyperbolic tangent of an angle in radians.

Parameters

Angle: Numeric

Angle in radians


TimeHour

Numeric := TimeHour (Time: Numeric)

Returns a number representing the hour on a 24-hour clock.

Parameter

Time: Numeric (optional)

If missing, the current system time is used.


TimeHundredth

Numeric := TimeHundredth (Time: Numeric)

Returns a number representing hundredths of a second.

Parameter

Time: Numeric (optional)

If missing, the current system hundredths of a second is used.


TimeMinute

Numeric := TimeMinute (Time: Numeric)

Returns a number representing the minute.

Parameter

Time: Numeric (optional)

If missing, the current system minute is used.


TimeSecond

Numeric := TimeSecond (Time: Numeric)

Returns a number representing the second.

Parameter

Time: Numeric (optional)

If missing, the current system second is used.


TimeString

String := TimeString (Time: Numeric; Format: String)

Returns the time in a string.

Example

vCurrentTime := TimeString (; "h:m:ss tt")

MessageBox (x; "TimeString"; vCurrentTime)

Result (format): 3:52:34 PM

Parameter

Time: Numeric (optional)

If missing, the current system time is used.

Format: String (optional)

Specifies a time string format.  If missing, the current Windows* Control Panel format is used.  See example above.

Hours

h (hours without leading zeros for single digit hours-12 hour clock)

hh (hours with leading zeros for single digit hours-12 hour clock)

H (hours without leading zeros for single digit hours-24 hour clock)

HH (hours with leading zeros for single digit hours-24 hour clock)

Minutes

m (minutes without leading zeros for single digit numbers)

mm (minutes with leading zeros for single digit minutes)

Seconds

s (seconds without leading zeros for single digit seconds)

ss (seconds with leading zeros for single digit seconds)

Time Marker

t (one character time marker: 'a' or 'p')

tt (multi-character time marker: 'am' or 'pm')


ToInitialCaps

String := ToInitialCaps (String: String; Style: Enumeration)

Capitalizes the first character in a string, or the first character of the words in a string.

Return Value

Mixed case equivalent of a specified string.

Parameters

String: String

String to convert.

Style: Enumeration (optional)

Default: FirstOfEachWord!

FirstCharOnly! Capitalize the first character in the string.

FirstOfEachWord! Capitalize the first character of every word in the string.


ToLower

String := ToLower (String: String)

 Related Topics  [image]  Example

Converts uppercase letters to lowercase.

The value returned by ToLower can be assigned to a variable or used directly by a statement such as If.

Example

vAnswer := "YES"

vAnswer := ToLower(vAnswer)

Result: vAnswer equals lowercase yes

Shorthand notation example

If(ToLower(vAnswer) = "yes")

Beep

Else

Quit

EndIf

Explanation: Beep if vAnswer equals lowercase yes.

Return Value

The lowercase equivalent of uppercase letters.

Parameters

String: String

A string to convert.


ToUpper

String := ToUpper (String: String)

 Related Topics  [image]  Example

Converts lowercase letters to uppercase.

The value returned by ToUpper can be assigned to a variable or used directly by a statement such as If.

Example

vAnswer := "yes"

vAnswer := ToUpper(vAnswer)

Result: vAnswer equals uppercase YES

Shorthand notation example

If(ToUpper(vAnswer) = "YES")

Beep

Else

Quit

EndIf

Explanation: Beep if vAnswer equals uppercase YES.

Return Value

The uppercase equivalent of lowercase letters.

Parameters

String: String

A string to convert.


UnitStr

String := UnitStr (Value: Any; Units: Enumeration)

 Related Topics  [image]  Example

Converts a measurement to a character string.

If a unit of measure is not specified, the default is WordPerfect* units.  To change the default, use DefaultUnits.  The following example converts WP units to centimeters and returns the result as a string:

Units := UnitStr(1200; Centimeters!)

Result: vUnits equals "2.540000C"

The next example converts centimeters to millimeters and returns the result as a string:

DefaultUnits(Centimeters!)

vUnits := UnitStr(1.0; Millimeters!)

Result: vUnits equals "10.000000M"

The next example converts inches to centimeters and returns the result as a string:

vUnits := UnitStr(2.0i; Centimeters!)

Result: vUnits equals "5.080000C"

See StrUnit to convert a string of numbers to a measurement expression.

Return Value

A measurement expressed as a string.

Parameters

Value: Any

A real number measurement.  Unless you specifiy a unit of measure, the default is WP Units.  To change the default, use DefaultUnits.

Units: Enumeration

The unit of measure that Value converts to.

Centimeters!

Inches!

Millimeters!

Points! (72 per inch)

WPUnits! (1200 per inch)

WP1200ths! (1200 per inch)


Until

Until (<Test> Boolean)

  Example

Specifies the condition for closing a Repeat control loop.  See Repeat.


Use

Use (<MacroFile> String)

 Related Topics  [image]  Example

Specifies a macro file with functions and/or procedures that can be called from another macro.

Use is a non-executable statement that can occur anywhere in a macro.  A macro with a calling statement to a function or procedure in another macro file must include a Use statement that identifies the file.

A Use macro file that includes only function and/or procedure statements must be compiled like any macro file (see Macro File Libraries).  PerfectScript automatically compiles uncompiled Use macros.  Macro execution stops if the macro will not compile.

Macro files identified by multiple Use statements are searched from first to last.  Thus a parent macro always calls the first occurrence of a function or procedure with the same name in different Use files.

Parameters

<MacroFile> String

The path and name of a macro file.  You cannot substitute String with a variable.


Value

Any := Value (<Value> Any)

Returns the value of an enumeration or the internal product command ID value for a command.

Parameters

<Value> Any

An enumeration or command.

Notes

If specifying a product command name, do not enclose the command in quotes.  For example, x := Value(MessageBox).

If specifying a product command parameter enumeration, use the product command name, a period, the parameter name, a period, and the enumeration.  For example, x := Value(MessageBox.Style.OKCancel!).

If using this command to obtain the value of a product command return enumeration value, specify the product command name, a period, and the return enumeration name.  For example, x := Value(PersistAll.On!).

Using Value to obtain enumeration values is optional.  The following syntax is also correct: x := MessageBox.Style.OKCancel! or x := PersistAll.On!


ValueType

Enumeration or Boolean := ValueType (Value: Any; Type: Enumeration)

Returns data type information about a variable or a value.

Return Value

If Type is specified, then True if Value is of the specified Type, or False if not.  If Type if not specified, the actual data type of Value is returned as an Enumeration. The possible enumerations are:

Boolean!

WPString!

AnsiString!

OemString!

Float!

Integer!

Centimeters!

Inches!

Millimeters!

Points!

WPUnits!

Examples

Declare vNmbr = 10.0

If (ValueType.Type.Float!)

MessageBox (x; "ValueType"; ValueType (vNmbr; Float!)

Endif

Result: MessageBox displays True

If (ValueType(vNmbr) = ValueType.Type.Integer!)

Beep

Else

MessageBox (x; "ValueType"; "vNmbr is not an integer value")

Endif

Result: MessageBox displays "vNmbr is not an integer value"

Parameters

Value: Any

Value to be tested (any valid expression including a variable name).

Type: Enumeration (optional)

Type to test for.  True if Value is of the specified Type, or False if not.  If missing, the data type of Value is returned.

Boolean! Value must be a boolean value.

String! Includes WPString, AnsiString, and OemString.

WPString! WordPerfect* string.

AnsiString! Ansi string.

OemString! OEM string.

Numeric! Includes all Number! and Measurement! types.

Number! Includes Float! and Integer!

Float! Floating point value.

Integer! Integer value.

Measurement! Includes Centimeters!, Inches!, Millimeters!, Points! and WPUnits!.

Centimeters! Centimeters measurement value.

Inches! Inches measurement value.

Millimeters! Millimeters measurement value.

Points! Points measurement value.

WPUnits! WP Units measurement value.


VarErrChk

Enumeration := VarErrChk (State: Enumeration)

 Related Topics  [image]  Example

Determines how a macro responds to uninitialized variables, or variables not assigned a value.

Return Value

Off! Previous VarErrChk state was Off!

On! Previous VarErrChk state was On!

Parameters

State: Enumeration (optional)

Specifies the state of variable checking.  The default is VarErrChk(On!).  If missing, the current state is returned without changing it.

Off! Ignore uninitialized variables by temporarily assigning a value of 0.

On! Display a run-time Error message when a macro attempts to use an uninitialized  variable, and end the macro.


Wait

Wait (TenthsOfSeconds: Numeric)

 Related Topics  [image]  Example

Pauses macro execution.

Time is measured in tenths of a second.  The maximum pause is one minute, or Wait(600).

Parameters

TenthsOfSeconds: Numeric

A number from zero to 600.  Divide the number by 10 to calculate the number of seconds.


While

While (<Test> Boolean)

 Related Topics  [image]  Example

A loop statement that executes while the expression at the top of the loop is true (see Using Loop Statements).

The loop does not execute the first time unless Test is true.  When Test is false, the first statement after EndWhile is executed.

Syntax

The general form of a While statement is:

While (<Test> Boolean)

...statement block...

EndWhile

Parameters

<Test> Boolean

Evaluates to true or false.


WordCount

Numeric := WordCount (String: String; WordLength: Numeric; SeparatorChars: String; Option: Enumeration)

Counts the words in a string.

Return Value

Number of words in a string.

Parameters

String: String

String containing words.

WordLength: Numeric (optional)

Length of words to count.  If missing, or less than or equal to zero, all words are counted.

SeparatorChars: String (optional)

Character(s) used to separate words.  If missing, white space characters are used.

Option: Enumeration (optional)

Type of counting to perform.  If missing, the value of WordLength determines which words are counted.  Default: CountWords!

CountWords! See WordLength parameter.

CountShorter! Count words shorter than specified length.

CountLonger! Count words longer than specified length.

ShortestLength! Return the length of the shortest word (ignore WordLength).

LongestLength! Return the length of the longest word (ignore WordLength).

AverageLength! Return the average word length (ignore WordLength).


WPString

String := WPString (<Value> String)

Passes value as a WordPerfect* string (DLL call in-line parameter function).  See DLLCall.


XOR

Boolean := Boolean XOR Boolean

Combines two relationship expressions.

Returns TRUE if only one expression is true, or FALSE if both are true or both are false.  See Logical Operators and Logical Expressions.


example 8001

APPLICATION(A1; "WordPerfect"; Default; "US")// Execute Windows* Calculator

// Locate and activate 3 times

// Demonstrate APPEXECUTE command

ASSIGN(hWP; APPLOCATE("*"))

APPEXECUTE("c:\windows\calc.exe")

ASSIGN(hCalc; APPLOCATE("Calculator"))

FORNEXT(vCtrl; 1; 2; 1)

WAIT(10)

APPACTIVATE(hWP)

WAIT(10)

APPACTIVATE(hCalc)

ENDFOR


example 8002

APPLICATION(A1; "WordPerfect"; Default; "US")// Display message box on ASSERT condition

// Demonstrate ASSERT command

ONCANCEL(Condition)

ONERROR(Condition)

ONNOTFOUND(Condition)

LABEL(Start)

MENU(vPick; Digit!; ; ; {"Assert Cancel"; "Assert Error"; "Assert Not Found"; "Quit"})

SWITCH(vPick)

CASEOF 1: ASSERT(CancelCondition!)

CASEOF 2: ASSERT(ErrorCondition!)

CASEOF 3: ASSERT(NotFoundCondition!)

CASEOF 4: QUIT

DEFAULT: GO(Condition)

ENDSWITCH

LABEL(Condition)

SWITCH(ErrorNumber)

CASEOF 1: vMsg := "1 (Cancel condition)"

CASEOF 2: vMsg := "2 (Error condition)"

CASEOF 7: vMsg := "3 (Not Found condition)"

DEFAULT: vMsg := "?"

ENDSWITCH

MESSAGEBOX(vStatus; "ASSERT COMMAND"; "You selected " + vMsg; IconInformation!)

GO(Start)


example 8000

APPLICATION (A1; "WordPerfect"; Default; "US")// Execute Windows* Cardfile three times: full screen, normal size, and to an icon

// FORNEXT decrements initial value

// Demonstrate APPEXECUTEEXT command

FORNEXT(vCtrl; 3; 1; -1)

ASSIGN(vReturn; APPEXECUTEEXT("c:\windows\cardfile.exe"; vCtrl))

IF(vReturn < 32)

BEEP

MESSAGEBOX(vStatus; "ERROR"; "Unable to execute Cardfile.exe"; IconExclamation!)

QUIT

ENDIF

 WAIT(3)

ENDFOR


example 8004
APPLICATION(A1; "WordPerfect"; Default; "US")

// Test user input

// Remember: procedures do not execute unless called

// Demonstrate GETNUMBER, PROCEDURE, and PROCEDURE PROTOTYPE commands

PROCEDURE PROTOTYPE ErrorMsg(x)

REPEAT

GETNUMBER(vNum; "Enter a number from 1 to 5"; "GETNUMBER EXAMPLE")

IF((vNum < 1) OR (vNum > 5))

CALL ErrorMsg(vNum)

ELSE

MESSAGEBOX(vStatus; "YES!"; "You entered " + vNum; IconInformation!)

ENDIF

UNTIL((vNum > 0) AND (vNum < 6))

PROCEDURE ErrorMsg(x)

BEEP BEEP BEEP

IF(x < 1)

vMessage := x + " is less than 1"

ELSE

vMessage := x + " is greater than 5"

ENDIF

MESSAGEBOX(vStatus; "OUT-OF-RANGE ERROR" ; vMessage + " - please try again"; IconExclamation!)

ENDPROC


example 8071
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONREMOVELISTITEM command

Loop = 1

lParam = 7

WM_SYSCOMMAND = 274

DIALOGDEFINE(1000; 50; 50; 107; 125; Percent! | NoFrame!; "RegionRemoveListItem")

DIALOGADDTEXT(1000; 0; 0; 15; 107; 15; Center!; "Select a fruit to delete")

DIALOGADDLISTBOX(1000; 102; 10; 35; 85; 75; Sorted!; var)

FOREACH(vList; {"Apples"; "Bananas"; "Oranges"; "Grapes"; "Pears"; "Watermelon"; "Grapefruit"; "Peaches"})

DIALOGADDLISTITEM(1000; 102; vList)

ENDFOR

DIALOGHANDLE(hItem; 1000; 102)

DIALOGSHOW(1000; 102; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(LWORD(Msg[lParam]) = hItem)

REGIONGETSELECTEDTEXT(vSelectItem; "1000.102")

REGIONREMOVELISTITEM("1000.102"; vSelectItem)

ENDIF

RETURN

FUNCTION LWORD(vNum)

vNum = vNum & 65535

RETURN(vNum)

ENDFUNC


example 8003

APPLICATION(A1; "WordPerfect"; Default; "US")// Beep vCount times - BREAK when vCount equals 4

// Remember: functions do not execute unless called

// Demonstrate BEEP command

FUNCTION BeepBeep(vCount)

REPEAT

BEEP

WAIT(3)

vCount := vCount - 1

UNTIL(vCount = 0)

RETURN

ENDFUNC

FOREACH(vCount; {1; 2; 3; 4; 5})

IF(vCount = 4)

BREAK

ENDIF

BeepBeep(vCount)

WAIT(5)

ENDFOR

MESSAGEBOX(x; "BREAK"; "Variable vCount equals 4"; IconInformation!)

QUIT


example 8073
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONSELECTLISTITEM command

Loop = 1

lParam = 7

WM_SYSCOMMAND = 274

DIALOGDEFINE(1000; 50; 50; 205; 125; Percent! | NoFrame!; "RegionSelectListItem")

DIALOGADDTEXT(1000; 0; 0; 15; 107; 15; Center!; "Select a fruit")

DIALOGADDLISTBOX(1000; 100; 11; 35; 85; 75; Sorted!; var)

DIALOGADDLISTBOX(1000; 101; 108; 35; 85; 75; UnSorted!; var)

FOREACH(vList; {"Oranges"; "Grapes"; "Apples"; "Pears"; "Watermelon"; "Grapefruit"; "Peaches"; "Bananas"})

DIALOGADDLISTITEM(1000; 100; vList)

DIALOGADDLISTITEM(1000; 101; vList)

ENDFOR

DIALOGHANDLE(hItem; 1000; 100)

DIALOGSHOW(1000; 100; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(LWORD(Msg[lParam]) = hItem)

REGIONGETSELECTEDTEXT(vSelectItem; "1000.100")

REGIONSELECTLISTITEM("1000.101"; vSelectItem)

ENDIF

RETURN

FUNCTION LWORD(vNum)

vNum = vNum & 65535

RETURN(vNum)

ENDFUNC


example 8076
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONASETWINDOWTEXT command

Loop = 1

vNmbr = 2

WM_SYSCOMMAND = 274

DIALOGDEFINE(1000; 50; 50; 150; 50; Percent! | NoFrame!; "RegionSetWindowText")

DIALOGADDFRAME(1000; 100; 10; 10; 10; 10; Frame! | Filled! | Gray!)

DIALOGADDHOTSPOT(1000; 101; 10; 10; 10; 10; Click!)

DIALOGADDTEXT(1000; 102; 28; 10; 125; 15; Left!; "Click to change text")

DIALOGSHOW(1000; 101; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(Msg[3] = 101)

ChangeTitle

ENDIF

RETURN

LABEL(ChangeTitle)

vChange = "Click " + vNmbr

REGIONSETWINDOWTEXT("1000"; vChange)

REGIONSETWINDOWTEXT("1000.102"; vChange)

ASSIGN(vNmbr; vNmbr + 1)

RETURN


example 8075
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONSETFOCUS command

Loop = 1

lParam = 7

WM_SYSCOMMAND = 274

DIALOGDEFINE(1000; 20; 30; 107; 110; NoFrame!; "RegionSetFocus")

DIALOGADDTEXT(1000; 0; 0; 15; 107; 15; Center!; "Select a button")

DIALOGADDLISTBOX(1000; 100; 10; 35; 85; 35; Sorted!; var)

FOREACH(vList; {"Radio Button 1"; "Radio Button 2"; "Radio Button 3"})

DIALOGADDLISTITEM(1000; 100; vList)

ENDFOR

DIALOGHANDLE(hItem; 1000; 100)

DIALOGADDRADIOBUTTON(1000; 101; 10; 75; 15; 15; "1"; var)

DIALOGADDRADIOBUTTON(1000; 102; 40; 75; 15; 15; "2"; var)

DIALOGADDRADIOBUTTON(1000; 103; 70; 75; 15; 15; "3"; var)

DIALOGSHOW(1000; 100; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(LWORD(Msg[lParam]) = hItem)

REGIONGETSELECTEDTEXT(vRB; "1000.100")

SWITCH(vRB)

CASEOF "Radio Button 1": vFocus = "101"

CASEOF "Radio Button 2": vFocus = "102"

CASEOF "Radio Button 3": vFocus = "103"

ENDSWITCH

REGIONSETFOCUS("1000." + vFocus)

ENDIF

RETURN

FUNCTION LWORD(vNum)

vNum = vNum & 65535

RETURN(vNum)

ENDFUNC


example 8074
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONSETCHECK command

Loop = 1

WM_SYSCOMMAND = 274

vCheck = 1

DIALOGDEFINE(1000; 50; 50; 160; 75; Percent! | NoFrame!; "RegionSetCheck")

DIALOGADDFRAME(1000; 100; 10; 10; 10; 10; Frame! | Filled! | Gray!)

DIALOGADDHOTSPOT(1000; 101; 10; 10; 10; 10; Click!)

DIALOGADDTEXT(1000; 0; 28; 10; 125; 15; Left!; "Click to select/deselect check box")

DIALOGADDCHECKBOX(1000; 102; 60; 35; 50; 15; "Check Box"; var)

DIALOGSHOW(1000; 101; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(Msg[3] = 101)

IF(vCheck = 1)

REGIONSETCHECK("1000.102"; Check!)

vCheck = 0

ELSE

REGIONSETCHECK("1000.102"; UnCheck!)

vCheck = 1

ENDIF

ENDIF

RETURN


example 8005
APPLICATION(A1; "WordPerfect"; Default; "US")

CANCEL(On!)

ONCANCEL CALL(CancelMessage)

PROCEDURE Message(vPrompt; vIcon)

IF(vIcon = "!")

MESSAGEBOX(y; "Test Results"; vPrompt; IconExclamation!)

ELSE

MESSAGEBOX(y; "Test Results"; vPrompt; IconInformation!)

ENDIF

ENDPROC

vStr := ""

REPEAT

GETSTRING(vStr; "Enter a word or Q to quit."; "Example Macro"; 50)

vTest := TOUPPER(vStr)

IF(vStr = "")

vStr := """<OK>"""

ENDIF

IF(vTest = "Q")

CALL Message("Goodbye"; "i")

ELSE

vMsg = "The CHAR length of " + vStr

vMsg = vMsg + " is " + CHARLEN(vStr)

CALL Message(vMsg; "!")

ENDIF

UNTIL(vTest = "Q")

QUIT

LABEL(CancelMessage)

vStr := "<Cancel>"

RETURN


example 8072
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONRESETLIST command

Loop = 1

Yes = 6

WM_SYSCOMMAND = 274

DIALOGDEFINE(1000; 20; 20; 107; 125; NoFrame!; "RegionResetList")

DIALOGADDFRAME(1000; 100; 10; 10; 10; 10; Frame! | Filled! | Gray!)

DIALOGADDHOTSPOT(1000; 101; 10; 10; 10; 10; Click!)

DIALOGADDTEXT(1000; 0; 28; 10; 75; 15; Left!; "Click to clear list")

DIALOGADDLISTBOX(1000; 102; 10; 35; 85; 75; Sorted!; var)

CALL(AddItems)

DIALOGSHOW(1000; 101; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(Msg[3] = 101)

REGIONRESETLIST("1000.102")

MESSAGEBOX(vResult; "Macro Example"; "Do you want to start over?"; IconQuestion! | YesNo!)

IF(vResult = Yes)

CALL(AddItems)

ELSE

Loop = 0

ENDIF

ENDIF

RETURN

LABEL(AddItems)

FOREACH(vList; {"Apples"; "Bananas"; "Oranges"; "Grapes"; "Pears"})

DIALOGADDLISTITEM(1000; 102; vList)

ENDFOR

RETURN


example 8007

APPLICATION(A1; "WordPerfect"; Default; "US")// Execute Windows* Calculator, Calendar, and Cardfile

ASSIGN(hWP; APPLOCATE("WordPerfect*"))

REPEAT

MENU(vChoice; Digit; ; ; {"Calculator"; "Calendar"; "Card File"; "Quit"})

CASE CALL(vChoice; {1; Program; 2; Program; 3; Program; 4; QuitMacro})

UNTIL(vChoice = 4)

LABEL(Program)

SWITCH(vChoice)

CASEOF 1: vProgram := "c:\windows\calc.exe"

CASEOF 2: vProgram := "c:\windows\calendar.exe"

CASEOF 3: vProgram := "c:\windows\cardfile.exe"

ENDSWITCH

APPEXECUTE(vProgram)

RETURN

LABEL(QuitMacro)

MESSAGEBOX(vStatus; "EXIT"; "Finished?"; IconQuestion! | YesNo!)

IF(vStatus = 6)

APPACTIVATE(hWP)

QUIT

ELSE

RETURN

ENDIF


example 8014
APPLICATION(A1; "WordPerfect"; Default; "US")

// Start conversation with GroupWise* 4.1

// Demonstrate DDEEXECUTE and DDEINITIATE commands

hConv := DDEINITIATE("GROUPWISE"; "COMMAND")

IF(hConv) // IF hConv not equal to 0

DDEEXECUTE(hConv; "ViewOpenNamed(ViewName:""Mail""; ViewType:Mail!)")

DDETERMINATEALL

ELSE

MESSAGEBOX(x; "ERROR"; "Is GroupWise running?  Conversation not started."; IconQuestion!)

ENDIF


example 8013
APPLICATION(A1; "WordPerfect"; Default; "US")

// Extract "Perfect" from WordPerfect

// Test if "program" was entered

// Demonstrate SUBCHAR command

vNumbers := ""

vPrompt := "Enter the following text: ""WordPerfect program"""

LABEL(Start)

GETSTRING(vStr; vPrompt; "USING SUBCHAR")

IF(vStr = "")

BEEP

MESSAGEBOX(x; "ERROR"; "You pressed return without entering any text"; IconStop!)

GO(Start)

ENDIF

vSub := SUBCHAR(vStr; 5; 7)

IF(vSub = "Perfect")

MESSAGEBOX(x; "SUBCHAR EXAMPLE"; "WordPerfect is simply """ + vSub + """"; IconInformation!)

IF(CHARPOS(vStr; "program") = 0)

BEEP

MESSAGEBOX(x; "CHARPOS EXAMPLE"; "You entered ""WordPerfect"" but not ""program"""; IconExclamation!)

ENDIF

ELSE

BEEP

MESSAGEBOX(x; "ERROR"; """WordPerfect"" wasn't the first word"; IconExclamation!)

GO(Start)

ENDIF


example 8015
APPLICATION(A1; "WordPerfect"; Default; "US")

// Start conversation with GroupWise* 4.1 from WordPerfect 6.1

// Execute GroupWise 4.1 command

// Demonstrate DDEEXECUTEEXT command

ASSIGN(hConv; DDEINITIATE("GROUPWISE"; "COMMAND"))

IF(hConv) // IF hConv not equal to 0

vReturn := DDEEXECUTEEXT(hConv; "ViewOpenNamed(""Mail""; Mail!)"; 0; Message)

IF(vReturn = 0)

MESSAGEBOX(x; "ERROR"; "Command not received by GroupWise"; IconExclamation!)

ENDIF

ELSE

BEEP

MESSAGEBOX(x; "ERROR"; "Is GroupWise running?  Conversation not started."; IconQuestion!)

ENDIF

DDETERMINATEALL

QUIT

LABEL(Message)

ASSIGN(vMsg; "GroupWise acknowledges receipt of ViewOpenNamed command")

MESSAGEBOX(z; "DDEEXECUTEEXT EXAMPLE"; vMsg; IconInformation!)

RETURN


example 8016
APPLICATION(A1; "WordPerfect"; Default; "US")

// Request GroupWise* 4.1 version number from WordPerfect 7

// Demonstrate DDEREQUEST command

// This example is included for backward compatibility

// In GroupWise Macros Help, see Contents page, Using DDE

ASSIGN(hConv; DDEINITIATE("WPOFFICE40"; "GETOFFICEDATA"))

IF(hConv)

ASSIGN(vMajor; DDEREQUEST(hConv; "GetOfficeData(ID; MajorVersion!)"))

ASSIGN(vMinor; DDEREQUEST(hConv; "GetOfficeData(ID; MinorVersion!)"))

MESSAGEBOX(x; "DDEREQUEST EXAMPLE"; "GroupWise version is " + vMajor + "." + vMinor; IconInformation!)

DDETERMINATE(hConv)

ELSE

BEEP

MESSAGEBOX(x; "ERROR"; "Is GroupWise running?  Conversation not started."; IconQuestion!)

ENDIF


example 8017
APPLICATION(A1; "WordPerfect"; Default; "US")

// Assign fax number to ExpressFax+

// Demonstrate DDEPOKE command

ASSIGN(hConv; DDEINITIATE("FAXMNG"; "Transmit"))

IF(hConv)

GETSTRING(vFax; "Enter FAX Number"; "ExpressFax+")

DDEPOKE(hConf;"FAX Number"; vFax)

DDETERMINATE(hConv)

ELSE

BEEP

MESSAGEBOX(x; "ERROR"; "Is ExpressFax+ running?  Conversation not started."; IconQuestion!)

ENDIF


example 8012
APPLICATION(A1; "WordPerfect"; Default; "US")

// Extract numbers from a character string

// Demonstrate CHARLEN command

vNumbers := ""

vPrompt := "Enter text that includes both letters and numbers:"

LABEL(Start)

GETSTRING(vStr; vPrompt; "EXTRACT NUMBERS")

IF(vStr = "")

BEEP

MESSAGEBOX(x; "ERROR"; "You pressed return without entering any text"; IconStop!)

GO(Start)

ENDIF

vLen := CHARLEN(vStr)

vPos := 1

WHILE(NOT(vPos = vLen + 1))

vTest := SUBCHAR(vStr; vPos; 1)

IF((CTON(vTest) > 47) AND (CTON(vTest) < 58))

vNumbers := vNumbers + vTest

ENDIF

vPos := vPos + 1

ENDWHILE

IF(CHARLEN(vNumbers) > 0)

MESSAGEBOX(x; "NUMBER STRING"; "You entered the following numbers: " + vNumbers; IconInformation!)

ELSE

BEEP

MESSAGEBOX(x; "ERROR"; "You didn't enter any numbers"; IconExclamation!)

ENDIF


example 8011
APPLICATION(A1; "WordPerfect"; Default; "US")

// Create a loop with GO command

LABEL(Start)

MENU(vChoice; Digit; ; ; {"IconExclamation!"; "IconInformation!"; "IconQuestion"; "IconStop!"; "Quit"})

CASE(vChoice; {1; Exclaim; 2; Info; 3; Question; 4; Stop; 5; QuitMacro})

LABEL(Exclaim)

MESSAGEBOX(x; "EXCLAMATION"; "Example of an exclamation icon"; IconExclamation!)

GO(LoopToStart)

LABEL(Info)

MESSAGEBOX(x; "INFORMATION"; "Example of an information icon"; IconInformation!)

GO(LoopToStart)

LABEL(Question)

Yes := 6

MESSAGEBOX(vAns; "QUESTION"; "Example of a question icon" + NTOC(0F90Ah) +"Click a button"; IconQuestion! | YesNo!)

IF(vAns = Yes)

vPrompt := "You clicked Yes"

ELSE

vPrompt := "You clicked No "

ENDIF

MESSAGEBOX(x; "MACRO PATH"; vPrompt; IconInformation!)

GO(LoopToStart)

LABEL(Stop)

MESSAGEBOX(z; "STOP"; "Example of a stop icon"; IconStop!)

GO(LoopToStart)

LABEL(LoopToStart)

No := 7

MESSAGEBOX(vAns; "Message"; "Would you like to continue?"; IconQuestion! | YesNo!)

IF(vAns = No)

GO(QuitMacro)

ELSE

vChoice = ""

GO(Start)

ENDIF

LABEL(QuitMacro)

BEEP

QUIT


example 8077
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONSHOWWINDOW command

Loop = 1

WM_SYSCOMMAND = 274

vDisable = 1

DIALOGDEFINE(1000; 50; 50; 175; 75; Percent! | NoFrame!; "RegionShowWindow")

DIALOGADDFRAME(1000; 100; 10; 10; 10; 10; Frame! | Filled! | Gray!)

DIALOGADDHOTSPOT(1000; 101; 10; 10; 10; 10; Click!)

DIALOGADDTEXT(1000; 0; 28; 10; 125; 15; Left!; "Click to hide/show the following text")

DIALOGADDTEXT(1000; 102; 0; 35; 175; 15; Center!; "Novell GroupWise* 4.1")

DIALOGSHOW(1000; 101; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(Msg[3] = 101)

IF(vDisable = 1)

REGIONSHOWWINDOW("1000.102"; Hide!)

vDisable = 0

ELSE

REGIONSHOWWINDOW("1000.102"; Show!)

vDisable = 1

ENDIF

ENDIF

RETURN


example 8008

APPLICATION(A1; "WordPerfect"; Default; "US")// Create personal or business letterhead

// Plays macro in WordPerfect for Windows

MENU(vChoice; Digit; ; ; {"Personal letterhead"; "Business letterhead"; "Quit"})

FileNew

CASE(vChoice; {1; Personal; 2; Business; 3; QuitMacro}; QuitMacro)

LABEL(Personal)

Center

AttributeAppearanceOn(Bold!)

FontSize(16.0p)

Type("From Dan's Desk")

AttributeAppearanceOff(Bold!) HardReturn

Center FontSize(12.0p)

DateCode

HardReturn HardReturn HardReturn

Type("Dear ")

QUIT

LABEL(Business)

DateCode HardReturn HardReturn

Type("Mr. John Doe") HardReturn

Type("Executive Vice President") HardReturn

Type("XYZ Company") HardReturn

Type("4399 Oak View Drive") HardReturn

Type("Orem, UT 84057") HardReturn HardReturn

Type("Dear Mr. Doe:")

QUIT

LABEL(QuitMacro)

QUIT


example 8009

// There are four macros in this example// Compile separately

APPLICATION(A1; "WordPerfect"; Default; "US")

// macro1.wcm

MESSAGEBOX(vStatus; vTitle; "Macro 1 " + vPrompt; IconInformation!)

APPLICATION(A1; "WordPerfect"; Default; "US")

// macro2.wcm

MESSAGEBOX(vStatus; vTitle; "Macro 2 " + vPrompt; IconInformation!)

APPLICATION(A1; "WordPerfect"; Default; "US")

// macro3.wcm

MESSAGEBOX(vStatus; vTitle; "Macro 3 " + vPrompt; IconInformation!)

APPLICATION(A1; "WordPerfect"; Default; "US")

// Calling Macro

GLOBAL vTitle; vPrompt

MENU(vChoice; Letter; ; ; {"Macro 1"; "Macro 2"; "Macro 3"})

ASSIGN(vPrompt; "called")

GETSTRING(vMacrosPath; "Enter macros path"; "Example Macro"; 50)

SWITCH(vChoice)

CASEOF 1:

ASSIGN(vTitle; "MACRO ONE")

CHAIN(vMacrosPath + "macro1.wcm")

CASEOF 2:

ASSIGN(vTitle; "MACRO TWO")

CHAIN(vMacrosPath + "macro2.wcm")

CASEOF 3:

ASSIGN(vTitle; "MACRO THREE")

CHAIN(vMacrosPath + "macro3.wcm")

ENDSWITCH

MESSAGEBOX(x; "Macro Example"; "This box displays before a Chain command is executed."; IconInformation!)


example 8010

// There are four macros in this example// Compile separately

APPLICATION(A1; "WordPerfect"; Default; "US")

// macro1.wcm

MESSAGEBOX(vStatus; vTitle; "Macro 1 - " + vPrompt; IconInformation!)

RETURN

APPLICATION(A1; "WordPerfect"; Default; "US")

// macro2.wcm

MESSAGEBOX(vStatus; vTitle; "Macro 2 - " + vPrompt; IconInformation!)

RETURN

APPLICATION(A1; "WordPerfect"; Default; "US")

// macro3.wcm

MESSAGEBOX(vStatus; vTitle; "Macro 3 - " + vPrompt; IconInformation!)

RETURN

APPLICATION(A1; "WordPerfect"; Default; "US")

// Calling Macro

// Demonstrate RUN command and GLOBAL variables

GLOBAL vTitle; vPrompt

ASSIGN(vPrompt; "RUN macros can return to their caller")

ASSIGN(vMacrosPath; EnvPaths(PathType: Macros!))

REPEAT

MENU(vChoice; Letter; ; ; {"Macro 1"; "Macro 2"; "Macro 3"; "Quit"})

SWITCH(vChoice)

CASEOF 1:

ASSIGN(vTitle; "MACRO ONE")

RUN(vMacrosPath + "macro1.wcm")

CASEOF 2:

ASSIGN(vTitle; "MACRO TWO")

RUN(vMacrosPath + "macro2.wcm")

CASEOF 3:

ASSIGN(vTitle; "MACRO THREE")

RUN(vMacrosPath + "macro3.wcm")

DEFAULT: QuitMacro

ENDSWITCH

UNTIL(vChoice = 4)

LABEL(QuitMacro)

BEEP

MESSAGEBOX(vStatus; "QUIT"; "This example uses global variables"; IconExclamation!)

DISCARD vTitle; vPrompt

QUIT


example 8006
APPLICATION(A1; "WordPerfect"; Default; "US")

MENU(vChoice; Digit; ; ; {"Advance down"; "Advance up"; "Advance left"; "Advance right"})

SWITCH(vChoice)

CASEOF 1: vPrompt := "Advance down:"

CASEOF 2: vPrompt := "Advance up:"

CASEOF 3: vPrompt := "Advance left:"

CASEOF 4: vPrompt := "Advance right:"

ENDSWITCH

DEFAULTUNITS(Inches!)

// option: specifiy different unit of measure

GETUNITS(vUnit; vPrompt; "GETUNITS EXAMPLE")

SWITCH(vChoice)

CASEOF 1: ADVANCE(AdvanceDown!; vUnit)

CASEOF 2: ADVANCE(AdvanceUp!; vUnit)

CASEOF 3: ADVANCE(AdvanceLeft!; vUnit)

CASEOF 4: ADVANCE(AdvanceRight!; vUnit)

ENDSWITCH


example 8079
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate GETCURRENTDIRECTORY and SETCURRENTDIRECTORY command

ONCANCEL(QuitMacro)

HRt = NTOC(0F90Ah)

LABEL(SetCurrentDir)

GETSTRING(vNewDir; "Current directory: " + GETCURRENTDIRECTORY + HRt + HRt + "New directory:"; "Directory Commands"; 100)

IF(SETCURRENTDIRECTORY(vNewDir) = False)

BEEP

MESSAGEBOX(x; "Error"; "Invalid directory"; IconExclamation!)

GO(SetCurrentDir)

ELSE

MESSAGEBOX(x; "Current Directory"; vNewDir; IconInformation!)

ENDIF

QUIT

LABEL(QuitMacro)

MESSAGEBOX(x; "End Macro"; "You chose Cancel or pressed Esc"; IconInformation!)

QUIT


example 8094
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate REGIONISVISIBLE, DIALOGSHOW, and DIALOGDISMISS commands

DialogDefine("Dialog"; 50; 50; 200; 200; Percent!; "REGIONISVISIBLE")

DialogAddPushButton("Dialog"; 1; 85; 10; 25; 13; NonDefaultBttn!; "OK")

DialogAddPushButton("Dialog"; 2; 85; 30; 25; 13; DefaultBttn!; "Cancel")

DialogShow("Dialog"; "WordPerfect"; Msg)

x = 0

WHILE(x != 1)

REGIONISVISIBLE (vResult; "Dialog.1")

MESSAGEBOX(z; "OK button"; "Visible: " + CheckResult(vResult))

REGIONSHOWWINDOW ("Dialog.1"; Hide!)

REGIONISVISIBLE (vResult; "Dialog.1")

MESSAGEBOX(z; "OK button"; "Visible: " + CheckResult(vResult))

x = 1

ENDWHILE

DialogDismiss("Dialog"; "CancelBttn")

QUIT

LABEL(Msg)

RETURN

FUNCTION CheckResult(vResult)

IF(vResult = 0)

vResult = "No"

ELSE

vResult = "Yes"

ENDIF

RETURN(vResult)

ENDFUNC


example 8095
APPLICATION(A1; "WordPerfect"; Default; "US")

OnError (ErrorMsg)

DialogDefine ("Dialog1"; 50; 50; 200; 100; Percent! | OK! | Cancel!; "Dialog Example")

DialogAddPushButton("Dialog1"; "PushBttn1"; 153; 35; 38; 14; NonDefaultBttn!; "Add Ctrl")

DialogAddPushButton("Dialog1"; "PushBttn2"; 153; 55; 38; 14; NonDefaultBttn!; "Get hwnd")

DialogShow ("Dialog1"; "WordPerfect"; Msg)

CallbackWait

Quit

Label(Msg)

If (Msg[5] = 274)

DialogDestroy ("Dialog1")

CallbackResume

Return

Endif

Switch (Msg[3])

CaseOf "OKBttn": MessageBox(x; "OK Button"; "You pressed OK"; IconInformation!)

CaseOf "CancelBttn":

DialogDestroy("Dialog1")

CallBackResume

Return

CaseOf "PushBttn1":

DialogAddProgress ("Dialog1"; "ProgressCtrl"; 10;10; 180; 15)

CaseOf "PushBttn2":

hwnd := RegionGetHandle ("dialog1.ProgressCtrl")

MessageBox (x; "Window Handle"; hwnd)

EndSwitch

Return

Label (ErrorMsg)

MessageBox (x; "Error"; "You pressed the Get hwnd button before the Add Ctrl button."; IconExclamation!)

Return


example 8093
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate DIALOGSHOW and DIALOGDISMISS commands

HRt = NTOC(0F90Ah)

WM_COMMAND = 273

WM_SYSCOMMAND = 274

vPopup = "Popup item 1"

vList = "List item 1"

DIALOGSHOW("Dialog1"; "WordPerfect"; Msg)

x := 0

While(x = 0)

Endwhile

QUIT

LABEL(MSG)

IF((Msg[5] = WM_SYSCOMMAND) OR (Msg[3] = "CancelBttn"))

BEEP

x = 1

RETURN

ENDIF

IF(Msg[5] = WM_COMMAND)

DIALOGDISMISS("Dialog1"; "OKBttn")

MsgBox

DIALOGSHOW("Dialog1"; "WordPerfect"; Msg)

ENDIF

RETURN

LABEL(MsgBox)

MESSAGEBOX(z; "Selections"; vList + HRt + HRt + vPopup + HRt)

RETURN


example 8092


example 8091
// There are two macros in this example

// The INCLUDE macro is compiled when you play the main macro

// Demonstrate INCLUDE command

// INCLUDE macro: INC.WCM

// Without compiling, save this macro in the macros directory

APPLICATION (A1; "WordPerfect"; Default; "US")

Type("2")

PROCEDURE TestProc(x)

Type(x)

ENDPROC

//Main macro: PARENT.WCM

APPLICATION (A1; "WordPerfect"; Default; "US")

AddTextBox (1600w; 12000w; 9000w; 10000w)

Type("1")

INCLUDE("C:\PRWIN30\MACROS\INC.WCM")

Type("3")

CALL TestProc(4)

QUIT


example 8096
APPLICATION(A1; "WordPerfect"; Default; "US")

DialogDefine ("Dialog1"; 50; 50; 200; 100; Percent! | OK! | Cancel!; "Dialog Example")

DialogAddPushButton("Dialog1"; "PushBttn1"; 153; 35; 38; 14; NonDefaultBttn!; "Run Calc")

DialogAddPushButton("Dialog1"; "PushBttn2"; 153; 55; 38; 14; NonDefaultBttn!; "Toggle")

DialogAddPushButton("Dialog1"; "PushBttn3"; 153; 15; 38; 14; NonDefaultBttn!; "Close App")

DialogLoad("Dialog1"; "WordPerfect")

RegionShowWindow ("Dialog1.PushBttn2"; Hide!)

RegionShowWindow ("Dialog1.PushBttn3"; Hide!)

x = 1

DialogShow ("Dialog1"; "WordPerfect"; Msg)

CallbackWait

Quit

Label(Msg)

If (Msg[5] = 274)

DialogDestroy ("Dialog1")

CallbackResume

Return

Endif

Switch (Msg[3])

CaseOf "OKBttn": MessageBox(x; "OK Button"; "You pressed OK"; IconInformation!)

CaseOf "CancelBttn":

DialogDestroy("Dialog1")

CallBackResume

Return

CaseOf "PushBttn1":

AppExecute ("c:\windows\calc.exe")

RegionShowWindow ("Dialog1.PushBttn2"; Show!)

RegionShowWindow ("Dialog1.PushBttn3"; Show!)

CaseOf "PushBttn2":

If(x=1)

AppShow ("Calculator"; Hide!)

x := 0

Else

AppShow ("Calculator"; Restore!)

x := 1

EndIf

CaseOf "PushBttn3":

AppClose ("Calculator")

RegionShowWindow ("Dialog1.PushBttn2"; Hide!)

RegionShowWindow ("Dialog1.PushBttn3"; Hide!)

EndSwitch

Return


example 8097
APPLICATION(A1; "WordPerfect"; Default; "US")

OnError (ErrorMessage)

DialogDefine ("Dialog1"; 50; 50; 200; 100; Percent! | OK! | Cancel!; "Dialog Example")

DialogAddPushButton("Dialog1"; "PushBttn1"; 153; 35; 38; 14; NonDefaultBttn!; "Add Ctrl")

DialogAddPushButton("Dialog1"; "PushBttn2"; 153; 55; 38; 14; NonDefaultBttn!; "Get Date")

DialogShow ("Dialog1"; "WordPerfect"; Msg)

CallbackWait

Quit

Label(Msg)

If (Msg[5] = 274)

DialogDestroy ("Dialog1")

CallbackResume

Return

Endif

Switch (Msg[3])

CaseOf "OKBttn": MessageBox(x; "OK Button"; "You pressed OK"; IconInformation!)

CaseOf "CancelBttn":

DialogDestroy("Dialog1")

CallBackResume

Return

CaseOf "PushBttn1":

vDay := DateDay()

vMonth := DateMonth()

vYear := DateYear()

DialogAddDate ("Dialog1"; "DateCtrl"; 10;10; 50; 15; Validate!;

var; vYear; vMonth; vDay)

CaseOf "PushBttn2":

MessageBox(x; "Selected Date"; RegionGetWindowText ("Dialog1.DateCtrl"))

EndSwitch

Return

Label(ErrorMessage)

MessageBox(x; "Error"; "You may have selected Get Date before Add Ctrl";  IconExclamation!)

Return


example 8101
APPLICATION(A1; "WordPerfect"; Default; "US")

OnError (ErrorMsg)

DialogDefine ("Dialog1"; 50; 50; 200; 100; Percent! | OK! | Cancel!; "Dialog Example")

DialogAddPushButton("Dialog1"; "PushBttn1"; 153; 35; 38; 14; NonDefaultBttn!; "Add Ctrl")

DialogAddPushButton("Dialog1"; "PushBttn2"; 153; 55; 38; 14; NonDefaultBttn!; "Modify")

DialogShow ("Dialog1"; "WordPerfect"; Msg)

CallbackWait

Quit

Label(Msg)

If (Msg[5] = 274)

DialogDestroy ("Dialog1")

CallbackResume

Return

Endif

Switch (Msg[3])

CaseOf "OKBttn": MessageBox(x; "OK Button"; "You pressed OK"; IconInformation!)

CaseOf "CancelBttn":

DialogDestroy("Dialog1")

CallBackResume

Return

CaseOf "PushBttn1":

DialogAddEditBox ("Dialog1"; "EditCtrl"; 10; 10; 120; 50; Left! | Multiline!; vText; 100)

RegionSetWindowText ("Dialog1.EditCtrl"; "Modify text.")

RegionSetFocus ("Dialog1.EditCtrl")

CaseOf "PushBttn2":

vMod := RegionGetModified ("Dialog1.EditCtrl")

MessageBox (x; "Modify List Box"; vMod)

RegionSetFocus ("Dialog1.EditCtrl")

EndSwitch

Return

Label (ErrorMsg)

MessageBox (x; "Error"; "You pressed Modify before Add Ctrl."; IconExclamation!)

Return


example 8100
APPLICATION(A1; "WordPerfect"; Default; "US")

DialogDefine ("Dialog1"; 50; 50; 200; 100; Percent! | OK! | Cancel!; "Dialog Example")

DialogAddListBox ("Dialog1"; "ListCtrl"; 10; 10; 120; 70; Unsorted!; vItem)

DialogAddPushButton("Dialog1"; "PushBttn1"; 153; 35; 38; 14; NonDefaultBttn!; "Add Item")

DialogAddPushButton("Dialog1"; "PushBttn2"; 153; 55; 38; 14; NonDefaultBttn!; "Get Cnt")

vCount := 1

DialogShow ("Dialog1"; "WordPerfect"; Msg)

CallbackWait

Quit

Label(Msg)

If (Msg[5] = 274)

DialogDestroy ("Dialog1")

CallbackResume

Return

Endif

Switch (Msg[3])

CaseOf "OKBttn": MessageBox(x; "OK Button"; "You pressed OK"; IconInformation!)

CaseOf "CancelBttn":

DialogDestroy("Dialog1")

CallBackResume

Return

CaseOf "PushBttn1":

vItem := "Item" + vCount

RegionAddListItem ("Dialog1.ListCtrl"; vItem)

vCount := vCount + 1

CaseOf "PushBttn2":

vNmbr := RegionGetListCount ("Dialog1.ListCtrl")

MessageBox (x; "List Items"; "Number: " + vNmbr)

EndSwitch

Return


example 8099
APPLICATION(A1; "WordPerfect"; Default; "US")

DialogDefine ("Dialog1"; 50; 50; 200; 100; Percent! | OK! | Cancel!; "Dialog Example")

DialogAddPushButton("Dialog1"; "PushBttn1"; 153; 35; 38; 14; NonDefaultBttn!; "Dialog1")

DialogAddPushButton("Dialog1"; "PushBttn2"; 153; 55; 38; 14; NonDefaultBttn!; "Dialog2")

DialogShow ("Dialog1"; "WordPerfect"; Msg)

//DialogSetProperties ("Dialog1")

CallbackWait

Quit

Label(Msg)

If (Msg[5] = 274)

DialogDestroy ("Dialog1")

CallbackResume

Return

Endif

Switch (Msg[3])

CaseOf "OKBttn": MessageBox(x; "OK Button"; "You pressed OK"; IconInformation!)

CaseOf "CancelBttn":

DialogDestroy("Dialog1")

CallBackResume

Return

CaseOf "PushBttn1":

vAns := DoesDialogExist ("Dialog1")

DialogAddText ("Dialog1"; 101; 10; 10; 100; 14; Center! | RecessBox!; vAns + ": Dialog1 exists.")

CaseOf "PushBttn2":

vAns := DoesDialogExist ("Dialog2")

DialogAddText ("Dialog1"; 101; 10; 10; 100; 14; Center! | RecessBox!; vAns + ": Dialog2 does not exist.")

EndSwitch

Return


example 8098
APPLICATION(A1; "WordPerfect"; Default; "US")

DialogDefine ("Dialog1"; 50; 50; 200; 100; Percent! | OK! | Cancel!; "Dialog Example")

DialogAddPushButton("Dialog1"; "PushBttn1"; 153; 35; 38; 14; NonDefaultBttn!; "Add Ctrl")

DialogAddPushButton("Dialog1"; "PushBttn2"; 153; 55; 38; 14; NonDefaultBttn!; "Start")

DialogShow ("Dialog1"; "WordPerfect"; Msg)

CallbackWait

Quit

Label(Msg)

If (Msg[5] = 274)

DialogDestroy ("Dialog1")

CallbackResume

Return

Endif

Switch (Msg[3])

CaseOf "OKBttn": MessageBox(x; "OK Button"; "You pressed OK"; IconInformation!)

CaseOf "CancelBttn":

DialogDestroy("Dialog1")

CallBackResume

Return

CaseOf "PushBttn1":

DialogAddProgress ("Dialog1"; "ProgressCtrl"; 10;10; 180; 15)

CaseOf "PushBttn2":

ForNext (vPercent; 1; 100; 1)

RegionSetProgressPercent("Dialog1.ProgressCtrl"; vPercent)

Wait(1)

EndFor

RegionSetProgressPercent("Dialog1.ProgressCtrl"; 0)

EndSwitch

Return


example 8090
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate FILEERROR and FINDFILE commands

vPath = EnvPaths(Macros!)

vFilename = FILEFIND(vPath + "*.wcm"; Normal!; 1)

WHILE(vFilename != "")

CALL DisplayName(vFilename)

vFilename = FILEFIND("";;1)

ENDWHILE

PROCEDURE DisplayName(vFilename)

MESSAGEBOX(x; "FILEFIND"; vFilename; IconInformation!)

ENDPROC

MESSAGEBOX(x; "Message"; "Error code = " + FILEERROR)


example 8089
APPLICATION(WP; "WordPerfect"; Default; "US")

// Before playing this macro, create a file named File_IO in the default macros directory, and save the file in ANSI (Windows) Text format

// Demonstrate FILETRUNCATE command

CALL(OpenWriteToReadFromFile)

CALL(QuitMacro)

LABEL(OpenWriteToReadFromFile)

HRt = NTOC(0F90Ah)

ASSIGN(vPath; EnvPaths(Macros!))

hFile = OPENFILE(vPath + "FILE_IO.DOC"; ReadWrite!;

DenyNone!; AnsiText!)

IF(hFile < 0)

MESSAGEBOX(x; "Error"; "Error opening file"; IconExclamation!)

QUIT

ENDIF

Test(FILEWRITE(hFile; "WordPerfect is a wonderful product!"; NoNewLine!); "FILEWRITE")

Test(FILEPOSITION(hFile; 0; FromBeginning!); "FILEPOSITION")

Test(FILEREAD(hFile; vText); "FILEREAD")

Test(FILEPOSITION(hFile; 20; FromBeginning!); "FILEPOSITION")

Test(FILETRUNCATE(hFile); "FILETRUNCATE")

Test(FILEPOSITION(hFile; 0; FromBeginning!); "FILEPOSITION")

Test(FILEREAD(hFile; vTruncate); "FILEREAD")

MESSAGEBOX(x; "File I/O - Truncate File"; vText+HRt+HRt+vTruncate)

RETURN

PROCEDURE Test(vError; vStr)

// vError = value returned from FILE command

IF(vError < 0)

BEEP

MESSAGEBOX(x; "Error"; vStr; IconExclamation!)

GO(QuitMacro)

ENDIF

ENDPROC

LABEL(QuitMacro)

IF(NOT(CLOSEFILE(hFile)) = True)

BEEP

MESSAGEBOX(x; "Error"; "Error closing file"; IconExclamation!)

ELSE

MESSAGEBOX(x; "File I/O"; "File successfully closed")

ENDIF

QUIT


example 8082
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate GETFILEATTRIBUTES command

ONCANCEL(QuitMacro)

HRt = NTOC(0F90Ah)

GETSTRING(vFilename; "File:"; "Get File Attributes"; 100)

IF(NOT(vFilename = ""))

MESSAGEBOX(x; ""; GETFILEATTRIBUTES(vFilename))

ENDIF

QUIT

LABEL(QuitMacro)

MESSAGEBOX(x; "End Macro"; "You chose Cancel or pressed Esc"; IconInformation!)

QUIT


example 8081
APPLICATION(WP; "WordPerfect"; Default; "US")

// Create a directory named c:\test

// Demonstrate RENAMEDIRECTORY command

ONCANCEL(QuitMacro)

HRt = NTOC(0F90Ah)

CREATEDIRECTORY ("c:\test";Prompts!)

GETSTRING(vNewName; "Type a new name for directory c:\test:"; "Rename a Directory"; 100)

RENAMEDIRECTORY ("c:\test";vNewName;Prompts!)

MESSAGEBOX(vYesNo; "Renamed Directory"; "Delete " + vNewName + " now?";IconQuestion!|YesNo!)

IF(vYesNo = 6)

DELETEDIRECTORY(vNewName)

MESSAGEBOX(x;"Delete Directory";"Directory " + vNewName + " deleted.")

ELSE

MESSAGEBOX(x;"Renamed Directory";"Directory " + vNewName + " not deleted.")

ENDIF

QUIT

LABEL(QuitMacro)

MESSAGEBOX(x;"End Macro"; "You chose Cancel or pressed Esc";IconInformation!)

QUIT


example 8080
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate CREATEDIRECTORY and DELETEDIRECTORY commands

ONCANCEL(QuitMacro)

HRt = NTOC(0F90Ah)

LABEL(CreateDir)

GETSTRING(vCreateDir; "Current directory: " + GETCURRENTDIRECTORY + HRt + HRt + "New directory:"; "Create New Directory"; 100)

IF(CREATEDIRECTORY(vCreateDir) = False)

BEEP

MESSAGEBOX(x; "Error"; "Directory not created"; IconExclamation!)

GO(CreateDir)

ELSE

MESSAGEBOX(vYesNo; "New Directory"; vCreateDir + HRt + Hrt + "Delete new directory now?"; IconQuestion! | YesNo!)

IF(vYesNo = 6)

MESSAGEBOX(x; "Delete Directory"; "Directory deleted: " + DELETEDIRECTORY(vCreateDir))

ENDIF

ENDIF

QUIT

LABEL(QuitMacro)

MESSAGEBOX(x; "End Macro"; "You chose Cancel or pressed Esc"; IconInformation!)

QUIT


example 8018
APPLICATION(A1; "WordPerfect"; Default; "US")

// Declare an array of months

// Demonstrate DECLARE command, recursive LABEL statement

DECLARE Months[12]

x := 1

FOREACH(vMonth; {"January"; "February"; "March"; "April"; "May"; "June"; "July"; "August"; "September"; "October"; "November"; "December"})

Months[x] := vMonth

x := x + 1

ENDFOR

LABEL(Start)

MENU(vNmbr; Letter; ; ; {"January"; "February"; "March"; "April"; "May"; "June"; "July"; "August"; "September"; "October"; "November"; "December"; "QUIT"})

IF(vNmbr = 13)

BEEP

QUIT

ELSE

MESSAGEBOX(vStatus; "MONTHS OF THE YEAR"; "You selected " + Months[vNmbr]; IconInformation!)

GO(Start)

ENDIF


example 8083
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate SETFILEATTRIBUTES command

ONCANCEL(QuitMacro)

HRt = NTOC(0F90Ah)

GETSTRING(vFilename; "Set read-only attribute." + HRt + Hrt + "File:"; "SETFILEATTRIBUTES"; 100)

IF(NOT(vFilename = ""))

MESSAGEBOX(x; "SETFILEATTRIBUTES"; "Read-only status: " + SETFILEATTRIBUTES(vFilename; ReadOnly!; Prompts!))

ENDIF

QUIT

LABEL(QuitMacro)

MESSAGEBOX(x; "End Macro"; "You chose Cancel or pressed Esc"; IconInformation!)

QUIT


example 8084
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate GETFILEDATEANDTIME command

ONCANCEL(QuitMacro)

HRt = NTOC(0F90Ah)

GETSTRING(vFilename; "Date and time." + HRt + Hrt + "File:"; "GETFILEDATEANDTIME"; 100)

IF(NOT(vFilename = ""))

MESSAGEBOX(x; "Number of seconds since Jan 1, 1980"; GETFILEDATEANDTIME(vFilename))

ENDIF

QUIT

LABEL(QuitMacro)

MESSAGEBOX(x; "End Macro"; "You chose Cancel or pressed Esc"; IconInformation!)

QUIT


example 8088
APPLICATION(WP; "WordPerfect"; Default; "US")

// Before playing this macro, create a file named File_IO, amd save it in the default macros directory in ANSI (Windows) Text format

// Demonstrate OPENFILE, CLOSEFILE, FILEWRITE, FILEREAD, FILEPOSITION, FILEISEOF, and FILESIZE commands

CALL(OpenInfo)

CALL(WriteToFile)

CALL(ReadFromFile)

CALL(QuitMacro)

LABEL(OpenInfo)

HRt = NTOC(0F90Ah)

ASSIGN(vPath; EnvPaths(Macros!))

hFile = OPENFILE(vPath + "FILE_IO.DOC"; ReadWrite!; DenyNone!; AnsiText!)

IF(hFile < 0)

ErrorMsg("opening"; hFile)

ELSE

vIsEOF = "Postion marker (EOF): " + FILEISEOF(hFile)

vSize = "File size: " + FILESIZE(vPath + "FILE_IO.DOC")

MESSAGEBOX(X;"File Information"; vIsEOF + HRt + HRt + vSize)

ENDIF

RETURN

LABEL(WriteToFile)

FORNEXT(z; 1; 10; 1)

IF(FILEWRITE(hFile; "WordPerfect is a great product! ";

NoNewLine!) < 0)

ErrorMsg("writing to"; hFile)

ENDIF

ENDFOR

RETURN

LABEL(ReadFromFile)

FILEPOSITION(hFile; 0; FromBeginning!)

IF(FILEREAD(hFile; vText) < 0)

ErrorMsg("reading from"; hFile)

ELSE

MESSAGEBOX(x; "File I/O"; vText)

ENDIF

RETURN

PROCEDURE ErrorMsg(Msg; hFile)

BEEP

MESSAGEBOX(x; "Error"; "Error " + Msg + " file"; IconExclamation!)

ENDPROC

LABEL(QuitMacro)

IF(NOT(CLOSEFILE(hFile)) = True)

BEEP

MESSAGEBOX(x; "Error"; "Error closing file"; IconExclamation!)

ELSE

MESSAGEBOX(x; "File I/O"; "File successfully closed")

ENDIF

QUIT


example 8087
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate RENAMEFILE command

ONCANCEL(QuitMacro)

HRt = NTOC(0F90Ah)

LABEL(begin)

GETSTRING(vOldName; "Old file name:"; "RENAMEFILE"; 100)

IF(vOldName = "")

GO(begin)

ENDIF

GETSTRING(vNewName; "Old file: " + vOldName + HRt + HRt + "New file name:"; "RENAMEFILE"; 100)

IF(NOT(vNewName = ""))

IF(NOT(RENAMEFILE(vOldName; vNewName; Prompts!) = True))

Msg = vOldName + " not renamed"

ELSE

Msg = "New file name: " + vNewName

ENDIF

MESSAGEBOX(x; "RENAMEFILE"; Msg; IconInformation!)

ENDIF

QUIT

LABEL(QuitMacro)

MESSAGEBOX(x; "End Macro"; "You chose Cancel or pressed Esc"; IconInformation!)

QUIT


example 8086
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate DELETEFILE command

ONCANCEL(QuitMacro)

GETSTRING(vFilename; "File:"; "DELETEFILE"; 100)

IF(NOT(vFilename = ""))

IF(NOT(DELETEFILE(vFilename; Prompts!) = True))

Msg = vFilename + " not deleted"

ELSE

Msg = vFilename + " successfully deleted"

ENDIF

MESSAGEBOX(x; "DELETEFILE"; Msg; IconInformation!)

ENDIF

QUIT

LABEL(QuitMacro)

MESSAGEBOX(x; "End Macro"; "You chose Cancel or pressed Esc"; IconInformation!)

QUIT


example 8085
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate SETFILEDATEANDTIME command

ONCANCEL(QuitMacro)

HRt = NTOC(0F90Ah)

GETSTRING(vFilename; "Date and time." + HRt + Hrt + "File:"; "GETFILEDATEANDTIME"; 100)

IF(NOT(vFilename = ""))

MESSAGEBOX(x; "New File Date and Time Stamp"; "Result: " + SETFILEDATEANDTIME(vFilename; 485780000) + " (Jun 30, 1994 / 7:02a)")

ENDIF

QUIT

LABEL(QuitMacro)

MESSAGEBOX(x; "End Macro"; "You chose Cancel or pressed Esc"; IconInformation!)

QUIT


example 8078
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate COPYFILE, DOESFILEEXIST, GETCURRENTDIRECTORY, and DOESDIRECTORYEXIST commands

VARERRCHK(Off!)

HRt = NTOC(0F90Ah)

CALL(GetFileNames)

CALL(CheckNames)

CALL(CopyFiles)

QUIT

LABEL(GetFileNames)

GETSTRING(vSource; "Current directory: " + GETCURRENTDIRECTORY + HRt + HRt + "File to copy:"; "Copy File"; 100)

GETSTRING(vDestination; "File to copy: " + vSource + HRt + HRt + "To:"; "Copy File"; 100)

RETURN

LABEL(CheckNames)

IF(NOT(DOESFILEEXIST(vSource) = True))

ErrorMsg(vSource + " does not exist")

ENDIF

vLen = STRLEN(vDestination)

vCnt = vLen

WHILE(NOT(vResult = "\") OR (vStrLen = 0))

vResult = SUBSTR(vDestination; vCnt; 1)

vCnt = vCnt - 1

ENDWHILE

// parsed filename is not used vFilename = SUBSTR(vDestination; vCnt + 2; vLen - vCnt)

vDirectoryName = SUBSTR(vDestination; 1; vCnt)

IF(DOESDIRECTORYEXIST(vDirectoryName) = True)

RETURN

ELSE

ErrorMsg(vDirectoryName + " does not exist")

ENDIF

LABEL(CopyFiles)

IF(COPYFILE(vSource; vDestination; NoPrompts!) = True)

MESSAGEBOX(x; "COPYFILE"; "File copied successfully"; IconInformation!)

ELSE

ErrorMsg("File not copied")

ENDIF

RETURN

PROCEDURE ErrorMsg(Msg)

BEEP

MESSAGEBOX(x; "Error"; Msg; IconExclamation!)

QUIT

ENDPROC


example 8019


example 8053


example 8052


example 8054


example 8055


example 8056


example 8051
APPLICATION(A1; "WordPerfect"; Default; "US")

// Returns the handle of five push button controls

// Demonstrate DIALOGHANDLE command

VARERRCHK(Off!)

DIALOGDEFINE(1000; 50; 50; 100; 190; Percent!; "DIALOGHANDLE")

FORNEXT(x; 1; 5; 1)

DIALOGADDPUSHBUTTON(1000; x; 10; x + (x * 20) - 10; 75; 15; NonDefaultBttn!; "Button " + x)

ENDFOR

DIALOGADDTEXT(1000; -1; 10; 120; 75; 40; RecessBox! | Left!; "Press Enter, or choose Close from the system menu box.")

DIALOGSHOW(1000; 1)

vResult := ""

FOREACH(vControl; {"1"; "2"; "3"; "4"; "5"})

vResult := vResult + "Button " + vControl + ": "

DIALOGHANDLE(vHandles; 1000; vControl)

vResult := vResult + vHandles + ".  "

ENDFOR

MESSAGEBOX(x; "CONTROL HANDLES"; vResult)

DIALOGDESTROY(1000)


example 8050
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate DIALOGADDSCROLLBAR command with callback function

SB_LINEUP := 0

SB_LINEDOWN := 1

WM_SYSCOMMAND := 274

WM_HSCROLL := 276

DIALOGDEFINE(1000; 50; 50; 125; 70; Percent!; "SCROLL BAR")

DIALOGADDTEXT(1000; -1; 10; 10; 100; 15; Center! | RecessBox!; "Click the left or right arrow")

DIALOGADDSCROLLBAR(1000; "Scroll"; 10; 30; 100; 0; Left! | HScroll!; BarPos; 1; 3)

DIALOGSHOW(1000; "Scroll"; Msg)

Stop := 1

WHILE(Stop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

SWITCH(Msg[5])

CASEOF WM_SYSCOMMAND: Stop := 0

CASEOF WM_HSCROLL: CALL(Scroll)

ENDSWITCH

RETURN

LABEL(Scroll)

SWITCH(Msg[6])

CASEOF SB_LINEUP:

MESSAGEBOX(x; "CALLBACK FUNCTION"; "You clicked the left arrow"; IconInformation!)

CASEOF SB_LINEDOWN:

MESSAGEBOX(x; "CALLBACK FUNCTION"; "You clicked the right arrow"; IconInformation!)

ENDSWITCH

RETURN


example 8046
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate DIALOGADDFILENAMEBOX, DIALOGADDEDITBOX, and DIALOGADDVIEWER

VARERRCHK(Off!)

ASSIGN(vText; "Note that DIALOGDEFINE uses Enter2HRtn! style with this edit box control.")

DIALOGDEFINE (1000; 50; 50; 195; 225; OK! | Percent! | Enter2HRtn!; "DIALOGADDCONTROL")

DIALOGADDTEXT(1000; -1; 10; 10; 100; 15; Left!; "DIALOGADDFILENAMEBOX")

DIALOGADDFILENAMEBOX(1000; 100; 10; 20; 170; 15; FilesAndDirs!; vDir; "c:\")

DIALOGADDTEXT(1000; -2; 10; 40; 100; 15; Left!; "DIALOGADDEDITBOX")

DIALOGADDEDITBOX(1000; 101; 10; 50; 170; 50; Left! | Multiline! | WordWrap! | VScroll!; vText; 1000)

DIALOGADDTEXT(1000; -3; 10; 105; 100; 15; Left!; "DIALOGADDVIEWER")

DIALOGADDVIEWER(1000; 102; 10; 115; 170; 60; "C:\AUTOEXEC.BAT")

DIALOGSHOW(1000; 100)

DIALOGDESTROY(1000)

IF(STRLEN(vDir) = 0)

Msg("You did not enter a path or filename")

ELSE

MESSAGEBOX(x; "DIALOGADDFILENAMEBOX"; "You entered the following path or path and filename: " + vDir)

ENDIF

IF(STRLEN(vText) = 0)

Msg("You did not enter text in the edit control")

ELSE

MESSAGEBOX(x; "DIALOGADDEDITBOX"; "You entered the following text in the edit control: " + NTOC(0F90Ah) + NTOC(0F90Ah) + vText)

ENDIF

PROCEDURE Msg(x)

BEEP

MESSAGEBOX(x; "Oops!"; x; IconExclamation!)

ENDPROC


example 8047
APPLICATION(A1; "WordPerfect"; Default; "US")

// Use array SortStr to sort up to eight character strings by length

// Calculate width of dialog box from longest string and height from the number of strings

// Demonstrate DIALOGADDFRAME command

CALL(GetNumberAndStrings)

CALL(GetDimensions)

CALL(DisplaySortedStrings)

LABEL(GetNumberAndStrings)

GETNUMBER(vNmbr; "Number of strings to sort (up to eight):"; "FRAME EXAMPLE")

IF(vNmbr > 8)

vNmbr := 8

ENDIF

DECLARE StrSort[vNmbr]

FORNEXT(x; 1; vNmbr; 1)

GETSTRING(StrSort[x]; "String " + x + ":"; "SORT " + vNmbr + " STRINGS"; 50)

ENDFOR

RETURN

LABEL(GetDimensions)

vSorted := 1

WHILE(vSorted = 1)

vSorted := 0

FOR(x; 1; x < vNmbr; x + 1)

IF(STRLEN(StrSort[x]) < STRLEN(StrSort[x + 1]))

vTemp := StrSort[x]

StrSort[x] := StrSort[x + 1]

StrSort[x + 1] := vTemp

vSorted := 1

ENDIF

ENDFOR

ENDWHILE

x := 20

y := 20

w := STRLEN(StrSort[1]) + (STRLEN(StrSort[1]) * 4)

h := 13

RETURN

LABEL(DisplaySortedStrings)

DIALOGDEFINE(1000; 50; 50; w + 45; 40 + 30 * vNmbr; Percent!; "FRAME CONTROL")

FORNEXT(r; 1; vNmbr; 1)

DIALOGADDFRAME(1000; r; x - 5;  y - 5 + (r * 30) - 30; w + 10; h + 7; Frame! | Gray!)

DIALOGADDTEXT(1000; 0; x; y + (r * 30) - 30; w; h; Center!; TOUPPER(StrSort[r]))

ENDFOR

DIALOGSHOW(1000; 1)

DIALOGDESTROY(1000)

QUIT


example 8048
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate group controls and buttons

VARERRCHK(Off!)

DIALOGDEFINE(1000; 50; 50; 200; 140; Percent!; "GROUP CONTROLS AND BUTTONS")

DIALOGADDGROUPBOX(1000; -1; 10; 10; 75; 55; "Radio Buttons")

DIALOGADDRADIOBUTTON(1000; 100; 25; 25; 50; 15; "Example 1"; vRadio1)

DIALOGADDRADIOBUTTON(1000; 101; 25; 45; 50; 15; "Example 2"; vRadio2)

DIALOGADDVLINE(1000; -2; 125; 15; 55)

DIALOGADDPOPUPBUTTON(1000; 102; 135; 35; 50; 13; vPopup)

DIALOGADDLISTITEM(1000; 102; "Popup 1")

DIALOGADDLISTITEM(1000; 102; "Popup 2")

DIALOGADDLISTITEM(1000; 102; "Popup 3")

DIALOGADDHLINE(1000; -3; 10; 85; 175)

DIALOGADDPUSHBUTTON(1000; 103; 15; 95; 165; 13; DefaultBttn!; "Cancel")

DIALOGSHOW(1000; 103)

IF(vRadio1 <> 0)

vMessage := "You selected radio button 1. "

ELSE

IF(vRadio2 <> 0)

vMessage := "You selected radio button 2. "

ELSE

vMessage := "You didn't select a radio button. "

ENDIF

ENDIF

vMessage := vMessage + "You selected " + vPopup + ". "

IF(MacroDialogResult = 103)

vMessage := vMessage + "You chose Cancel to close the dialog box."

MESSAGEBOX(x; "MESSAGE BOX"; vMessage; IconInformation!)

ELSE

BEEP

MESSAGEBOX(x; "MESSAGE BOX"; "You chose a system command to close the dialog box"; IconExclamation!)

ENDIF

DIALOGDESTROY(1000)


example 8049
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate DIALOGADDLISTBOX and DIALOGADDLISTITEM

DECLARE Fruit[5]

y := 10

DIALOGDEFINE(1000; 50; 50; 122; 155; OK! | Percent! | NoFrame!; "SORTED LIST BOX")

FOREACH(vList; {"Apples"; "Oranges"; "Bananas"; "Grapes"; "Pears"})

DIALOGADDTEXT(1000; 0; 10; y; 30; 15; Left!; vList)

DIALOGADDHOTSPOT(1000; y; 10; y; 30; 9; Click!)

FRUIT[y/10] := vList

y := y + 10

ENDFOR

DIALOGADDLISTBOX(1000; 103; 50; 10; 60; 50; Sorted!; vChoice)

DIALOGADDTEXT(1000; 0; 10; 75; 102; 35; Left! | RecessBox!; "Click a ""fruit"" to display in the list box.  Click a list box item and choose OK when finished.")

DIALOGSHOW(1000; 102; Msg)

Stop  := 0

WHILE(Stop = 0)

ENDWHILE

DIALOGDESTROY(1000)

IF(vChoice = "")

vMessage := "You didn't select a list box item " + vChoice

ELSE

vMessage := "You selected " + vChoice

ENDIF

MESSAGEBOX(x; "LIST BOX CHOICE"; vMessage; IconInformation!)

QUIT

LABEL(Msg)

IF(Msg[5] = 274)

Stop := 1

ENDIF

SWITCH(Msg[3])

CASEOF 10: DIALOGADDLISTITEM(1000; 103; Fruit[1])

CASEOF 20: DIALOGADDLISTITEM(1000; 103; Fruit[2])

CASEOF 30: DIALOGADDLISTITEM(1000; 103; Fruit[3])

CASEOF 40: DIALOGADDLISTITEM(1000; 103; Fruit[4])

CASEOF 50: DIALOGADDLISTITEM(1000; 103; Fruit[5])

CASEOF "OKBttn":

DIALOGUNDISPLAY(1000; "OKBttn")

Stop := 1

ENDSWITCH

RETURN


example 8057
// Create a DOS or Windows* dialog box

// Demonstrate IFPLATFORM command

// compile on DOS platform

IFPLATFORM(DOS)

DLGCREATE(x; "TITLE"; DLGNoCancel!;;;30;14)

DLGCONTROL(CtrlRadioButton!;a;"Letter";StyInitial!;4;4;;2)

DLGCONTROL(CtrlRadioButton!;b;"Itinerary";;4;6;;2)

DLGCONTROL(CtrlRadioButton!;c;"Memo";;4;8;;2)

DLGCONTROL(CtrlRadioButton!;d;"Fax";;4;10;;2)

DLGEND

SWITCH(1)

CASEOF a: BEEP

CASEOF b: BEEP

CASEOF c: BEEP

CASEOF d: BEEP

ENDSWITCH

ENDIFPLATFORM

// compile on Windows* platform

IFPLATFORM(WIN95)

APPLICATION(A1; "WordPerfect"; Default; "US")

DIALOGDEFINE(1000; 50; 50; 100; 125; Style:OK!; Caption:"TITLE")

DIALOGADDRADIOBUTTON(1000; 1; 10; 10; 75; 15; ButtonText:"Letter"; a)

DIALOGADDRADIOBUTTON(1000; 2; 10; 25; 75; 15; ButtonText:"Itinerary"; b)

DIALOGADDRADIOBUTTON(1000; 3; 10; 40; 75; 15; ButtonText:"Memo"; c)

DIALOGADDRADIOBUTTON(1000; 4; 10; 55; 75; 15; ButtonText:"Fax"; d)

DIALOGSHOW(1000; 1)

SWITCH(1)

CASEOF a: vMsg := "Letter"

CASEOF b: vMsg := "Itinerary"

CASEOF c: vMsg := "Memo"

CASEOF d: vMsg := "Fax"

ENDSWITCH

MESSAGEBOX(x; "Selection"; vMsg; IconInformation!)

DIALOGDESTROY(1000)

ENDIFPLATFORM


example 8058
APPLICATION(A1; "WordPerfect"; Default; "US")

// Compiling this macro produces a compile-time syntax error

// To compile, make the second AboutDlg a comment (//)

// Demonstrate ENDAPP command

AboutDlg

ENDAPP(A1)

AboutDlg


example 8066
APPLICATION(WP; "WordPerfect"; Default; "US")

// Command: REGIONENABLEWINDOW

Loop = 1

WM_SYSCOMMAND = 274

vDisable = 1

DIALOGDEFINE(1000; 50; 50; 155; 75; Percent! | NoFrame!; "RegionEnableWindow")

DIALOGADDFRAME(1000; 100; 10; 10; 10; 10; Frame! | Filled! | Gray!)

DIALOGADDHOTSPOT(1000; 101; 10; 10; 10; 10; Click!)

DIALOGADDTEXT(1000; 0; 28; 10; 125; 15; Left!; "Click to disable/enable check box")

DIALOGADDCHECKBOX(1000; 102; 55; 30; 50; 15; "Check box"; var)

DIALOGSHOW(1000; 101; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(Msg[3] = 101)

IF(vDisable = 1)

REGIONENABLEWINDOW("1000.102"; Disable!)

vDisable = 0

ELSE

REGIONENABLEWINDOW("1000.102"; Enable!)

vDisable = 1

ENDIF

ENDIF

RETURN


example 8065
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONADDLISTITEM command

Loop = 1

ListItem = 1

WM_SYSCOMMAND = 274

DIALOGDEFINE(1000; 50; 50; 107; 125; Percent! | NoFrame!; "RegionAddListItem")

DIALOGADDFRAME(1000; 100; 10; 10; 10; 10; Frame! | Filled! | Gray!)

DIALOGADDHOTSPOT(1000; 101; 10; 10; 10; 10; Click!)

DIALOGADDTEXT(1000; 0; 28; 10; 75; 15; Left!; "Click to add list item")

DIALOGADDLISTBOX(1000; 102; 10; 35; 85; 75; Sorted!; var)

DIALOGSHOW(1000; 101; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(Msg[3] = 101)

AddListBoxItem

ENDIF

RETURN

LABEL(AddListBoxItem)

vItem = "Item " + ListItem

REGIONADDLISTITEM("1000.102"; vItem)

ListItem = ListItem + 1

RETURN


example 8067
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONGETCHECK command

Loop = 1

WM_SYSCOMMAND = 274

DIALOGDEFINE(1000; 20; 30; 135; 75; NoFrame!; "RegionGetCheck")

DIALOGADDFRAME(1000; 100; 10; 10; 10; 10; Frame! | Filled! | Gray!)

DIALOGADDHOTSPOT(1000; 101; 10; 10; 10; 10; Click!)

DIALOGADDTEXT(1000; 0; 28; 10; 125; 15; Left!; "Click to get check box state")

DIALOGADDCHECKBOX(1000; 102; 30; 35; 20; 15; "1"; var)

DIALOGADDCHECKBOX(1000; 103; 60; 35; 20; 15; "2"; var)

DIALOGADDCHECKBOX(1000; 104; 90; 35; 20; 15; "3"; var)

DIALOGSHOW(1000; 101; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(Msg[3] = 101)

REGIONGETCHECK(vChk1; "1000.102")

REGIONGETCHECK(vChk2; "1000.103")

REGIONGETCHECK(vChk3; "1000.104")

FORNEXT(x; 1; 3; 1)

IF(INDIRECT("vChk" + x) = 1)

ASSIGN(INDIRECT("vChk" + x); "selected")

ELSE

ASSIGN(INDIRECT("vChk" + x); "not selected")

ENDIF

ENDFOR

MESSAGEBOX(vYesNo; "Check Box State"; "1: " + vChk1 + NTOC(0F90Ah) + "2: " + vChk2 + NTOC(0F90Ah) + "3: " + vChk3)

ENDIF

RETURN


example 8068
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONGETSELECTEDTEXT command

Loop = 1

lParam = 7

WM_SYSCOMMAND = 274

DIALOGDEFINE(1000; 20; 30; 107; 125; NoFrame!; "RegionGetSelectedText")

DIALOGADDTEXT(1000; 0; 0; 15; 107; 15; Center!; "Select a fruit")

DIALOGADDLISTBOX(1000; 102; 10; 35; 85; 75; Sorted!; var)

FOREACH(vList; {"Apples"; "Bananas"; "Oranges"; "Grapes"; "Pears"; "Corn"})

DIALOGADDLISTITEM(1000; 102; vList)

ENDFOR

DIALOGHANDLE(hItem; 1000; 102)

DIALOGSHOW(1000; 102; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(LWORD(Msg[lParam]) = hItem)

REGIONGETSELECTEDTEXT(vSelectItem; "1000.102")

IF(vSelectItem = "Corn")

BEEP

MESSAGEBOX(z; "Error"; "You didn't select a fruit!"; IconExclamation!)

ELSE

MESSAGEBOX(z; "List Box Item"; "You selected " + vSelectItem)

ENDIF

ENDIF

RETURN

FUNCTION LWORD(vNum)

vNum = vNum & 65535

RETURN(vNum)

ENDFUNC


example 8069
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONAGETWINDOWTEXT command

Loop = 1

WM_SYSCOMMAND = 274

DIALOGDEFINE(1000; 50; 50; 158; 50; Percent! | NoFrame!; "RegionGetWindowText")

DIALOGADDFRAME(1000; 100; 10; 10; 10; 10; Frame! | Filled! | Gray!)

DIALOGADDHOTSPOT(1000; 101; 10; 10; 10; 10; Click!)

DIALOGADDTEXT(1000; 0; 28; 10; 125; 15; Left!; "Click to retrieve the caption bar title")

DIALOGSHOW(1000; 101; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(Msg[3] = 101)

GetTitle

ENDIF

RETURN

LABEL(GetTitle)

REGIONGETWINDOWTEXT(vTitle; "1000")

MESSAGEBOX(x; "Region Commands"; "The caption bar title is " + vTitle; IconInformation!)

Loop = 0

RETURN


example 8064
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate DIMENSIONS command

HRt = NTOC(0F90Ah)

DECLARE array[4; 2; 5]

v1 = DIMENSIONS(array[])

v2 = DIMENSIONS(array[]; 0)

v3 = DIMENSIONS(array[]; 1)

v4 = DIMENSIONS(array[]; 2)

v5 = DIMENSIONS(array[]; 3)

v6 = DIMENSIONS(array[]; 4)

v7 = DIMENSIONS(c)

v8 = DIMENSIONS(b[])

vMsg = v1 + HRt + v2 + HRt + v3 + HRt + v4 + HRt + v5 + HRt + v6 + HRt + v7 + HRt + v8

MESSAGEBOX(x; "DIMENSIONS"; "Variables v1 - v8 values:" + Hrt + Hrt + vMsg)


example 8063


example 8059
This command is included for DOS compatibility.  The windows equivalent is Menu.


example 8060
This command is included for DOS compatibility.  The windows equivalent is Run.


example 8061
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate DIALOGDISPLAY command

HRt = NTOC(0F90Ah)

HSp = "     "

vCombo = "Combo item 1"

vList = "List item 1"

WM_COMMAND = 273

WM_SYSCOMMAND = 274

DIALOGDEFINE(1000; 50; 50; 160; 125; Percent! | NoFrame! | Cancel!; "WM_COMMAND")

DIALOGADDLISTBOX(1000; 100; 10; 10; 60; 30; Sorted!; vList)

DIALOGADDLISTITEM(1000; 100; "List item 1")

DIALOGADDLISTITEM(1000; 100; "List item 2")

DIALOGADDLISTITEM(1000; 100; "List item 3")

DIALOGADDCOMBOBOX(1000; 101; 10; 50; 60; 40; Droplist!; vCombo; 100)

DIALOGADDLISTITEM(1000; 101; "Combo item 1")

DIALOGADDLISTITEM(1000; 101; "Combo item 2")

DIALOGADDLISTITEM(1000; 101; "Combo item 3")

DIALOGADDPOPUPBUTTON(1000; 102; 10; 80; 60; 15; vPopup)

DIALOGADDLISTITEM(1000; 102; "Popup item 1")

DIALOGADDLISTITEM(1000; 102; "Popup item 2")

DIALOGADDLISTITEM(1000; 102; "Popup item 3")

DIALOGADDPUSHBUTTON(1000; 103; 100; 10; 50; 15; NonDefaultBttn!; "Push Button")

DIALOGADDRADIOBUTTON(1000; 104; 100; 35; 50; 15; "Radio"; vRadio)

DIALOGADDCHECKBOX(1000; 105; 100; 60; 50; 15; "Check box"; vCheck)

DIALOGHANDLE(hButton; 1000; 103)

DIALOGHANDLE(hRadio; 1000; 104)

DIALOGHANDLE(hCheck; 1000; 105)

DIALOGDISPLAY(1000; 1; Msg)

x := 0

While(x = 0)

Endwhile

DIALOGDESTROY(1000)

LABEL(MSG)

IF((Msg[5] = WM_SYSCOMMAND) OR (Msg[3] = "CancelBttn"))

BEEP

x = 1

RETURN

ENDIF

IF(Msg[5] = WM_COMMAND)

lParam = Msg[7]

DIALOGUNDISPLAY(1000; 1)

MsgBox

DIALOGDISPLAY(1000; 1; Msg)

ENDIF

RETURN

LABEL(MsgBox)

SWITCH(LOWRD(lParam))

CASEOF hButton: vHandle = hButton

CASEOF hRadio: vHandle = hRadio

CASEOF hCheck: vHandle = hCheck

DEFAULT: vHandle = "N/A"

ENDSWITCH

Lo = "Low-word: " + LOWRD(lParam) + HRt + HRt

Hi = "High-word: " + HIWRD(lParam) + HRt + HRt

Handle = "Control handle: " + vHandle + HRt + HRt

ListItems = "Selected list items:" + HRt + HRt + HSp + vPopup + HRt + HSp + vList + HRt + HSp + vCombo + HRt

MESSAGEBOX(vResult; "WM_COMMAND"; Hi + Lo + Handle + ListItems)

RETURN

FUNCTION LOWRD(lo)

lo = lo & 65535

Return(lo)

ENDFUNC

FUNCTION HIWRD(hi)

hi = hi >> 16

RETURN(hi)

ENDFUNC


example 8062


example 8045
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate DIALOGADDHOTSPOT and DIALOGADDICON

VARERRCHK(Off!)

Yes := 6

WM_SYSCOMMAND := 274

DialogControl := 3

DIALOGDEFINE (1000; 50; 50; 115; 85; Percent! | NoFrame!; "DIALOGADDICON" )

DIALOGADDTEXT(1000; -1; 10; 10; 50; 13; Left!; "Click an icon:")

FORNEXT(z; 1; 3; 1)

DIALOGADDICON (1000; 0; 25; z + 10 + (z * 13); 10; 8; "#" + (z+159); 0)

DIALOGADDHOTSPOT(1000; z; 25; z + 10 + (z * 13); 10; 8; Click!)

ENDFOR

DIALOGSHOW(1000; 0; Msg)

WHILE(NOT(vStatus = Yes))

ENDWHILE

DIALOGDESTROY (1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

vStatus = Yes

ENDIF

SWITCH(Msg[DialogControl])

CASEOF 1: MESSAGEBOX(vStatus; "DIALOGADDHOTSPOT"; "Overlap hot spots and icons to create custom controls."; IconExclamation!)

CASEOF 2:MESSAGEBOX(vStatus; "DIALOGADDHOTSPOT"; "See the WordPerfect for Windows Software Developer's Kit for PerfectFit* information."; IconInformation!)

CASEOF 3:MESSAGEBOX(vStatus; "DIALOGADDHOTSPOT"; "Are you finished with this example?"; IconQuestion! | YesNo!)

ENDSWITCH

RETURN


example 8044
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate DIALOGADDCONTROL and SENDKEYS commands

InhibitInput(Off!)

WM_SYSCOMMAND := 274

z := 0

DIALOGDEFINE (1000; 50; 50; 122; 150; Percent! | NoFrame! | OK!; "DIALOGADDCONTROL")

DIALOGADDCHECKBOX(1000; 100; 10; 10; 75; 15; "Check for demo"; vCB)

DIALOGADDCONTROL(1000; 101; 10; 40; 100; 75; "wpnslb20"; 2; ""; vListItem; 0)

A := "Apple"

B := "Apple pie"

C := "Applesauce"

D := "Banana"

E := "Banana oil"

F := "Banana seat"

G := "Banana split"

FORNEXT(x; 65; 71; 1)

DIALOGADDLISTITEM(1000; 101; INDIRECT(NTOC(x)))

ENDFOR

DIALOGSHOW(1000; 101; Msg)

WHILE(z = 0)

ENDWHILE

DIALOGDESTROY(1000)

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

z := 1

ENDIF

SWITCH(Msg[3])

CASEOF 100: Demo

CASEOF "OKBttn": DIALOGUNDISPLAY(1000; 101)

IF(STRLEN(vListItem) > 0)

ASSIGN(vSelect; "You selected """ + vListItem + """ from the list box")

ELSE

ASSIGN(vSelect; "You didn't select an item from the list box")

ENDIF

MESSAGEBOX(x; "LIST ITEM"; vSelect; IconInformation!)

z := 1

ENDSWITCH

RETURN

LABEL(Demo)

SENDKEYS WAIT("{Tab} {Up}")

FOREACH(vLetter; {"A"; "p"; "p"; "l"; "e"; "s"; "a"; "u"; "c"; "e"})

SENDKEYS WAIT(vLetter)

WAIT(3)

ENDFOR

WAIT(12)

FORNEXT(w; 1; 10; 1)

SENDKEYS WAIT("{BackSpace}")

WAIT(1)

ENDFOR

WAIT(10)

FOREACH(vLetter; {"B"; "a"; "n"; "a"; "n"; "a"; " "; "s"; "p"; "l"; "i"; "t"})

SENDKEYS WAIT(vLetter)

WAIT(3)

ENDFOR

WAIT(12)

SENDKEYS WAIT("{Tab}")

MESSAGEBOX(x; "NAME SEARCH LIST BOX"; "Enter a word from the list to experiment with WordPerfect's custom list box")

SENDKEYS WAIT("{Up}")

RETURN


example 8027
APPLICATION(A1; "WordPerfect"; Default; "US")

APPLICATION(A2; "WordPerfect"; "US")

// AboutDlg does not require a product prefix

AboutDlg()

NEWDEFAULT(A2)

// WordPerfect is not the default application

// AboutDlg requires a product prefix (A2)

A2.AboutDlg()


example 8026
APPLICATION(A1; "WordPerfect"; Default; "US")

// Speak an ASCII text file

// A text-to-speech driver must be installed

// Demonstrate MMSPEAK, MMSPEAKCLIPBOARD, MMSTOPSPEECH commands

REPEAT

MENU(vChoice; Digit; ; ; {"File"; "Clipboard"; "Quit"})

SWITCH(vChoice)

CASEOF 1:

GETSTRING(vStr; "Enter the path and name of a file to speak:"; "ASCII TEXT FILE")

IF(vStr = "")

BREAK

ELSE

MMSPEAK(vStr)

CancelMessage()

ENDIF

CASEOF 2:

MMSPEAKCLIPBOARD

CancelMessage()

ENDSWITCH

UNTIL(vChoice = 3)

QUIT

PROCEDURE CancelMessage()

vCancel := 2

MESSAGEBOX(vStatus; "SPEAK FILE"; "Choose Cancel any time to stop speech"; IconStop! | RetryCancel!)

IF(vStatus = vCancel)

MMSTOPSPEECH

ENDIF

ENDPROC


example 8028
APPLICATION(A1; "WordPerfect"; Default; "US")

// Convert integer to Character equivalent

// NTOC(32) returns "space" character

// Demonstrate NTOC command

AddTextBox (1000w;9000w;12000w;8000w)

FOR(int; 33; int < 127; int + 1)

Type(NTOC(int) + (NTOC(32)))

ENDFOR

// Convert character set value to character equivalent

FOR(int; 0; int < 102; int + 1)

Type(NTOC(4; int) + (NTOC(32)))

ENDFOR

MESSAGEBOX(vAns; "NTOC command"; "Close Text Box?"; YesNo! | IconQuestion!)

IF(vAns = 6)

TextEditExit()

ENDIF


example 8029


example 8030
APPLICATION(A1; "WordPerfect"; Default; "US")

// Test Error condition

// Demonstrate ONERROR CALL command

ONERROR CALL(ErrorTest)

No := 7

REPEAT

GETNUMBER(vNmbr; "Enter 3 and press <Enter>:"; "ONERROR CALL EXAMPLE")

IF(vNmbr = 3)

MESSAGEBOX(vStatus; "YES!"; "You entered 3 as requested.  Do you want to try again?"; IconInformation! | YesNo!)

ELSE

ASSERT(ErrorCondition!)

ENDIF

UNTIL(vStatus = No)

QUIT

LABEL(ErrorTest)

BEEP

MESSAGEBOX(vStatus; "ERROR"; "You didn't enter 3 as requested"; IconExclamation!)

RETURN


example 8025
APPLICATION(A1; "WordPerfect"; Default; "US")

// Play .wav file

// Assume Windows* sound system and that appropriate driver is installed

// Demonstrate MMPLAY and WAIT commands

No := 7

REPEAT

MENU(vWav; Digit; ; ; {"Siren"; "Crickets"; "Snoring"; "Thunder"; "Dog bark"; "Elephant"; "Quit"})

SWITCH(vWav)

CASEOF 1: PlaySound("siren.wav"; 115)

CASEOF 2: PlaySound("crickets.wav"; 50)

CASEOF 3: PlaySound("snoring.wav"; 30)

CASEOF 4: PlaySound("thunder.wav"; 30)

CASEOF 5: PlaySound("dogbark.wav"; 15)

CASEOF 6: PlaySound("elephant.wav"; 15)

CASEOF 7: QUIT

ENDSWITCH

MESSAGEBOX(vStatus; "MMPLAY"; "Would you like to hear another sound?"; IconQuestion! | YesNo!)

UNTIL(vStatus = No)

PROCEDURE PlaySound(vSound; vWait)

MMPLAY("c:\windows\sndsys\sounds\" + vSound)

WAIT(vWait)

ENDPROC


example 8024
APPLICATION(A1; "WordPerfect"; Default; "US")

// Remember: functions must be called to execute

// Demonstrate FUNCTION and FUNCTION PROTOTYPE commands

FUNCTION PROTOTYPE Check(vBeep; HdReturn)

HdReturn := NTOC(0F90Ah)

x := 4

vBeep := 1

WHILE(x = 4)

BEEP

x := Check(vBeep; HdReturn)

vBeep := vBeep + 1

ENDWHILE

MESSAGEBOX(z; "RETURN"; "The value of variable vStatus (" + x + ") is returned to variable x, which ends the loop."; IconExclamation!)

FUNCTION Check(vBeep; HdReturn)

MESSAGEBOX(vStatus; "FUNCTION EXAMPLE"; "Beeps: " + vBeep + HdReturn + HdReturn + "Choose Retry to beep again." + HdReturn; IconInformation! | RetryCancel!)

RETURN(vStatus)

ENDFUNC


example 8020
APPLICATION(A1; "WordPerfect"; Default; "US")

// LABEL(ErrorMsg) executes with ERROR(On!)

// Demonstrate ERROR command

ONERROR(ErrorMsg)

REPEAT

MENU(vChoice; Digit; ; ; {"ERROR(Off!)"; "ERROR(On!)"; "Quit"})

CASE CALL(vChoice; {1; OffMsg; 2; OnMsg; 3; QuitMacro}; QuitMacro)

UNTIL(vChoice = 3)

LABEL(OffMsg)

ERROR(Off!)

ASSERT(ErrorCondition!) // ignore Error condition

MESSAGEBOX(x; "ERROR(Off!)"; "Error condition ignored"; IconInformation!)

RETURN

LABEL(OnMsg)

ERROR(On!)

ASSERT(ErrorCondition!) // LABEL(ErrorMsg) executed

RETURN

LABEL(ErrorMsg)

BEEP

MESSAGEBOX(x; "ERROR CONDITION"; "An error condition causes LABEL(ErrorMsg) to execute"; IconInformation!)

RETURN

LABEL(QuitMacro)

QUIT


example 8021
APPLICATION(A1; "WordPerfect"; Default; "US")

// LABEL(NotFoundMsg) executes with NOTFOUND(On!)

// Demonstrate NOTFOUND command

ONNOTFOUND(NotFoundMsg)

REPEAT

MENU(vChoice; Digit; ; ; {"NOTFOUND(Off!)"; "NOTFOUND(On!)"; "Quit"})

CASE CALL(vChoice; {1; OffMsg; 2; OnMsg; 3; QuitMacro}; QuitMacro)

UNTIL(vChoice = 3)

LABEL(OffMsg)

NOTFOUND(Off!)

ASSERT(NotFoundCondition!) // ignore Not Found condition

MESSAGEBOX(x; "NOTFOUND(Off!)"; "Not Found condition ignored"; IconInformation!)

RETURN

LABEL(OnMsg)

NOTFOUND(On!)

ASSERT(NotFoundCondition!) // LABEL(NotFoundMsg) executed

RETURN

LABEL(NotFoundMsg)

BEEP

MESSAGEBOX(x; "NOTFOUND CONDITION"; "A Not Found condition causes LABEL(NotFoundMsg) to execute"; IconInformation!)

RETURN

LABEL(QuitMacro)

QUIT


example 8022
APPLICATION(A1; "WordPerfect"; Default; "US")

// Declare and test variable types

// Demonstrate BREAK, EXISTS, LOCAL, GLOBAL, and PERSIST commands

DISCARD var5; var1; var7

LOCAL var2; var9; var4

GLOBAL var3; var10; var6

PERSIST var5; var1; var7

ASSIGN(var8; "")

FOR(x; 1; x < 11; x + 1)

ASSIGN(INDIRECT("var" + x); x)

MESSAGEBOX(vStatus; "VAR" + x; "Continue to next variable?"; IconQuestion! | YesNo!)

IF(vStatus = 7)

BREAK

ENDIF

ENDFOR

FOR(z; 1; z < (x + 1); z + 1)

SWITCH(EXISTS(INDIRECT("var" + z)))

CASEOF 1: Msg("Local"; z)

CASEOF 2: Msg("Global"; z)

CASEOF 3: Msg("Persist"; z)

ENDSWITCH

ENDFOR

FUNCTION Msg(w; y)

MESSAGEBOX(z; "VARIABLE TYPES"; "var" + y + " = " + w)

ENDFUNC


APPLICATION(A1; "WordPerfect"; Default; "US")

// Calculate fractions and integers

// Demonstrate FRACTION and INTEGER commands

ONCANCEL(QuitMacro)

ASSIGN(HdReturn; NTOC(0F90Ah)) // hard return code

REPEAT

GETNUMBER(vNmbr; "Enter a real number:"; "FRACTION EXAMPLE")

ASSIGN(vInteger; INTEGER(vNmbr))

ASSIGN(vFraction; FRACTION(vNmbr))

vMsg1 := "The integer portion of " + vNmbr + " is " + vInteger

vMsg2 := "The fractional portion of " + vNmbr + " is " + vFraction

MESSAGEBOX(x; "INTEGER - FRACTION"; vMsg1 + HdReturn + HdReturn + vMsg2 + HdReturn; IconInformation! | RetryCancel!)

UNTIL(x = 2)

LABEL(QuitMacro)

QUIT


example 8031
APPLICATION(A1; "WordPerfect"; Default; "US")

// Test Not Found condition

// Open view and retrieve text into the message box

// Demonstrate ONNOTFOUND command

NOTFOUND(On!)

ONNOTFOUND CALL(NotFoundTest)

No := 7

REPEAT

GETSTRING(vStr; "Enter a string to search for and press <Enter>:"; "ONNOTFOUND CALL EXAMPLE")

IF(vStr = "")

NEXT

ENDIF

vError := False

PosTextTop()

Find(MessageSearchString: vStr; SearchDir: Forward!; MessageMatch: BeginText!)

IF(vError = False)

vMessage := "Success!  Do you want to try again?"

ELSE

vMessage := "Not Found condition.  Do you want to try again?"

ENDIF

MESSAGEBOX(vStatus; "Search"; vMessage; IconInformation! | YesNo!)

UNTIL(vStatus = No)

QUIT

LABEL(NotFoundTest)

BEEP

MESSAGEBOX(vError; "ERROR"; """" + vStr + """ not found"; IconExclamation!)

vError := True

RETURN // return to IF statement following Find command


example 8032
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate PAUSE command

ONCANCEL(EndLoop)

InhibitInput(Off!)

InformationIcon := 4

x := 1

AddTextBox(1000w;9000w;12000w;8000w;)

REPEAT

Type(x + NTOC(32))

IF(x MOD 10 = 0)

PROMPT("PAUSE EXAMPLE"; "Choose OK to dismiss prompt and continue loop, or Cancel to end loop."; InformationIcon)

PAUSE

ENDIF

x := x + 1

UNTIL(x = 0)

LABEL(EndLoop)

QUIT


example 8040
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate TOLOWER and VARERRCHK command

HdReturn := NTOC(0F90Ah)

VARERRCHK(Off!)

FOR(x; 65; x < 91; x + 1)

// convert uppercase character to lowercase

// vLongStr not declared - no value assigned

vLongStr := vLongStr + TOLOWER(NTOC(x)) + NTOC(32)

ENDFOR

MESSAGEBOX(x; "VARERRCHK and TOLOWER"; "With VARERRCHK(On!), you would receive a run-time error message." + HdReturn + HdReturn + "vLongStr: "  + vLongStr + HdReturn; IconInformation!)


example 8039
APPLICATION(A1; "WordPerfect"; Default; "US")

// Extract "Perfect" from WordPerfect and test if "program" was typed

// Demonstrate STRPOS and SUBSTR commands

vNumbers := ""

LABEL(Start)

GETSTRING(vStr; "Enter the following text: ""WordPerfect program"""; "SUBSTR AND STRPOS EXAMPLES")

IF(vStr = "")

BEEP

MESSAGEBOX(x; "ERROR"; "You pressed return without entering any text"; IconStop!)

GO(Start)

ENDIF

vSub := SUBSTR(vStr; 5; 7)

IF(vSub = "Perfect")

MESSAGEBOX(x; "SUBSTR EXAMPLE"; "WordPerfect is simply """ + vSub + """"; IconInformation!)

IF(STRPOS(vStr; "program") = 0)

BEEP

MESSAGEBOX(x; "STRPOS EXAMPLE"; "You entered ""WordPerfect"" but not ""program"""; IconExclamation!)

ENDIF

ELSE

BEEP

MESSAGEBOX(x; "ERROR"; """WordPerfect"" wasn't the first word"; IconExclamation!)

GO(Start)

ENDIF


example 8041
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate UNITSTR and DIALOG commands

vNmbr := 1

vStatus := 4

DIALOGDEFINE(1000; 50; 50; 100; 120; Percent! | NoTitle!| NoFrame!; "")

DIALOGADDTEXT(1000; -1; 10; 15; 75; 15; Left!; "Convert " + vNmbr + " inch to:")

DIALOGADDCHECKBOX(1000; 101; 15; 30; 100; 13; "Centimeters"; vCB1)

DIALOGADDCHECKBOX(1000; 102; 15; 45; 100; 13; "Millimeters"; vCB2)

DIALOGADDCHECKBOX(1000; 103; 15; 60; 100; 13; "Points"; vCB3)

DIALOGADDCHECKBOX(1000; 104; 15; 75; 100; 13; "WP Units"; vCB4)

DIALOGADDTEXT(1000; -2; 10; 100; 100; 15; Left!; "(Press Alt+F4 to cancel)")

DIALOGSHOW(1000; -1; Msg)

WHILE(vStatus = 4)

ENDWHILE

DIALOGDESTROY(1000)

LABEL(Msg)

IF(Msg[5] = 274)

BEEP

vStatus := 2

ENDIF

DEFAULTUNITS(Inches!)

SWITCH(Msg[3])

CASEOF 101: vResult := UNITSTR(vNmbr; Centimeters!)

Message

CASEOF 102: vResult := UNITSTR(vNmbr; Millimeters!)

Message

CASEOF 103: vResult := UNITSTR(vNmbr; Points!)

Message

CASEOF 104: vResult := UNITSTR(vNmbr; WPUnits!)

Message

ENDSWITCH

RETURN

LABEL(Message)

DIALOGUNDISPLAY(1000; "CancelBttn")

MESSAGEBOX(vStatus; "UNITSTR COMMAND"; vNmbr + " inch is converted to " + vResult; IconInformation! | RetryCancel!)

IF(vStatus = 4)

DIALOGSHOW(1000; -1; Msg)

ELSE

BEEP

ENDIF

RETURN


example 8042
// There are two macros in this example

// Compile separately: name the first MACROLIB.WCM

// A Warning Error displayed when macros compiled for the first time

//For each warning, choose Continue Compilation.

// Demonstrate USE command

APPLICATION(A1; "WordPerfect"; Default; "US")

FUNCTION GetMsgBoxResult(x)

VARERRCHK(Off!)

BEEP

SWITCH(x)

CASEOF 1:MESSAGEBOX(vChoice; "Macro File Library"; "Choose a button to dismiss the message box"; IconStop! | AbortRetryIgnore!)

CASEOF 2:MESSAGEBOX(vChoice; "Macro File Library"; "Choose a button to dismiss the message box"; IconStop! | Ok!)

CASEOF 3:MESSAGEBOX(vChoice; "Macro File Library"; "Choose a button to dismiss the message box"; IconStop! | OkCancel!)

CASEOF 4:MESSAGEBOX(vChoice; "Macro File Library"; "Choose a button to dismiss the message box"; IconStop! | RetryCancel!)

CASEOF 5:MESSAGEBOX(vChoice; "Macro File Library"; "Choose a button to dismiss the message box"; IconStop! | YesNo!)

CASEOF 6:MESSAGEBOX(vChoice; "Macro File Library"; "Choose a button to dismiss the message box"; IconStop! | YesNoCancel!)

ENDSWITCH

RETURN(vChoice)

ENDFUNC

PROCEDURE DisplayMsgBoxResult(x)

MESSAGEBOX(x; "Macro File Library"; "You chose the """ + x + """ button"; IconInformation!)

ENDPROC

APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate USE command

VARERRCHK(Off!)

// replace default macros directory if necessary

USE("c:\prwin\macros\macrolib.wcm")

REPEAT

MENU(vResult; Digit; ; ; {"AbortRetryIgnore!"; "OK!"; "OKCancel!"; "RetryCancel!"; "YesNo!"; "YesNoCancel"; "Quit"})

SWITCH(GetMsgBoxResult(vResult))

CASEOF 1: vStatus = "OK"

CASEOF 2: vStatus = "Cancel"

CASEOF 3: vStatus = "Abort"

CASEOF 4: vStatus = "Retry"

CASEOF 5: vStatus = "Ignore"

CASEOF 6: vStatus = "Yes"

CASEOF 7: vStatus = "No"

ENDSWITCH

IF(NOT(vResult = 7))

DisplayMsgBoxResult(vStatus)

ENDIF

UNTIL(vResult = 7)


example 8043
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate DIALOGADDCHECKBOX, DIALOGADDCOLORWHEEL, DIALOGADDCOMBOBOX, and DIALOGADDCOUNTER

CALL(DlgCreate)

REPEAT

MENU(vResult; Digit; ; ; {"Check box"; "Color wheel"; "Combination box"; "Counter"; "Quit"})

DisplayControls

UNTIL(vResult = 5)

CALL(QuitMacro)

LABEL(DisplayControls)

x := 0

SWITCH(vResult)

CASEOF 1: DIALOGSHOW(1000; 100; Msg)

WHILE(x = 0)

ENDWHILE

CASEOF 2: DIALOGSHOW(1001; 1)

vRed := vCW % 256

vGreen := vCW / 256 % 256

vBlue := vCW / 256 / 256

DisplayColorValues(vRed; vGreen; vBlue)

CASEOF 3: DIALOGSHOW(1002; 100)

CASEOF 4: DIALOGSHOW(1003; 100)

ENDSWITCH

RETURN

LABEL(Msg)

IF(Msg[5] = 274)

DIALOGUNDISPLAY(1000; "CancelBttn")

x := 1

ENDIF

SWITCH(Msg[3])

CASEOF 100:

DIALOGUNDISPLAY(1000; "CancelBttn")

MESSAGEBOX(x; "SEE WHAT YOU CAN DO"; "This check box is used with a callback function.  See DIALOGSHOW for details."; IconInformation!)

ENDSWITCH

RETURN

PROCEDURE DisplayColorValues(r; g; b)

MESSAGEBOX(x; "COLOR VALUES"; "The red component equals " + r + ". The green component equals " + g + ". The blue component equals " + b + "."; IconInformation!)

ENDPROC

LABEL(DlgCreate)

DIALOGDEFINE (1000; 50; 50; 120; 50; Percent! | NoFrame!; "DIALOGADDCHECKBOX")

DIALOGADDCHECKBOX(1000; 100; 10; 10; 100; 15; "Click check box"; vCB)

DIALOGDEFINE (1001; 50; 50; 125; 130; Percent! | NoFrame! | OK!; "DIALOGADDCOLORWHEEL")

DIALOGADDCOLORWHEEL(1001; 101; 10; 10; 105; 80; vCW)

DIALOGDEFINE (1002; 50; 50; 125; 115; Percent! | NoFrame!; "DIALOGADDCOMBOBOX")

DIALOGADDCOMBOBOX(1002; 100; 10; 10; 100; 50; DropDown!; var)

DIALOGADDLISTITEM(1002; 100; "DropDown! combo box")

DIALOGADDCOMBOBOX(1002; 101; 10; 40; 100; 50; Simple!; var)

DIALOGADDLISTITEM(1002; 101; "Simple! combo box")

DIALOGDEFINE (1003; 50; 50; 120; 50; Percent! | NoFrame!; "DIALOGADDCOUNTER")

var := 5

DIALOGADDCOUNTER(1003; 100; 10; 10; 50; 15; 0; var; 1; 10; 1)

RETURN

LABEL(QuitMacro)

FORNEXT(x; 1000; 4; 1)

DIALOGDESTROY(x)

ENDFOR

QUIT


example 8038
APPLICATION(A1; "WordPerfect"; Default; "US")

// Extract string of numbers and convert to measurement equivalent

// Demonstrate STRUNIT command

Retry := 4

LABEL(Start)

vNumbers := ""

GETSTRING(vStr; "Enter text that includes both letters and numbers:"; "EXTRACT NUMBERS")

IF(vStr = "")

BEEP

MESSAGEBOX(x; "ERROR"; "You pressed return without entering any text"; IconStop!)

GO(Start)

ENDIF

vLen := STRLEN(vStr)

vPos := 1

REPEAT

vTest := SUBSTR(vStr; vPos; 1)

IF((CTON(vTest) > 47) AND (CTON(vTest) < 58))

vNumbers := vNumbers + vTest

ENDIF

vPos := vPos + 1

UNTIL(vPos = vLen + 1)

IF(STRLEN(vNumbers) > 0)

CALL(DefaultUnit)

vConvert := STRUNIT(vNumbers)

vConvert := vConvert * 5

MESSAGEBOX(x; "STRUNIT COMMAND"; vNumbers + " * 5 equals " + vConvert; IconInformation! | RetryCancel!)

IF(x = Retry)

GO(Start)

ENDIF

ELSE

BEEP

MESSAGEBOX(x; "ERROR"; "You didn't enter any numbers"; IconExclamation!)

ENDIF

QUIT

LABEL(DefaultUnit)

MENU(vChoice; Digit; ; ; {"Inches"; "Centimeters"; "Millimeters"; "Points"; "WP Units"})

SWITCH(vChoice)

CASEOF 1: DEFAULTUNITS(Inches!)

CASEOF 2: DEFAULTUNITS(Centimeters!)

CASEOF 3: DEFAULTUNITS(Millimeters!)

CASEOF 4: DEFAULTUNITS(Points!)

CASEOF 5: DEFAULTUNITS(WPUnits!)

ENDSWITCH

RETURN


example 8037
APPLICATION(A1; "WordPerfect"; Default; "US")

// Extract string of numbers and convert to numeric equivalent

// Demonstrate STRNUM command

vNumbers := ""

vPrompt := "Enter text that includes both letters and numbers:"

LABEL(Start)

GETSTRING(vStr; vPrompt; "EXTRACT NUMBERS")

IF(vStr = "")

BEEP

MESSAGEBOX(x; "ERROR"; "You pressed return without entering any text"; IconStop!)

GO(Start)

ENDIF

vLen := STRLEN(vStr)

vPos := 1

REPEAT

vTest := SUBSTR(vStr; vPos; 1)

IF((CTON(vTest) > 47) AND (CTON(vTest) < 58))

vNumbers := vNumbers + vTest

ENDIF

vPos := vPos + 1

UNTIL(vPos = vLen + 1)

IF(STRLEN(vNumbers) > 0)

vConvert := STRNUM(vNumbers)

vConvert := vConvert * 5

MESSAGEBOX(x; "STRNUM COMMAND"; vNumbers + " * 5 equals " + vConvert; IconInformation!)

ELSE

BEEP

MESSAGEBOX(x; "ERROR"; "You didn't enter any numbers"; IconExclamation!)

ENDIF


example 8033
// There are two macros in this example

// Compile separately

APPLICATION(A1; "WordPerfect"; Default; "US")

// Name of macro: Persist.wcm

// Demonstrate PERSIST command

// vNmbr is a Persist variable

MESSAGEBOX(x; "PERSISTALL EXAMPLE"; "The value of variable vNmbr is " + vNmbr; IconInformation!)

ASSIGN(vNmbr; 999)

RETURN

APPLICATION(A1; "WordPerfect"; Default; "US")

// Run PERSIST.WCM macro

// Demonstrate PERSISTALL command

LOCAL vStatus; vCancel

vStatus := 4

vCancel := 2

PERSISTALL // vNmbr Persist variable

REPEAT

IF(EXISTS(vNmbr))

DISCARD vNmbr

ENDIF

GETNUMBER(vNmbr; "Enter a number:"; "PERSISTALL EXAMPLE")

vMacrosPath := EnvPaths(Macros!)

RUN(vMacrosPath + "persist.wcm")

MESSAGEBOX(vStatus; "PERSISTALL EXAMPLE"; "After running PERSIST.WCM, the value of variable vNmbr is " + vNmbr; IconInformation! | RetryCancel!)

UNTIL(vStatus = vCancel)


example 8034
APPLICATION(A1; "WordPerfect"; Default; "US")

// Saves text to file

// Demonstrate SENDKEYS WAIT command

InhibitInput(Off!)

AddTextBox(1000w;9000w;12000w;8000w;)

Type("Save this message as ""test.doc"" in the default Save Directory (see PrefLocationOfFiles).")

WAIT(10)

SENDKEYS WAIT("{Alt+F}{S}test.doc{Enter}")


example 8035
APPLICATION(A1; "WordPerfect"; Default; "US")

// Demonstrate SPEED command

ONCANCEL(QuitMacro)

AddTextBox(1000w;9000w;12000w;8000w;)

Type("Press Ctrl+Shift+F10 to Cancel")

FOR(x; 1; x < 51; x + 1)

Type(x + NTOC(32))

SPEED(x/10)

IF(((x MOD 10) = 0) AND (x < 50))

Slower

ENDIF

ENDFOR

QuitMacro

LABEL(Slower)

BEEP

Type("Slower ... ")

RETURN

LABEL(QuitMacro)

MESSAGEBOX(x; "SPEED EXAMPLE"; "Counting to 50, SPEED increased the delay between counts."; IconInformation!)

QUIT


example 8036
APPLICATION(A1; "WordPerfect"; Default; "US")

// Test user input for Y or N

// For Cancel condition: chose Cancel, click Close, press Alt+F4, or double-click system menu box

// Demonstrate STRLEN command

CANCEL(On!)

ONCANCEL CALL(CancelMessage)

PROCEDURE Message(vPrompt; vIcon)

IF(vIcon = "!")

BEEP

MESSAGEBOX(y; "Message Box"; vPrompt; IconExclamation!)

ELSE

MESSAGEBOX(y; "Message Box"; vPrompt; IconInformation!)

ENDIF

ENDPROC

vStr := ""

REPEAT

GETSTRING(vStr; "Press one character: ""Y"" for Yes or ""N"" for no"; "GETSTRING - STRLEN EXAMPLE"; 50)

IF(vStr = "")

vStr := "<Enter>"

ENDIF

vTest := TOUPPER(vStr)

IF(STRLEN(vStr) > 1)

CALL Message("You typed or pressed """ + vStr + """"; "!")

ELSE

IF((vTest = "Y") OR (vTest = "N"))

CALL Message("Well done - You pressed " + vTest; "i")

ELSE

CALL Message("You pressed """ + vStr + """"; "!")

ENDIF

ENDIF

UNTIL(((vTest = "Y") OR (vTest = "N")) AND NOT(STRLEN(vStr) > 1))

QUIT

LABEL(CancelMessage)

vStr := "a Cancel control"

RETURN


example 8070
APPLICATION(WP; "WordPerfect"; Default; "US")

// Demonstrate REGIONMOVEWINDOW command

Loop = 1

WM_SYSCOMMAND = 274

DIALOGDEFINE(1000; 20; 40; 135; 75; NoFrame!; "RegionMoveWindow")

DIALOGADDCHECKBOX(1000; 101; 10; 10; 75; 15; "Click to start demo"; var)

DIALOGSHOW(1000; 101; Msg)

WHILE(Loop = 1)

ENDWHILE

DIALOGDESTROY(1000)

QUIT

LABEL(Msg)

IF(Msg[5] = WM_SYSCOMMAND)

Loop = 0

ENDIF

IF(Msg[3] = 101)

REGIONSHOWWINDOW("1000.101"; Hide!)

FORNEXT(x; 50; 190; 10)

REGIONMOVEWINDOW("1000"; 20; x; 135; 75)

WAIT(.5)

ENDFOR

FORNEXT(x; 50; 190; 10)

REGIONMOVEWINDOW("1000"; x; 190; 135; 75)

WAIT(.5)

ENDFOR

FORNEXT(x; 190; 40; -10)

REGIONMOVEWINDOW("1000"; 200; x; 135; 75)

WAIT(.5)

ENDFOR

FORNEXT(x; 190; 40; -10)

REGIONMOVEWINDOW("1000"; x; 40; 135; 75)

WAIT(.5)

ENDFOR

WAIT(.5)

REGIONMOVEWINDOW("1000"; 20; 40; 300; 225)

DIALOGADDTEXT(1000; 102; 0; 15; 300; 15; Center!; "Finished")

FORNEXT(x; 20; 100; 5)

REGIONMOVEWINDOW("1000.102"; 0; x; 300; 15)

WAIT(.9)

ENDFOR

ENDIF

RETURN


Click the Help Topics button to return to the list of topics.


Macro Basics

The following topics discuss the main statements used to write a macro: assignments, conditions, loops, comments, and commands.

Brief Descriptions

Macro Language Concepts

Detailed Information and Examples

Variables, Constants, Operators, and Expressions

Macro Control Statements

Extra Helps

Macro Conventions and Hints


Macro Language Concepts

This section introduces macro concepts.  Begin here if you are new to macro writing, or skip to the command index sections if you are an experienced macro writer.  The topics below are presented in detail in Variables, Constants, Operators, and Expressions, and in Macro Control Statements.

A command-based macro language consists of commands that, when compiled, perform tasks.  For example, the AboutDlg command (WordPerfect) displays the About WordPerfect* dialog box.  You can combine commands in macros to automate routine tasks and simplify large ones.  The following topics introduce macros:

Macros

Assignment Statements

Variables

System Variables

Conditional Statements

Loop Statements

Comment Statements

Command Statements

Command Names

Parameters

Product Commands

Programming Commands

Syntax

Subroutines

Compilers


Macros

Automate application tasks.  WordPerfect* macros automate tasks such as setting margins, selecting a font, or creating a merge file.  Presentations* macros automate tasks such as setting the page size, selecting a drawing tool, or creating a new slide show file.

Macros tasks consist of instructions called statements.  Statements can be assignments, conditions, loops, comments, or commands.  For example,

MarginLeft (1.0")

MarginRight (1.0")

are 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.


Assignment Statements

Assign the value of an expression to a variable.

Examples

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.  You can also assign values to variables using the Assign programming command.


Variables

Represent data that can change during macro play.  Data may include any type of expression, but only one expression at a time.  Variable names are user defined, are not case sensitive, must begin with a letter, can include any other combination of letters or numbers, and are limited to 50 characters.  For example, in WordPerfect*, if you assign 1.0" to variable vMargin, the following commands set one-inch top and bottom margins:

MarginTop (vMargin)

MarginBottom (vMargin)

In Presentations, if you assign the number 50 to variable vPixel, the following command sets Air Brush density to 50 pixels:

SetAirbrushDensity (AirbrushDensity: vPixel)

The lowercase v in vMargin, vTo, vSubject, and vPixel is an optional convention to identify variables.  For more information, see Variables in Variables, Constants, Operators, and Expressions.


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 Presentations*, system variables begin with Env (they return information about the application environment).  For example,

vMacroPath := ?PathMacros

assigns the path and name of the default WordPerfect macros directory to a variable named vMacroPath.  If you change the directory, the system variable ?PathMacros is updated to reflect the change.  The equivalent macro command in Presentations is EnvPaths(Macros!).


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.  For more information, see Using Conditional Statements.


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.  For more information, see Using Loop Statements.


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 they help if someone else has to understand your macro.  A comment begins with // and ends with a hard return [HRt].  See //.


Command Statements

Consist of a name, and optionally one or more parameters.  Commands represent instructions to the parent application.


Command Names

Often describe an action, such as Font, MarginLeft, Advance, and FootnoteOptions in WordPerfect*; or AlignObjectsLeft, BitmapBlur, SelectAllObjects, and ToolbarCopy in Presentations*.  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 (see Using Subroutines).

A macro can use more than one application.  Commands to the non-default application require a product prefix, which is specified in an Application statement.  In this example,

A1.AboutDlg ()

A1 (followed by a period) is the product prefix.  It tells the compiler to use the application assigned A1 in an Application statement.  See Compilers and Application.


Parameters

Contain a constant value (data) that is passed to the compiler or passed between subroutines.  In this Presentations* example,

AddSlide (Count: 3; TemplateName: "Title")

AddSlide is the command name, and 3 and "Title" are parameter data.  This command adds three slides with the Title template to the current slide show.  Parameter names, such as Count and TemplateName, are optional.

A parameter set begins with an open parenthesis and ends with a closed parenthesis.  Multiple parameters are separated with a semicolon.  Some commands have no parameters, and others have many.  Parentheses are optional for commands with no parameters but must be used with  user-defined functions and procedures (see Using Subroutines).

Repeating parameters begin with an open brace ({), end with a closed brace (}), and are separated with a semicolon.  For example, Menu may list up to 26 items.  The following example lists only three:

Menu (vChoice; Digit; 10; 10; {"Item 1"; "Item 2"; "Item 3})


Product Commands

Perform product tasks in a specific application.  For example,

ShowSlide(Slide: 4)

displays the fourth slide in the current slide show in Presentations*.


Programming Commands

Direct the play of a macro and are not specific to an application.  For example,

If (x = "A")

ColorAttributesDlg

Else

LineAttributesDlg

Endif

displays the Color Attributes dialog box if x equals the value "A", or displays the Line Attributes dialog box if x has any other value.  If, Else, and Endif are programming commands.  ColorAttributesDlg and LineAttributesDlg are product commands.

Product and programming commands are not case sensitive.


Syntax

Refers to rules that govern the form of macro statements and expressions.  For example,

Type(Text: "John Doe")

types John Doe.  The next example,

Type(Text: "John Doe"

lacks a closing parenthesis.  The syntax is not correct and produces an error message.  See Macro Errors for common syntax errors.


Subroutines

Consist of a statement or group of statements (statement block) that are played when the subroutine is called (see Using Calling Statements).  Subroutines include functions, procedures, and labels.

Example

Call (SubExample)

...(other statements)...

Label (SubExample)

...statement block...

Return

Explanation: 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 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.  See Using Calling Statements and Using Subroutines.


Compilers

Create object files, which are copies of source files translated into machine language.  Computers can play only object files.

A computer's central processing unit (CPU) plays instructions written in machine (computer) language.  Machine language consists of binary digits (bits) 0 and 1.  For example, the first three letters of the alphabet in binary notation are 1000001, 1000010, and 1000011.  The binary result of 4 + 5 is 1001.  Because binary digits are hard to work with, English-based programming languages (such as Basic, Pascal, and C) were created.  Programs are written with the help of an editor or word-processor and saved as source files.

Macro languages are similar to programming languages.  Macros are written with an editor or word-processor and saved as source files.  When PerfectScript compiles a source file, however, it does not create a separate object file.  Instead, it saves the object in the source file header where you cannot see it.  When you edit a source file, you must recompile it to update the object.  Presentations* can play only a source file with an up-to-date object.  A compiled source file, or macro, contains instructions PerfectScript interprets and sends to the appropriate application when you play the macro.


Variables, Constants, Operators, and Expressions

Variables and constants are joined by operators to form expressions.  Expressions often compute values that determine how control statements direct macro play (see Macro Control Statements).

Variables

Constants

Operators

Expressions


Variables

Point to a memory cell where data is stored.  The variable name represents the data's address or location.  An address can store only one data item at a time, which can be of any type and can change during macro play.  Use the programming commands Declare, Local, Global, or Persist to declare variables.

Adjacent memory cells, associated by a name, are called an array.  Use Declare, Local, Global, or Persist programming commands to declare an array name and the number of cells, or elements, associated with it.  Assign a value to an array element in the same way you assign a value to a variable.  For example,

Declare Test[10]

Assign (Test[1]; 5)

creates a 10-element array named Test, and assigns 5 to element 1.  Array elements can contain different data types, such as numbers or character strings.  See Declare for array examples.

A run-time error occurs if you reference a variable or array element that has not been assigned a value.

Variable and array names are user defined, are not case sensitive, must begin with a letter, can include any combination of letters or numbers, and are limited to 50 characters.  The following examples assign a right operand expression to a left operand variable (variable can also be an array element).

Examples

x := "John Doe"

Result: x equals John Doe (character string)

vLeftMargin := 5i

Result: vLeftMargin equals 5i (measurement expression)

ResultOfOperation := 3 + 4

Result: ResultOfOperation equals 7 (numeric expression)

z := z + 1

Result: z equals the value of z + 1 (Because a variable can contain only one value at a time, the original value of z is lost unless previously assigned to another variable.)

x := y > 1

Result: x equals the result of relational expression y > 1 (x equals True if y contains a value greater than 1, or False if y contains a value less than or equal to 1.  True and False are Boolean data that represent numeric constants 1 and 0.)

The following example evaluates the result of y > 1, without assigning the result to a variable.  The computer beeps if the value of y is greater than 1 (if the result of expression y > 1 equals True).  Beep is skipped if the value of y is less than or equal to 1 (if the expression result equals False).

If (y > 1)

Beep

Endif

Variable Programming Commands

Declare

Global

Indirect

Local

Persist

Special Variables

MacroDialogResult

ErrorNumber

MacroArgs[]


Indirect

Creates a variable name out of a combination of character strings and/or numbers.  See the programming command Indirect.  You can use Indirect wherever you can use a variable.

Indirect can also create a Label name out of a combination of character strings and/or numbers, and can be used in most places where you can use a label.  See Using Subroutines.


Local

Creates local variables and arrays (they only pertain to the current macro).  Variables declared in user-defined functions and procedures are local to those subroutines.  When you create a variable by assigning it a value, the variable is automatically declared Local (see the programming command Local).


Global

Creates variables and arrays that pertain to the current macro and to macros called by Run or Chain (see the following programming commands: Chain, Global, and Run).


Persist

Creates variables and arrays that pertain to any PerfectScript macro as long as PerfectScript is running (see the following programming commands: Persist and PersistAll).


Declare

Creates local variables and arrays (they only pertain to the current macro).  An array can have up to 10 dimensions, and up to 32,767 elements per dimension depending on the amount of available memory (see programming commands Declare and Local).


MacroDialogResult

An implicit variable (one defined by the application) that contains the Control value of the button that dismisses a dialog box.  See Creating a Dialog Box with Macro Commands and DialogDefine.


MacroArgs

A special array variable that contains values passed to it by Chain, Nest, or Run.  For example,

// Macro: MAIN.WCM

// Include full path if macro not

// in default macros directory

Run("TSTMACRO"; {"x"; "y"; "z"})

// Macro: TSTMACRO.WCM

// Compile, then play MAIN.WCM

vElements = Dimensions (MacroArgs[]; 0)

If (vElements != 0)

ForNext (x; 1; vElements; 1)

MessageBox (z; "Element Values"; "MacroArgs[" + x + "] = " + MacroArgs[x])

EndFor

Else

Beep

MessageBox (z; "Error"; "No values passed"; IconExclamation!)

EndIf

// Result: x y z


ErrorNumber

A system variable that contains the error value of a Cancel, Error, or Not Found condition.  See Assert and the ASSERT.WCM example (line 44).


Constants

Represent data items that cannot change during macro play.  For example,

Switch (x)

CaseOf 1: CALL (Start

CaseOf 2: CALL (Stop)

EndSwitch

contains two CASEOF statements, followed by numeric constants 1 and 2.  If variable x equals 1, a subroutine named Start is called.  If x equals 2, a subroutine named Stop is called.  See Using Conditional Statements and Switch.


Operators

Macros support the following operators:

Unary Operators

Binary Operators

Arithmetic Operators

Relational Operators

Logical Operators

Bitwise Operators


Unary Operators

Symbols or words that represent an operation on only one operand or expression.

Operator (explanation)

+ (multiplies an operand by +1)

- (multiplies an operand by -1)

NOT (inverts the result of relational and logical expressions)

Examples

Unary plus/minus (+/-) examples

NOT example

NOT example in an IF statement

NOT example in shorthand notation


Unary plus/minus (+/-) examples

+5

Result: +5 is the result of 5 * +1

-10

Result: 10 is the result of 10 * -1


NOT example

x := 5

y := (x < 10)

z := NOT(x < 10)

Explanation: True is assigned to y (x is less than 10).  False is assigned to z (inverted result of expression x < 10).


NOT example in an If statement

x := 5

z := (x < 10)

If (NOT(z))

Beep

Else

Quit

EndIf

Explanation: The result of expression x < 10 is assigned to variable z.  Beep causes the computer to beep if the inverted value of z equals True.  Because the inverted value of z equals False, there is no beep, and the Else statement is played. Quit ends the macro.


NOT example in shorthand notation

x := 5

If (NOT(x < 10))

Beep

Else

Quit

EndIf

Explanation: If instructs the computer to beep if the inverted result of expression x < 10 equals True.  Because the result of NOT(x < 10) equals False, there is no beep and the Else statement is played.  Quit ends the macro.

Previous example without NOT operator

x := 5

If (x > 10)

Beep

Else

Quit

EndIf

Explanation: If the result of expression x > 10 equals True, beep.  Because the result equals False (the value of x is less than 10), the Else statement is played.  Quit ends the macro.


Binary Operators

Symbols that represent an operation on two operands or expressions.  For example,

x := 3 + 4

contains a plus operator (+) which adds the operands 3 and 4.  The assignment operator (:=) assigns the result of the arithmetic expression 3 + 4 to variable x.

The binary operators are:

Arithmetic Operators

Relational Operators

Logical Operators

Bitwise Operators


Arithmetic Operators

Symbols or words that represent a mathematical operation on two operands.

Operator (action)

* (multiplication)

/ (division)

- (subtraction of numbers and reduction of strings)

+ (addition of numbers and concatenation of strings)

% (floating point modulus division returns floating point division remainder)

MOD (integer modulus division returns integer division remainder)

DIV (integer division returns integer portion of integer division)

** (exponentiation or raising a number to a power)

Examples

+/- (string) examples

** examples

% examples

MOD examples

DIV examples


Floating point (%) examples
% examples

x:=10.1 % 3

Result: x equals 1.1

x := 9 % 3

Result: x equals 0


MOD examples

x := 10 MOD 3

Result: x equals 1

x := 10.1 MOD 3

Result: error (cannot use MOD on real numbers)


DIV examples

x := 10 DIV 3

Result: x equals 3

x := 9 DIV 3

Result: x = 3

x := 9.1 DIV 3.5

Result: error (cannot use DIV on real numbers)


Relational Operators

Symbols that represent a relational operation on two operands.  The operation result equals True or False.

Operator (action)

> (greater than)

>= (greater than or equal to)

< (less than)

<= (less than or equal to

= (equal to)

<> (not equal to)

!= (not equal to)

IN (membership)

Examples

Greater than (>) and less than (<) examples

Not equal (<> or !=) example

Greater than or equal to (>=) example

Less than or equal to (<=) example

IN example


Greater than (>) and less than (<) examples

x := 10

z := (x > 5)

Result: z equals True (x is greater than 5).

z := (x < 5)

Result: z equals False (x is not less than 5).


Not equal (<> or !=) example

x := 10

z := (x <> 5)

Result: z equals True (x is not equal to 5)

x := 12

z := (x != 12)

Result: z equals False (x is equal to 12)


Greater than or equal to (>=) example

x := 10

If (x >= 10)

Beep

Else

Quit

EndIf

Explanation: The computer beeps because the result of expression x >= 10 equals True (x equals 10).  The Else statement is skipped.  Quit does not end the macro.


Less than or equal to (<=) example

x := 20

If (x <= 10)

Beep

Else

Quit

EndIf

Explanation: The computer does not beep because the result of expression x <= 10 equals False (x is greater than 10).  The Else statement is played.  Quit ends the macro.


Logical Operators

Words that represent a logical relationship between conditions, or that invert a condition.  The condition is the result of a relational expression.  The operators are listed in order of precedence.

Operator and Action

NOT  A unary operator that inverts the result of a relational expression.

AND  Combines two relational expressions.  Each expression must be true for the logical expression to be true.

XOR  Combines two relational expressions.  Only one expression can be true for the logical expression to be true.  If both are true or both are false, the logical expression is false.  The XOR operator is also named exclusive OR.

OR  Combines two relational expressions.   Only one expression need be true for the logical expression to be true.  The OR operator is also named inclusive OR.

Examples

NOT example

AND example

XOR example

XOR example in shorthand notation

OR example


NOT example

x := 8

If ((x < 10) AND NOT (x = 5))

Beep

EndIf

Explanation: The result of the logical expression equals True (x is less than 10 AND NOT x is equal to 5, or x is not equal to 5).


AND example

x := 1

y := 2

z := ((x = 1) AND (y = 2))

Result: z equals True (the logical AND expression is true because the relational expressions x = 1 and y = 2 are true).


XOR example

x := 1

y := 2

z := ((x = 0) XOR (y = 2))

Result: z equals True (only one relational expression is true).

z := ((x  = 1) XOR (y = 2))

Result: z equals False (both relational expressions are true).

z := ((x = 0) XOR (y = 1))

Result: z equals False (both relational expressions are false).


XOR example in shorthand notation

x := 1

y := 2

If ((x = 0) XOR (y = 2))

Beep

EndIf

Explanation: The result of the logical XOR expression equals True because relational expression x = 0 is false and relational expression y = 2 is true.


OR example

x := 1

y := 2

z := ((x = 1) OR (y = 5))

Result: z equals True (the logical OR expression is true because relational expression x = 1 is true).


Bitwise Operators

Symbols that represent a bitwise operation on two integer operands.  The operators are listed in order of precedence.

Operator and Action

~  Bitwise unary NOT [complement of 1] toggles a binary value [1 to 0, and 0 to 1].

&  Bitwise AND results in 1 if both operand bits are 1, and results in 0 if both operand bits are not 1.

|  Bitwise inclusive OR results in 1 if both operands are 1 or operands do not match.  Results in 0 if both operands are 0.

^  Bitwise exclusive OR (XOR) results in 0 if operands match, and 1 if operands do not match.

<<  Shift bits left.

>>  Shift bits right.

>>> Rotate bits left

<<< Rotate bits right

Examples

Unary NOT (~) example

AND (&) example

Inclusive OR (|) example

Exclusive OR (^) example

Shift left (<<) example

Shift right (>>) example

Rotate left (<<<) example

Rotate right (>>>) example


Unary NOT (~) example

Decimal (binary)

~-15 (1111111111110001)

Result: 14 (0000000000001110)

Explanation: Bitwise unary NOT toggles bits from 1 to 0 and from 0 to 1.


AND (&) example

Decimal (binary)

1000 (1111101000)

&31 (0000011111)

Result: 8 (0000001000)

Explanation: Bitwise AND turns off bits (result is 0) if one operand is 0.  Bits are left on (result is 1) if both operands are 1.


Inclusive OR (|) example

Decimal (binary)

1000 (1111101000)

|27 (0000011011)

Result: 1019 (1111111011)

Explanation: Bitwise OR turns on bits (result is 1) if one operand is 1.  Bits are left off (result is 0) if both operands are 0.


Exclusive OR (^) example

Decimal (binary)

1 (0001111101000)

^40 (0000101000)

Result: 960 (1111000000)

Explanation: Bitwise XOR turns on bits (result is 1) if the operands are different.  It turns off bits (result is 0) if the operands are the same.


Shift left (<<) example

Decimal (binary)

500 (0111110100)

<<1 (0000000001)

Result: 1000 (1111101000)

Explanation: Shifts bits one position left, and inserts one 0 bit at the right end of the binary numeral.  Multiplies the original value by 2.


Shift right (>>) example

Decimal (binary)

1000 (1111101000)

>>1 (0000000001)

Result: 500 (0111110100)

Explanation: Shifts bits one position right, and inserts one 0 bit at the left end of the binary numeral.  Divides the original value by 2.


Operator Precedence

The following table shows operator precedence, which is applied to expressions.

Precedence [operators]

1 [parentheses (), unary minus (-), unary plus (+), bitwise not (~), logical not (NOT)]

2 [** exponentiation]

3 [multiply (*), divide (/), modulus division (% or MOD), integer division (DIV)]

4 [add (+), subtract (-)]

5 [shift left (<<), shift right (>>), rotate left (<<<), rotate right (>>>)]

6 [equal (=), not equal (<> or !=), less than (<), less than or equal to (<=), greater than (>), greater than or equal to (>=), membership (IN)]

7 [bitwise and (&), bitwise or (|), bitwise xor (^)]

8 [logical and (AND)]

9 [logical or (OR), logical xor (XOR)]

10 [assignment (:= or =)]

Operator Rules

Operators with the same precedence are evaluated from left to right.

Operators inside parentheses are evaluated before operators outside parentheses.

Operators inside nested parentheses are evaluated from the innermost parentheses out.

Examples

Operator Precedence Examples


Operator Precedence Examples

x := ((50 * 5 + 50) * 3 + 100)

Result: x equals 1000 (50 * 5 = 250, 250 + 50 = 300, 300 * 3 = 900, 900 + 100 = 1000)

x := ((50 * (5 + 50)) * 3 + 100)

Result: x equals 8350 (5 + 50 = 55, 55 * 50 = 2750, 2750 * 3 = 8250, 8250 + 100 = 8350)

x := ((50 * 5 + 50) * (3 + 100))

Result: x equals 30900 (50 * 5 = 250, 250 + 50 = 300, 300 * 103 = 30900)


Expressions

Macros support the following expressions:

Numeric Expressions

Measurement Expressions

Radix Base Conversions

Character Expressions

Arithmetic Expressions

Relational Expressions

Logical Expressions

Bitwise Expressions

Command and function calls can be used in an expression if they return a value.


Numeric Expressions

Numeric constants or variables, or a combination of the two joined by a numeric operator.  A numeric operator is a word or symbol that operates on numeric data (see Unary Operators and Binary Operators).

Given that x equals 3, the following examples are valid numeric expressions.

Examples

5

Explanation: Numeric constant.

x

Explanation: Variable containing a numeric value.

x * 5

Explanation: Expression (multiply x and 5).  The expression x * 5 is also an arithmetic expression.

+5

Explanation: Unary plus constant.

-(x + 10)

Explanation: Unary minus expression (negate the result of x plus 10).


Measurement Expressions

Constants or variables containing a measurement value, or combination of the two joined by a numeric operator.

Given that z equals 4i (inches), the following examples are valid measurement expressions.

Examples

5c

Explanation: Constant (5 centimeters).

z

Explanation: Variable that contains a measurement value of 4 inches.

z * 10i

Explanation: Expression (multiply z and 10 inches).

-z

Explanation: Unary minus (negative 4 inches).

The following list contains valid units of measure.

Unit of Measure (measurement type)

" (inches)

i (inches)

c (centimeters)

m (millimeters)

p (points [72 per inch])

w (WP unit [1200 per inch])

Summary

A measurement expression is a number followed by one of the characters listed above.  The character specifies the unit of measure for the number.

You can add and subtract measurement expressions as you do numeric expressions.  When an operation is performed on measurement expressions that have different units of measure, the left operand measurement is used.

Combining numeric expressions with measurement expressions can produce unexpected results.

You do not need to specify a unit of measure for command measurement expressions that follow DefaultUnits.

If you do not specify a unit of measure for a measurement expression, and DefaultUnits has not been encountered, the default unit of measure is WP units (1200 per inch).


Character Expressions

Character constants (letter, digit, or keyboard symbol) or variables.  A character expression can also be a combination of the two concatenated by the plus operator (+), or a combination of the two separated by the minus operator (-), or compared by a relational operator such as > (greater than).  Character constants and character constants assigned to variables must be enclosed in double quotation marks.

Enclose a character constant in single quotation marks to specify an ASCII numeric value (see CToN).  For example,

x := 'A'

Result: x equals 65.

x := 'A' + 'B'

Result: x equals 131 (65 + 66).

A character string with double quotation marks is enclosed with two sets of double quotation marks.  For example,

x := "His name is ""John"" Doe"

Result: x equals His name is "John" Doe.

x := """John Doe"""

Result: x equals "John Doe" (outside quotation marks are always required).

The following examples are valid character expressions (notice the space after Joe and before Jr.).

"John Doe"

Explanation: Character string.

z := "Joe " + "Doe"

Explanation: Expression assigned to variable z (z equals John Doe).

x := z + ",  Jr."

Explanation: Expression assigned to variable x (x equals John Doe, Jr.).

If you concatenate a character string and a number, the number is converted to a character string.  If you concatenate a numeric character and a number, the numeric character is converted to a number and the two are added.  For example,

x := "A" + 1

Result: x equals A1 (character string).

x := "1" + 1

Result: x equals 2 (number).

x := ("A" + (1 + 3))

Result: x equals A4 (the result of a mathematical operation (1+3=4) converted to a character string before being concatenated to A).

Compare the previous example with the following examples (operation precedence is left to right):

x := ("A" + 1 + 3)

Result: x equals A13 (character string--numbers converted and not added).

x := (1 + 3 + "A")

Result: x equals 4A (character string--numbers added and then converted to a character string).


Arithmetic Expressions

Statements that represent arithmetic operations, or statements that contain two operands joined by an arithmetic operator.  The operation result is a numeric value.

Examples

x := 1 + 2

Result: x equals 3.

x := 3 * 3

Result: x equals 9.

x := "2" * 3 * 4

Result: x equals 24 (2 converted to a number then multiplied).

x := "A" * 2

Result: error (cannot multiply letters and numbers).


Relational Expressions

Statements that represent a relational operation, or statements that contain two operands joined by a relational operator.  The operation result equals True or False.

Examples

Given that x equals 5,

z := (x > 6)

Result: z equals False (5 is less than 6).

z := (x >= 5)

Result: z equals True (5 equals 5).

z := ("Ab" > "Bb")

Result: z equals False (Ab is less than, or comes before, Bb).

z := ("Ab" <> "Bb")

Result: z equals True (Ab is not equal to Bb).

Examples

Given that x equals "A", y equals "B", and z equals "a", the following expressions return True or False in variable w:

w := (x > y)

Result: w equals False (uppercase A is less than, or comes before, uppercase B).

w := (x > z)

Result: w equals True (uppercase A is greater than, or comes after, lowercase a).


Logical Expressions

Statements that represent logical operations, or statements that contain two relational expressions joined by a logical operator.  The operation result equals True or False.

Examples

Given that x equals 10, y equals 5, and z equals 20, the following expressions return True or False in variable w:

w := ((x > y) AND (y < z))

Result: w equals True (both relational expressions are true).

w := ((x < y) AND (y < z))

Result: w equals False (first relational expression is false).

w := NOT(y > z)

Result: w equals True (5 is not greater than 20).

w := ((x > 5) AND (y < 20) AND (z = 20))

Result: w equals True (all relational expressions are true).

w := (((x < 5) AND (y > 20)) OR (z = 20))

Result: w equals True (z = 20 is true).

w := (((x < 5) AND (y > 20)) OR NOT (z = 20))

Result: w equals False (all relational expressions are false).


Bitwise Expressions

Statements that represent bitwise operation, or statements that contain two operands joined by a bitwise operator.  The operation result is a numeric value.

Examples

Bitwise NOT (~) example

Bitwise AND (&) example

Bitwise inclusive OR (|) example

Bitwise XOR (^) example

Bitwise shift left (<<) example

Bitwise shift right (>>) example

Bitwise rotate left (<<<) example

Bitwise rotate right (>>>) example


Bitwise NOT (~) example

x := ~(-15)

Result: x equals 14 (complement of 1).

x := ~(-15) + 1

Result: x equals 15 (complement of 2).


Bitwise AND (&) example

x := 65535 & 535

Result: x equals 535.

Previous example in binary notation

1111111111111111(binary 65535)

&0000001000010111(AND binary 535)

Result: 0000001000010111(result is binary 535)

Explanation: Bitwise AND operation result is 1 if both operands are 1, or 0 if both operands are not 1.


Bitwise inclusive OR (|) example

x := 65535 | 535

Result: x equals 65,535.

Previous example in binary notation

1111111111111111(binary 65535)

|0000001000010111(OR binary 535)

Result: 1111111111111111(result is binary 65535)

Explanation: Bitwise OR operation result is 1 if one operand is 1, or 0 if both operands are 0.


Bitwise XOR (^) example

x := 65535 ^ 535

Result: x equals 65,000.

Previous example in binary notation

1111111111111111(binary 65535)

^0000001000010111(XOR binary 535)

Result: 1111110111101000(result is binary 65,000)

Explanation: Bitwise XOR operation result is 0 if both operands are 0 or 1, or 1 if operands do not match.


Bitwise shift left (<<) example

x := 65535 << 1

Result: x equals 131,070.

Previous example in binary notation

1111111111111111  (binary 65535)

Result: <<1111111111111110  (result is binary 131,070)

Explanation: Bitwise shift left operator shifts bits one position left, and inserts one 0 bit at the right end of the binary numeral.  The result is the original value multiplied by 2.


Bitwise shift right (>>) example

x := 65535 >> 1

Result: x equals 32,767.

Previous example in binary notation

1111111111111111  (binary 65535)

Result: <<0111111111111111  (result is binary 32,767)

Explanation: Bitwise shift right operator shifts bits one position right, and inserts one 0 bit at the left end of the binary numeral.  The result is the original value divided by 2.


Radix Base Conversions

The radix is the base of a number system.  The following list contains the radix choices.

x or h (Hexadecimal radix is 16)

o (Octal radix is 8)

b (Binary radix is 2)

Examples

x := 1Ah

Result: x equals 26

x := 1111b

Result: x equals 15

x := 44o

Result: x equals 36

All radix number values must begin with a number.  Precede non-numeric hex digits with 0.  For example,

x := 0Ah

Result: x equals 10


Macro Control Statements

Control statements alter the sequential play of macro commands.  For example,

SetBrushWidth(BrushWidth: 25)

SetBrushWidth(BrushWidth: 75)

sets a 25-pixel Paint Brush width and then a 75-pixel Paint Brush width.  The second command overrides the first.  A control statement can select which SetBrushWidth to play depending on a condition being true.

Example

Switch (<Test>)

Caseof 1: setbrushwidth(brushwidth: 25)

Caseof 2: setbrushwidth(brushwidth: 75)

Default: setbrushwidth(brushwidth: 50)

Endswitch

Explanation: If variable Test equals 1, set a 25-pixel Paint Brush width.  If Test equals 2, set a 75-pixel Paint Brush width.  If Test equals any value except 1 or 2, set a 50-pixel Paint Brush width.  The value of Test can be determined by a programming command such as Menu or GetNumber.

Macros support conditional control statements, loop control statements, and miscellaneous control statements such as Call, Go, and Quit.

More Information

Using Conditional Statements

Using Loop Statements

Using Calling Statements

Using Subroutines

Macro File Libraries


Using Conditional Statements

Conditional statements execute a statement or statement block when an expression is true, or when a variable matches a constant.

Macros support the following conditional statements:

Case

If

Switch


Case

Executes a Label statement when Test (user-defined variable) matches a constant value.

Case (<Test>; {1; Start; 2; Next}; Other)

...(other statements)...

Label (Start)

...statement block...

Label (Next)

...statement block...

Label (Other)

...statement block...

Explanation: If Test matches 1, call Label(Start).  If Test matches 2, call Label(Next).  If there is no match, call Label(Other).

Case Call is a similar statement which expects a Return after a Label statement.  See the programming commands Case and Case Call.


IFELSEENDIF
If-Else-Endif

Executes a statement or statement block when an expression is true.

If (x = 5)

...statement block...

Else

...statement block...

Endif

Explanation: Execute the first statement block if the expression x = 5 is true (if x equals 5).  If not true, execute the second statement block.  Else is optional.

If (Expression)

...statement block...

Endif

Explanation: If Expression is true, execute statement block.  If not true, execute the first statement after Endif.  Expression must evaluate to true or false.

See Relational Expressions and If.


SWITCHENDSWITCH
Switch-EndSwitch

Executes a statement or statement block when <Test> matches <Selector>.

Switch (<Test>)

Caseof <Selector>:

...statement block...

Caseof <Selector>:

...statement block...

Caseof <Selector>:

...statement block...

Default:

...statement block...

EndSwitch

Explanation: If <Test> matches <Selector>, the statement block after CASEOF <Selector> is executed.

Statement blocks can include calling a subroutine (see Using Subroutines).  If Continue follows a statement block, the next statement block is automatically executed.  See the programming command Switch.


Using Loop Statements

Loop statements execute a statement or statement block a specified number of times, until an expression is true, or while an expression is true.

Macros support the following loop statements:

For

Repeat

While


FORENDFOR
For-EndFor

Executes a statement or statement block a specified number of times.

Examples

For (<ControlVariable>; <InitialValue>; <TerminateExp>; <IncrementExp>)

...statement block...

EndFor

Explanation: <InitialValue> initializes <ControlVariable>.  <TerminateExp> tests the value of <ControlVariable>.  <IncrementExp> increases the value of <ControlVariable> until <TerminateExp> is true and the loop ends.

For (x; 1; x < 5; x + 1)

...statement block...

EndFor

Explanation: x is initialized to 1, statement block executes while x is less than 5, and x is incremented by 1 at the end of each loop.

Similar loop statements are Foreach and Fornext. See Relational Expressions, For, Foreach, and Fornext.


REPEATUNTIL
Repeat-Until

Executes a statement or statement block until an expression is true.  All Repeat statements execute at least once because the expression is checked at the end of the loop.

Examples

Repeat

...statement block...

Until (x >= 10)

Explanation: Execute statement block until the expression x >= 10 is true (until x is greater than or equal to 10).  The value of x must change in the loop to make the expression true or the loop never ends.  For example,

Repeat

...statement block...

x := x + 1

Until (x >= 10)

Explanation: Increment x by 1 (x := x + 1) at the end of each loop until x is greater than or equal to 10.  See Relational Expressions and Repeat.


WHILEENDWHILE
While-EndWhile

Executes a statement or statement block while an expression is true.  While statements never execute unless the expression is true because the expression is checked at the start of the loop.

Examples

While (x <= 10)

...statement block...

EndWhile

Explanation: Execute statement block while the expression x <= 10 is true (while x is less than or equal to 10).  If x is greater than 10, the loop does not execute.  The value of x must change in the loop to make the expression true or the loop never ends.

While (x <= 10)

 ...statement block...

x := x + 1

EndWhile

Explanation: Increment x by 1 (x := x + 1) at the end of each loop while x is less than or equal to 10.

See Relational Expressions and While.


Using Calling Statements

Calling statements call a subroutine which consists of one or more statements (see Using Subroutines).

Macros support the following calling statements:

Call

Go

Subroutine Name


Call

Has one parameter which is the name of a subroutine to call.  Return directs macro execution to the statement that follows Call (see the programming commands Call and Run).

Example

Call (ExSub)

...other statements...

Label (ExSub)

...statement block...

Return

Explanation: Call(ExSub) directs macro execution to Label(ExSub), where statement block is executed.  Return directs macro execution to the first statement after Call(ExSub).


Go

Has one parameter which is the name of a subroutine to jump to.  Macro execution continues from the point of the subroutine and does not return (statements between Go and the subroutine do not execute).  Return ends a macro or directs macro execution to the statement that follows a Run command (see the programming commands Go and Run).

Example

Go (ExSub)

...other statements...

Label (ExSub)

...statement block...

Return

Explanation: Go(ExSub) directs macro execution to Label(ExSub), where statement block is executed.  Return ends the macro.


Subroutine Name

Performs the same action as a Call statement.  For example,

Call InitializeVariables (<Parameter>; <Parameter>)

InitializeVariables (<Parameter>; <Parameter>)

both call a function or procedure named InitializeVariables (see Using Subroutines, Label, Function, Procedure and Return).  If the second example calls a function, you can assign a return value to a variable with a statement such as

x := InitializeVariables (<Parameter>; <Parameter>)


Using Subroutines

Subroutines consist of one or more statements that execute when the subroutine is called by Call, Go, Case, Case Call, or the name of the subroutine.

Macros support the following subroutines:

Labels

Functions

Procedures

Callback Data Description


Labels

Have one parameter which is the name of the subroutine.  Label names must begin with a character, consist of one or more letters or numbers, are limited to 30 characters, and can have an optional trailing @ sign.  Labels generally include one or more statements followed by Return or Quit.  Label statements execute the same as other macro statements and do not have to be called.  See the Label programming command.


Functions

Can have zero or more parameters which receive values from a calling statement (see Using Calling Statements) and return a value.  A function without parameters performs like a Label, except it cannot execute unless called.  Function names must begin with a character, consist of one or more letters or numbers, are limited to 30 characters, and can have an optional trailing @ sign.  The following rules apply to functions:

Functions begin with the word FUNCTION and end with ENDFUNC.

Functions do not execute unless called.

Calling statements consist of a function name, which can be followed by zero or more parameter values that pass to the function.  If there are no parameters, empty parentheses must follow the function name.

The number of parameters in a calling statement must match the number of function parameters.

A function cannot be defined inside another subroutine.

Functions can be placed anywhere in a macro or in a macro library file (see Use).

Functions can be called from a subroutine, or a function can call itself (functions are recursive).

Function variables are private to the function.  A variable with the same name as a function variable can be used elsewhere in the macro without conflict.

Functions can include Label statements which are not visible outside the function. A Label statement inside a function should not have the same name as a function or procedure.

Functions accept Return statements with no parameters (return 0); or a value contained in a variable that is the result of a function; or an enumerated type that asserts a Cancel, Error, or Not Found condition; or an enumerated type that asserts a Cancel, Error, or Not Found condition, and a value contained in a variable that is the result of a function operation. See Return.


Procedures

Can have zero or more parameters which receive a value from a calling statement (see Using Calling Statements).  A procedure cannot return a value.  A procedure without parameters performs like Label, except it cannot execute unless called.  Procedure names must begin with a character, consist of one or more letters or numbers, are limited to 30 characters, and can have an optional trailing @ sign.  The following rules apply to procedures:

Procedures begin with the word PROCEDURE and end with ENDPROC.

Procedures cannot execute unless called.

Calling statements consist of a procedure name, which can be followed by zero or more parameter values that are passed to the procedure.  If there are no parameters, empty parentheses must follow the procedure name.

The number of parameters in a calling statement must match the number of procedure parameters.

A procedure cannot be defined inside another subroutine.

Procedures can be placed anywhere in a macro, or in a macro library file (see Use).

Procedures can be called from a subroutine, or a procedure can call itself (procedures are recursive).

Procedure variables are private to the procedure.  A variable with the same name as a procedure variable can be used elsewhere in the macro without conflict.

Procedures can include Label statements which are not visible outside the procedure.  A Label statement inside a procedure should not have the same name as a procedure or function.

Procedures accept Return statements with no parameters (directs macro execution to the statement that follows a procedure's caller); or with one parameter (an enumerated type that asserts a Cancel, Error, or Not Found condition).  See Return.


Macro File Libraries

Contain functions and/or procedures that can be called from another macro and must be compiled.

Use specifies a macro that contains functions and/or procedures.  Usually precedes calling statements to a macro file library.  The following example contains two functions:

Function Add(x)

x := x + 50

Return (x)

EndFunc

Function Subtract(x)

x:= x - 25

Return (x)

EndFunc

Explanation: Function Add receives a value in variable x (see Using Calling Statements).  50 is added to x and returned to the functions caller.  Function Subtract receives a value in another variable named x.  25 is subtracted from x and returned to the functions caller.  If this example was saved and compiled as LIBRARY.WCM, the next example includes statements that call the Add and Subtract functions:

Application (WP; "WordPerfect"; Default; "US")

Use ("C:\...\LIBRARY.WCM")

z := Add(50)

z := Subtract(z)

If (z = 75)

Beep // computer beeps because z equals 75

EndIf

Explanation: After function Add is called, 100 is returned in variable z.  After function Subtract is called, 75 is returned in variable z.  The computer beeps because the expression z = 75 is true.

The previous example with function calling statements in shorthand notation:

Application (WP; "WordPerfect"; Default; "US")

Use ("C:\...\LIBRARY.WCM")

z := Add(Subtract(50))

If (z = 75)

Beep // computer beeps because z equals 75

EndIf


Conventions and Macro Hints

Conventions

You can enter programming commands in uppercase, lowercase, or mixed case.  The compiler is not case sensitive (see Compilers).

Product commands, such as AboutDlg or AddSlide, are shown in mixed case.

System variables, such as EnvPaths or EnvChartType, are shown in mixed case and usually begin with Env because they return information about the application environment.

Italicized words in a syntax definition are user-defined values.

Hints

Wrapping does not affect macro execution.

Do not insert spaces in a command name unless the space is part of the syntax.

Do not use hard returns, tabs, or indents within a character expression (a character string enclosed in double quotation marks).  See Character Expressions.

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.  To disable smart quotes in WordPerfect* for Windows, choose Tools, QuickCorrect*, Options, deselect Turn on double quotes.

Command syntax must be correct for a macro to compile.  Common errors include missing or incorrectly used commas (,), colons (:), semicolons (;), and double quotation marks (").

A macro is automatically compiled the first time it plays.  You can also compile macros from PerfectScript (see Compilers), or choose Save & Compile on the Macro feature bar (see Writing Macros).

Begin macros with an APPLICATION statement to identify the application used in the macro.  The compiler requires this information.  You can include more than one APPLICATION statement (see Application).

When compiled, macros are saved as WordPerfect files.


Creating Macros

Record a Macro

Play a Macro

Edit a Macro

Writing Macros

Macro Errors

Dialog Boxes


Record a Macro

Recording a macro saves a series of keystrokes and/or mouse actions that you can play (repeat) later.  Recorded macros automate routine tasks, such as setting margins (WordPerfect*) or color attributes (Presentations*), displaying a dialog box for user input, or opening or closing a file.


Play a Macro

After recording, playing a macro accomplishes in one step what may require several steps to achieve during a recording session.


Edit a Macro

If you edit a macro in WordPerfect* for Windows, the Macro feature bar simplifies the task.

You can edit a macro by typing commands, or you can use the Macro feature bar to insert commands.


Writing Macros

A recorded macro includes only product commands.  When you play a recorded macro, each action is played in recorded order (see Record a Macro).

A written macro can also include non-recordable statements that specify how a macro performs a task.  The writer specifies the conditions for playing assignments, loops, and programming commands (see Macro Language Concepts).  Writing a macro provides greater flexibility to determine function than recording a macro.  You can write a macro in WordPerfect* for Windows and play it in the application for which it was written.


Macro Errors

Errors are sometimes created when you edit a macro (see Syntax).  If, for example, you typed Centr (WordPerfect* command) instead of Center, when you choose Save & Compile a compile-time syntax error displays a syntax error message box.

The compiler does not recognize Centr, and guesses that it is a Label's calling statement (see Using Calling Statements and Using Subroutines).  When it reaches the end of the file and does not find a corresponding Label, it displays a Syntax Error message.  Common syntax errors are:

Missing semicolons between parameters

Missing parentheses

Missing double quotation marks (see Character Expressions)

Missing command in a conditional or loop statement (see Using Conditional Statements and Using Loop Statements)

Misspelled macro command names

Undefined calling statements (see Using Calling Statements)

Using commas between parameters instead of semicolons.

The compiler identifies syntax errors and suggests solutions for the writer to verify.

Run-time error messages identify errors that occur while the macro plays and show where errors occur.


Dialog Boxes

Users interact with applications through menus and dialog boxes.  Dialog boxes can display more than one option for user input.  For example, in the WordPerfect* Margins dialog box, default settings are displayed in edit boxes next to buttons.  To display the Margins dialog box, choose Format, Margins (an ellipsis to the right of a menu option indicates a dialog box is available).

To change settings, enter new values in the edit boxes or click a button (see DialogAddPopupButton).  The edit box and button are Windows* controls for user input.  Controls available for a user-defined dialog box are described in the topics listed below.

Dialog Box Controls

Creating a Dialog Box with Macro Commands

Creating a Dialog Box with Dialog Editor

Modal Dialog Boxes

Modeless Dialog Boxes


Dialog Box Controls

Are input or output windows where the user interacts with a dialog box and its parent application.  Macros support the following dialog box controls:

Bitmaps

Check Boxes

Color Wheels

Combination Boxes

Counter Buttons

Dates

Edit Boxes

Filename Edit Boxes

Frames

Group Boxes

Horizontal Lines

Hot Spots

Icons

List Boxes

Pop-Up Buttons

Progress Indicators

Push Buttons

Radio Buttons

Scroll Bars

Static Text Controls

Viewers

Vertical Lines


Check Boxes

Display one or more options.  Use a callback function to activate user-defined responses.  See DialogAddCheckBox.


Color Wheels

Display colors to select.  See DialogAddColorWheel.


Combination Boxes

Display an edit box and a list box.  Enter text such as a filename in the edit box, or double-click a list item to insert it.  See DialogAddComboBox.


Counter Buttons

Display an edit box and a counter button.  Enter a number in the edit box, or click the counter button to insert a number.  See DialogAddCounter.


Edit Boxes

Receive text input.  There are different styles of edit controls, including single line and multiple line.  See DialogAddEditBox.


Filename Edit Boxes

Display an edit control and a button control.  Enter a filename in the edit control, or click the button to display the Select File dialog box.  See DialogAddFileNameBox.


Frames

Group items in a dialog box.  Accept no input.  See DialogAddFrame.


Group Boxes

Group items in a dialog box with a titled frame.  Accept no input.  See DialogAddGroupBox.


Horizontal Lines

Separate items in a dialog box.  Accept no input.  See DialogAddHLine.


Hot Spots

Are invisible controls that close a dialog box when the user clicks a defined area.  Redefine the response with a callback function.  See DialogAddHotSpot.


Icons

Display graphic representations.  Accept no input, unless used in a callback function with DIALOGADDHOTSPOT.  See DialogAddHotSpot, DialogAddIcon, DialogShow.


List Boxes

Display a list of options to choose from.  There are different styles of list boxes, including single-column and multi-column.  See DialogAddListBox.


PopUp Buttons
Pop-Up Buttons

Display the name of a menu item on a push button.  Click the button to display the menu.  See DialogAddPopupButton.


Push Buttons

Activate user-defined responses when chosen.  See DialogAddPushButton.


Radio Buttons

Display mutually exclusive options.  Use a callback function to activate user-defined responses.  See DialogAddRadioButton and DialogShow.


Scroll Bars

Scroll through documents, or activate user-defined responses with a callback function.  See DialogAddScrollBar and DialogShow.


Static Text Controls

Send text to a dialog box.  Accept no input.  See DialogAddText.


Viewers

Display read-only text files.  See DialogAddViewer.


Vertical Lines

Separate items in a dialog box.  Accept no input.  See DialogAddVLine.


Creating a Dialog Box with Macro Commands

To create a dialog box with macro commands, define it, add controls, and display it.  You should dismiss the dialog box when the macro ends.  The commands presented below create a dialog box.

Click the example button above to display the complete macro.

Define

Specify the size and style of the dialog box, and the controls it will contain.  The following command,

DialogDefine(Dialog: 1000; Left: 50; Top: 50; Width: 150; Height: 100; Style: OK! | Percent!; Caption: "Example Dialog Box")

defines (creates in memory) a dialog box with the following specifications:

Dialog: The number 1000 was chosen to identify the dialog box.  A name such as "MainDialog" could also have been used.  The number or name must be unique.  It is used again to add controls, display, and then destroy the dialog box when the macro ends.

Left, Top, Width, Height: The dialog box is displayed in the center of the screen by setting the left and top parameters to 50 and using the Percent! style.  Dialog boxes are positioned and sized in dialog units.  A vertical unit equals 1/8 the font height, and a horizontal unit equals 1/4 the font width.

Style: The Percent! formula is:

(screen width or height - dialog box width or height) * percentage

This formula equals the number of dialog units from the left side of the screen to the left side of the dialog box, or the number of dialog units from the top of the screen to the top of the dialog box.  The dialog box has an OK push button control.

Caption: The dialog box title is "Example Dialog Box".

Parameter names: Parameter names are optional.  For example,

Dialogdefine (1000; 50; 50; 200; 125; OK! | Percent!; "Example Dialog Box")

defines the same dialog box as the command above.

Add Controls

The following commands

DialogAddText (Dialog: 1000; Control: 100; Left: 10; Top: 10; Width: 50; Height: 15; Style: Left!; Text: "Edit control:")

DialogAddEditBox (Dialog: 1000; Control: 101; Left: 10; Top: 25; Width: 125; Height: 25; Style: Left! | VScroll! | Multiline!; vReturn; 1000)

add a static control and an edit control to the dialog box with the following specifications (see Dialog Box Controls):

Dialog: 1000 for both controls, which equals the Dialog parameter of the parent dialog box (see Define above).

Control: The controls have unique Control numbers (100 and 101), which could also be names such as "Control 1" and "Control 2".  Old-style dialog boxes used Control values to give a control the initial input focus (see Creating a Dialog Box with Dialog Editor).

The value of the Control used to dismiss the dialog box is returned in the implicit variable MacroDialogResult (see DialogDefine): 1 for OK, 2 for Cancel, 2 for Close (system menu box), 2 if you double-click the system menu box, 2 if you press Alt+F4, or the value of the Control parameter of a user-defined push button or hot spot (see DialogAddPushButton and DialogAddHotSpot).

Left, Top, Width, Height: The controls are displayed 10 dialog units from the left side of the dialog box, and 10 and 25 units from the top.  The widths are 50 and 175 dialog units, and the heights are 15 and 50 dialog units.  A vertical dialog unit equals 1/8 the font height, and a horizontal dialog unit equals 1/4 the font width.

Style: The static text is left justified.  The edit box is multi-line with a vertical scroll bar.  Combine styles with bitwise OR operator (|) (see Bitwise Operators).

Text: The static control text is "Edit Control".

MacroVar, LimitText: Text typed into the edit box is assigned to variable vReturn when the dialog box is dismissed by OK or Close on the system menu.  The maximum number of characters the edit control accepts is 1000.

Display

The following command

DialogShow ("1000"; "WordPerfect")

displays dialog box 1000 and gives the input focus to control 101 (edit control has the insertion point).

Dismiss

The following command

DialogDismiss ("1000"; "OKBttn")

dismisses dialog box 1000, and clears the value of the implicit variable MacroDialogResult.  If you need this value, assign it to another variable before executing DIALOGDISMISS.  If you do not destroy a dialog box before the macro ends, memory conflicts may occur.


Creating a Dialog Box with Dialog Editor

Use the Macro Dialog Editor to quickly and easily create, design, set properties for, and edit the dialogs you use in your macros.  Using the Macro Dialog Editor takes the place of the DialogDefine sections in your macros.

Macro Dialog Editor lets you add, edit, position, size, move, and assign values to controls, lines, and other elements of a dialog.  You can also use it to give each control a control name, variable name, values, and other properties, as well as define the control order, set the initial focus, set tab stops, and group controls.

With Dialog Editor you can visually create and edit dialogs for Windows* application macros.  Open Dialog Editor from the WordPerfect* PerfectScript or from within WordPerfect for Windows.

To open the Macro Dialog Editor from the PerfectScript,

1	Open PerfectScript (run PS70.EXE from Windows).

2	Choose Dialog from the Resource menu.

3	Specify a macro filename, then choose OK.

4	Choose File, New, type a name for the dialog, then choose File, Open.

or

Select the dialog you want, then choose File, Open.

To open the Macro Dialog Editor from within WordPerfect,

1	Choose Macro from the Tools menu, then choose Edit.

2	Specify a macro filename, then choose OK to display the Macro feature bar.  Click Dialog Editor on the macro feature bar.

3	Choose Create, type a name for the dialog, then choose OK.

or

Select the dialog you want, then choose Edit.  A file that contains only dialog definitions does not have to be compiled.


Example Dialog Box

{ [image]}

// Example Dialog Box

// Define dialog box

DialogDefine (Dialog: 1000; Left: 50; Top: 50; Width: 150; Height: 100; Style: OK! | Percent!; Caption: "Example Dialog Box")

//Static text control

DialogAddText (Dialog: 1000; Control: 100; Left: 10; Top: 10; Width: 50; Height: 15; Style: Left!; Text: "Edit control:")

// Edit box control

DialogAddEditBox (Dialog: 1000; Control: 101; Left: 10; Top: 25; Width: 125; Height: 25; Style: Left! | VScroll! | Multiline!; vReturn; 1000)

// Display dialog box

DialogShow ("1000"; "WordPerfect")

// Destroy dialog box

DialogDismiss ("1000"; "OKBttn")


Modal Dialog Boxes

Require the user to complete an action before input to the parent application is allowed.  For example, the Margins dialog box (WordPerfect*) and the Page Format dialog box (Presentations*) and the Busy Search Settings dialog box (GroupWise*) require the user to choose OK or Cancel before control returns to the application.  Macro dialog boxes are modal by default (see DialogDefine).


Modeless Dialog Boxes

Do not require the user to complete an action before input to the parent application is allowed.  For example, you can perform a search with the Find and Replace Text dialog box (WordPerfect*: choose Edit, Find and Replace), then click document and edit the document while the Find and Replace Text dialog box remains on the screen.  Click the dialog box to perform another search.  For information about creating a modeless dialog box, see DialogDefine.


PerfectScript

PerfectScript is an application included with Windows* applications to record, play, compile, and convert macros.

PerfectScript starts automatically when you record or play a macro from a Windows application that supports macros.  If you play a macro for an application that is not running, PerfectScript automatically starts the application.

You can set PerfectScript options, including the default macro directory, editor, and extension in the PerfectScript Preferences dialog box.  To display the dialog box, choose Edit, Preferences:

Additional Information

Compilers

Command-Based Macro Language

Compiler Errors

Run-time Errors


Compilers

In machine (computer) language, every word is a binary numeral consisting of zeros and ones.  For example, the first three letters of the alphabet in binary notation are 1000001, 1000010, and 1000011.  The binary result of 4 + 5 is 1001.  Because binary numerals are hard to work with, English-based programming languages (such as Basic, Pascal, and C) were created.  Programs written with the help of an editor or word-processor are saved as source files.  A compiler creates an object file, which is a copy of the source file translated into machine language.  Computers can execute only object files.

Macro languages are similar to programming languages.  Macros are written with an editor or word-processor and saved as a source file.  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.  It is recreated each time the source file is compiled.  A compiled source file (macro) contains instructions that are executed when you play the macro.


Command-Based Macro Language

A command-based macro language records keystrokes and/or mouse actions as commands.  It does not record the actual keystrokes.  For example, to display the Line Hyphenation dialog box (WordPerfect*), choose Format, Line, Hyphenation.  If you record these steps, your macro contains a product command named LineHyphenationDlg.


Compiler Errors

The compiler stops and displays a message when it discovers a macro syntax error (see Syntax).  The message contains information about the error and its location (the compiler makes a best guess and may not always be accurate).  Choose Cancel Compilation to dismiss the message box, or choose Continue Compilation to test for other errors.  You must correct all errors before a macro compiles.  See Macro Errors for common syntax errors.


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.  See Macro Errors.


Coach Overview

A Coach takes the user through some of the product's most common tasks step-by-step, providing instructions and prompts as needed.  The Coach can either show the user how to perform the desired task or it can tell the user what to do and then monitor the user's actions to make sure no mistakes are made.

The Coach Support Routines allow Coaches* to be written with macros for products that use PerfectScript.

The support routines provide three types of functions.

Prompting

CoachMessageBoxEx displays options for the user to select.  CoachPrompt displays helps and hints.

Animating

CoachAnimate shows the user how to perform certain actions.  The Coach can (1) move the mouse pointer, (2) send mouse clicks, and (3) send keystrokes to the application.

Filtering

CoachFilterAdd defines a filter to monitor tokens.  CoachFilterEnable activates the filter to compare defined events with current events.  If the user makes a mistake, the Coach might display a message box or prompt.

CoachFilterDisable deactivates a filter and CoachFilterDestroy destroys a filter.

Named Region

A named region is a specific window or item on the screen, such as "WordPerfect.OpenDlg.OpenBttn".  See Named Region in Mouse String.

Writing the Coach

A Coach generally follows these steps.

1	Pause keyboard and mouse input until a Coach enables it.

2	Define filter.

3	Instruct the user how to perform a task with prompts, message boxes, and animation.

4	Enable filter.

5	Wait for user input.

6	Respond to user input with a callback procedure.

7	Disable filter.

8	Destroy filter.

9	Turn on keyboard and mouse input.

Define all filters at the beginning of a Coach macro, then enable each one as it is needed.  Repeat steps 2 through 8 as many times as necessary.

Quitting the Coach

Press Alt+Esc to quit the Coach.

Coach Dialog Box

Coaches have a .WCH extension and are stored in the Help7 directory.

When the user chooses Coach from the Help menu, the descriptive names of all .WCH files in the macros directory are displayed in the Coach dialog box.  When a Coach name is selected, the information from the Abstract field of the document summary is displayed at the bottom of the Coach dialog box.  If the Coach does not have a descriptive name, the filename is displayed.


DDE Conversations

DDE Execute is a Windows* feature that enhances product integration by allowing applications to instruct each other to perform specific tasks (execute commands).  For example, using DDE Execute you can create macros in WordPerfect* that send commands to control other Windows applications.  In order for this to work, the other application must accept DDE Execute strings.  See DDEInitiate, DDEExecute, and DDETerminate.  Also, see the documentation for the other Windows application.  The information you need includes the service (application) name, topic name, and list of commands it will accept through DDE Execute.

In addition, Windows applications can use DDE Execute to control Presentations*.  The application must first initiate a DDE conversation using the service (application) name of "WPPresentations" and topic name of "Command".  Before terminating the conversation, the application can send DDE Execute strings made up of one or more Presentations macro commands.  Note that Presentations will accept only product commands, not programming commands.  These product commands may not contain variables or expressions.

Windows applications can also send commands to Presentations as a DDE Request item in order to receive a string representing the command's return value.  The application must send the DDE Execute string or DDE Request item in ANSI text format.  Presentations will return the DDE Request result as an ANSI text string.  If either a DDE Execute string or a DDE Request item returns an error, the application can send a DDE Request on the item "LastCmdError" to find out what went wrong.  This item will return an ANSI text string containing a three-digit error code and a description of the error.  See DDERequest.

DDE Execute Application Names, Services, and Topics

GroupWise*, GroupWise, Command

InfoCentral*, WPIC, RunMacro

Envoy*, Envoy, System

Presentations*, WPPresentations, Command

Quattro* Pro, QPW, <full path and filename of open notebook>

WPWin7, WPWin7_Macros, Commands

Envoy and InfoCentral

Envoy and InfoCentral act as servers for DDE Execute, but not clients. This means that you can use DDE Execute in products to send commands to Envoy and InfoCentral, but you cannot use DDE Execute in Envoy or InfoCentral to send commands to other products. For information about the DDE commands you can use with Envoy and InfoCentral, see the Software Development Kits that are available for these products.


Macro Examples

Line-by-line comments describe the following macros.  Click the copy button above each one to copy the macro to the Clipboard to paste in a WordPerfect* document.

ASSERT.WCM displays a menu and creates Cancel, Error, and Not Found conditions.

CALLBACK.WCM creates a callback function that responds to system menu box options and various dialog controls.

CB_SCBAR.WCM creates a callback function that responds to the position of a scroll bar thumb.

CALENDAR.WCM use DDE to launch GroupWise* 4.1 and open the GroupWise day calendar.

For a callback function example that responds to list item selections, see the DialogShow example.


Comment

Click the mouse to make this message disappear.


Macro: ASSERT.WCM

ASSERT.WCM uses MENU to display a list of options; ASSERT to create a Cancel, Error, or Not Found condition; and ONCANCEL, ONERROR, or ONNOTFOUND to execute a subroutine.  It also uses MESSAGEBOX to display messages and Go to create user-defined loops.  Click the comment buttons [image] for detailed explanations.

// Name: ASSERT.WCM // 1

// Directory: C:\MACROS // 2

// Description: Demonstrate Assert command // 3

APPLICATION(WP; "WPPrWin"; Default; "US") // 4

CALL(AssertConditions) // 5

CALL(DisplayMenu) // 6

CALL(QuitMacro) // 7

//********************************************************* // 8

//MAIN LABEL STATEMENTS // 9

//********************************************************* // 10

LABEL(AssertConditions) // 11

ONCANCEL(Conditions) // 12

ONERROR(Conditions) // 13

ONNOTFOUND(Conditions) // 14

vCondition := "Turn conditions Off!" // 15

RETURN // 16

LABEL(DisplayMenu) // 17

MENU(vChoice; Digit!; ; ; {"CancelCondition!"; "ErrorCondition!"; "NotFoundCondition!"; vCondition; "Quit"}) // 18

SWITCH(vChoice) // 19

CASEOF 1: ASSERT(CancelCondition!) // 20

CASEOF 2: ASSERT(ErrorCondition!) // 21

CASEOF 3: ASSERT(NotFoundCondition!) // 22

CASEOF 4: IF(vCondition = "Turn conditions Off!") // 23

GO(TurnConditionsOff) // 24

Else // 25

GO(TurnConditionsOn) // 26

ENDIF // 27

CASEOF 5: GO(QuitMacro) // 28

DEFAULT: Conditions // 29 [image] ENDSWITCH // 30

RETURN // 31

LABEL(QuitMacro) // 32

vMessage := "You selected 5, or you selected 1, 2, or 3 with all conditions Off!" // 33

MESSAGEBOX(vStatus; "Condition Status"; vMessage; RetryCancel! | IconInformation! | DefButton2!) // 34

IF(vStatus = 4) // 35

GO(DisplayMenu) // 36

Else // 37

QUIT // 38

ENDIF // 39

//********************************************************* // 40

//SECONDARY LABEL STATEMENTS // 41

//********************************************************* // 42

LABEL(Conditions) // 43

SWITCH(ErrorNumber) // 44

CASEOF 1: vMessage := "^0" // 45

CASEOF 2: vMessage := "^1" // 46

CASEOF 7: vMessage := "^2" // 47

DEFAULT:  vMessage := "^3" // 48

ENDSWITCH // 49

MESSAGEBOX(vStatus; "Condition Status"; vMessage; Ok! | IconInformation! | HasParameters!; {"You selected 1 with CANCEL(On!)"; "You selected 2 with ERROR(On!)"; "You selected 3 with NOTFOUND(On!)"; "Menu item not chosen"}) // 50

GO(DisplayMenu) // 51

LABEL(TurnConditionsOn) // 52

CANCEL(On!) // 53

ERROR(On!) // 54

NOTFOUND(On!) // 55

vCondition := "Turn conditions Off!" // 56

GO(DisplayMenu) // 57

LABEL(TurnConditionsOff) // 58

CANCEL(Off!) // 59

ERROR(Off!) // 60

NOTFOUND(Off!) // 61

vCondition := "Turn conditions On!" // 62

GO(DisplayMenu) // 63


Lines 1-3

Comments about the macro.


Line 2

Macros are generally saved to the application's macros directory.


Line 4

WordPerfect* identified as the default application.


Line 5

Call LABEL(AssertConditions), which identifies a LABEL subroutine to call when there is a Cancel, Error, or Not Found condition (lines 12-14).


Line 6

Call LABEL(DisplayMenu) after LABEL(AssertConditions) returns (line 16).  LABEL(DisplayMenu) displays a five-option menu (line 18).


Line 7

Call LABEL(QuitMacro) after LABEL(DisplayMenu) returns (line 31).  LABEL(QuitMacro) displays a message box where the user can end the macro or redisplay the menu (lines 32-39).


Lines 8-10

Comments identify LABELs that correspond to the opening CALL statements (lines 5-7).


Lines 11-16

LABEL(AssertConditions) identifies a LABEL to execute when a Cancel, Error, or Not Found condition occurs.


Line 12

Execute LABEL(Conditions) when a Cancel condition occurs (line 43).


Line 13

Execute LABEL(Conditions) when an Error condition occurs (line 43).


Line 14

Execute LABEL(Conditions) when a Not Found condition occurs (line 43).


Line 15

Assignment operator assigns a character string to a variable named vCondition, which is menu item 4 the first time the menu is displayed (line 18).  The default condition for CANCEL, ERROR, and NOTFOUND is On!.


Line 16

RETURN statement directs macro execution to CALL(DisplayMenu) (line 6).


Lines 17-31

LABEL displays a five-option menu and asserts a Cancel, Error, or Not Found condition depending on a menu choice.


Line 18

MENU displays a numbered (Digit!) list of five items.  The number the user chooses is assigned to vChoice.  Omitting the third and fourth parameters centers the menu on the screen.


Line 19

SWITCH initiates an action, depending on the value of vChoice, which contains the number of the chosen menu item.


Line 20

If 1 is selected, assert a Cancel condition.  The macro assigns 1 to the variable ErrorNumber (see Assert).  LABEL(Condition) is automatically called (lines 12 and 45).


Line 21

If 2 is selected, assert an Error condition.  The macro assigns 2 to the variable ErrorNumber (see Assert).  LABEL(Condition) is automatically called (lines 13 and 46).


Line 22

If 3 is selected, assert a Not Found condition.  The macro assigns 7 to the variable ErrorNumber (see Assert).  LABEL(NotFound) is automatically called (line 14 and line 47).


Lines 23-27

If 4 is selected, toggle CANCEL, ERROR, and NOTFOUND conditions by calling LABEL(TurnConditionsOn) (lines 52-57) or LABEL(TurnConditionsOff) (lines 58-63).  The label called depends on the contents of variable vCondition (lines 15, 56, and 62).  Update the description of menu item 4.


Line 28

If 5 is selected, end (quit) macro.


Line 29

If another key is pressed, such as Esc, LABEL(Condition) executes.  Notice that the subroutine name executes the subroutine.  See Subroutine Name.


Line 30

ENDSWITCH closes SWITCH statement (line 19).


Line 31

RETURN statement directs macro execution to CALL(QuitMacro).


Lines 32-39

LABEL(QuitMacro) displays a message box with an option to end the macro or redisplay the menu.


Line 33

Assignment operator assigns character string "You selected 5, or you selected 1, 2, or 3 with all conditions Off!" to variable vMessage (line 34).


Line 34

MESSAGEBOX displays a message box with an information icon and Retry and Cancel buttons.  If Retry is chosen, 4 is assigned to variable vStatus, or 2 is assigned to vStatus if Cancel is chosen.


Lines 35-36

If variable vStatus equals 4 (line 34), GO sends macro execution to LABEL(DisplayMenu), which redisplays the menu.


Lines 37-38

If vStatus is any value except 4 (Else), end the macro (QUIT).


Line 39

ENDIF closes IF statement (line 35).


Lines 40-42

Comments identify secondary LABELs or LABELs called from another LABEL (see lines 12-14, 24, and 26).


Lines 43-51

Execute LABEL(Conditions) when the user chooses 1, 2, or 3 (lines 20-22 and 12-14).


Line 44

SWITCH initiates an action, depending on the value of the variable ErrorNumber (lines 20, 21, 22) (see Assert).


Line 45

If ErrorNumber equals 1 (Cancel condition), assign "^1" to vMessage (see line 50).


Line 46

If ErrorNumber equals 2 (Error condition), assign "^2" to vMessage (see line 50).


Line 47

If ErrorNumber equals 7 (NotFound condition), assign "^3" to vMessage (line 50).


Line 48

If ErrorNumber contains a value other than 1, 2, or 7, assign "^4" to vMessage (line 50).


Line 49

ENDSWITCH closes SWITCH statement (line 44).


Line 50

MESSAGEBOX displays a message box with an information icon and OK button.  It uses the HasParameters! style, followed by four Message parameter options.  A caret (^) followed by a number in the Message parameter inserts the corresponding ParameterData message (one of the four message options) in its place (lines 45-48).  Numbering begins with 0.  See MessageBox.


Line 51

GO creates a loop by sending macro execution to LABEL(DisplayMenu), which redisplays the menu.


Lines 52-55

LABEL(TurnConditionsOn) turns on CANCEL, ERROR, and NOTFOUND conditions after LABEL(TurnConditionsOff) is executed.


Line 56

Assigns character string "Turn conditions Off!" to variable vCondition, which is displayed as menu item 4 (line 18).


Line 57

GO creates a loop by sending macro execution to LABEL(DisplayMenu), which redisplays the menu.


Lines 58-61

LABEL(TurnConditionsOff) turns off CANCEL, ERROR, and NOTFOUND conditions after the macro first starts or LABEL(TurnConditionsOn) is executed.


Line 62

Assigns character string "Turn conditions On!" to variable vCondition, which is displayed as menu item 4 (line 18).


Line 63

GO statement creates a loop by sending macro execution to LABEL(DisplayMenu), which redisplays the menu.


Macro: CALLBACK.WCM

CALLBACK.WCM creates a callback function that responds to system menu box options, check boxes, radio buttons, hot spots, and push buttons.  Click the comment buttons [image] for detailed explanations.

// Name: CALLBACK.WCM // 1

// Directory: C:\OFFICE7\MACROS\... // 2

// Description: Callback function displays a message when a user chooses a dialog box control // 3

APPLICATION(WP; "WPPrWin"; Default; "US") // 4

//********************************************************* // 5

// MAIN CALL STATEMENTS // 6

//********************************************************* // 7

CALL(InitializeVariables) // 8

CALL(CreateDialog) // 9

CALL(DisplayMainDialog) // 10

CALL(StartMessageLoop) // 11

CALL(QuitMacro) // 12

//********************************************************* // 13

// MAIN LABEL STATEMENTS // 14

//********************************************************* // 15

LABEL(InitializeVariables) // 16

WM_SYSCOMMAND := 274 // 17

WM_COMMAND := 273 // 18

vCheck := 0 // 19

vRadio := 0 // 20

vLoop := "Yes" // 21

RETURN // 22

LABEL(CreateDialog)// 23

DIALOGDEFINE(1000; 50; 50; 210; 175; 1+2+16; "Callback Function") // 24

DIALOGADDCHECKBOX(1000; 101; 10; 10; 50; 10; "Checkbox"; vCheck) // 25

DIALOGADDRADIOBUTTON(1000; 102; 10; 30; 60; 10;"Radio button"; vRadio) // 26

DIALOGADDHOTSPOT(1000; 103; 90; 10; 50; 50; 1) // 27

DIALOGADDFRAME(1000; 104; 90; 10; 50; 50; 5) // 28

DIALOGADDTEXT(1000; 105; 150; 30; 50; 15; 1; "<- Hot spot") // 29

vText1 := "Choose Close from the system menu, double-click" // 30

vText2 := "the system menu box, or press Alt+F4." // 31

DIALOGADDTEXT(1000; 106; 20; 95; 190; 15; 1; vText1) // 32

DIALOGADDTEXT(1000; 107; 20; 105; 170; 15; 1; vText2) // 33

DIALOGADDGROUPBOX(1000; 109; 10; 75; 185; 50; "System commands") // 34

RETURN // 35

LABEL(DisplayMainDialog) // 36

DIALOGSHOW (1000; 1; MsgLoop) // 37

RETURN // 38

LABEL(StartMessageLoop) // 39

WHILE(vLoop = "Yes") // 40

ENDWHILE // 41

RETURN // 42

LABEL(QuitMacro) // 43

DIALOGDESTROY(1000) // 44

QUIT // 45

//********************************************************* // 46

// CALLBACK FUNCTION // 47

//********************************************************* // 48

LABEL(MsgLoop) // 49

SWITCH(MsgLoop[3]) // 50

CASEOF 101: // 51

DIALOGDISMISS(1000; "OKBttn") // 52

MESSAGEBOX(vStatus; "Check Box"; "Check boxes display options.  Choose OK to hide the message box and return to the main dialog box."; OK! | IconInformation!) // 53

DIALOGSHOW (1000;1; MsgLoop) // 54

CASEOF 102: // 55

MESSAGEBOX(vStatus; "Radio Button"; "Radio buttons display mutually-exclusive options.  Choose OK to hide the message box and return to the main dialog box."; OK! | IconInformation!) // 56

CASEOF 103: // 57

MESSAGEBOX(vStatus; "Hot Spot"; "A hot spot was created over a filled frame.  You can also create a hot spot over an icon.  Choose OK to hide the message box and return to the main dialog box."; OK! | IconInformation!) // 58

CASEOF "OKBttn": // 59

MESSAGEBOX(vStatus; "OK Button"; "You chose the OK button on the main dialog box.  Choose OK to hide the message box and return to the main dialog box."; OK! | IconInformation!) // 60

CASEOF "CancelBttn": // 61

MESSAGEBOX(vStatus; "Cancel Button"; "Choosing Cancel assigns ""No"" to variable vLoop, which ends the loop and the macro."; OK! | IconExclamation!) // 62

vLoop := "No" // 63

ENDSWITCH // 64

IF(MsgLoop[5] = WM_SYSCOMMAND) // 65

MESSAGEBOX(vStatus; "System Command"; "After you choose OK, the main dialog box will disappear and then reappear after one second."; OK! | IconInformation!) // 66

DIALOGDISMISS(1000; "OKBttn") // 67

WAIT(10) // 68

DIALOGSHOW(1000; 1; MsgLoop) // 69

ENDIF // 70

RETURN // 71


Lines 1-3

Comments about the macro.


Line 2

Macros are generally saved to the default macros directory.


Line 4

WordPerfect* identified as the default application.


Lines 5-7

Comments identify the opening CALL statements that outline and define the macro's basic operations.


Line 8

Call LABEL(InitializeVariables), which initializes all variables (lines 16-22).  A run-time error occurs if you reference a variable that has not been assigned a value.  See VarErrChk.


Line 9

Call LABEL(CreateDialog) after LABEL(InitializeVariables) returns.  LABEL(CreateDialog) creates a dialog box in memory (lines 23-35).  It does not display the dialog box.


Line 10

Call LABEL(DisplayMainDialog) after LABEL(CreateDialog) returns.  LABEL(DisplayMainDialog) displays the dialog box and identifies a callback function.  See DialogShow.


Line 11

Call LABEL(StartMessageLoop) after LABEL(DisplayDialog) returns.  LABEL(StartMessageLoop) starts a message loop that suspends the dialog box for callback functions (lines 49-71).


Line 12

CALL LABEL(QuitMacro) after LABEL(StartMessageLoop) returns.  LABEL(QuitMacro) removes the dialog box from memory and ends the macro.


Lines 13-15

Comments identify LABELs that correspond to the opening CALL statements (lines 8-12).


Lines 16-22

LABEL(InitializeVariables) initializes all variables.


Lines 17-18

Initialize variables to contain Windows* message numbers.  Using variables makes the macro easier to read.  The variable names are user defined, but match the Windows message names.  See DialogShow.


Lines 19-20

Initialize check box and radio button variables (lines 25, 26).


Line 21

Initialize the loop variable.  vLoop is later assigned a new value to end the message loop (line 63), which sends macro execution to CALL(QuitMacro).


Line 22

RETURN sends macro execution to CALL(CreateDialog).


Lines 23-35

LABEL(CreateDialog) creates a dialog box in memory.


Lines 25-27

Control parameter values are sent as messages to the callback function (52-63).


Line 35

RETURN sends macro execution to CALL(DisplayMainDialog).


Lines 36-38

LABEL(DisplayMainDialog) displays the dialog box and identifies the callback function MsgLoop.  RETURN sends macro execution to CALL(StartMessageLoop).


Lines 39-42

LABEL(StartMessageLoop) starts the message loop that suspends the dialog box for callback functions (lines 49-71).  RETURN sends macro execution to CALL(QuitMacro).


Lines 43-45

LABEL(QuitMacro) removes the dialog box from memory and ends the macro.


Lines 46-48

Comments identify the callback function.


Lines 49-71

Callback function MsgLoop responds to five Control parameter messages and one system command message.  See DialogShow.


Line 50

SWITCH tests the third element of the callback function array.  See DialogShow.


Lines 51-63

Array element MsgLoop[3] contains the Control parameter value of the control that calls the callback function.  A message box describes the control.  In this macro, Cancel is the only button that can dismiss the dialog box.


Line 52

DIALOGDISMISS hides the dialog box while the message box is displayed (line 54).


Line 54

DIALOGSHOW redisplays the dialog box after the message box is dismissed (line 52).


Line 64

ENDSWITCH closes the SWITCH statement (line 50).


Lines 65-70

A WM_SYSCOMMAND message is received when the user chooses Close from the system menu box, double-clicks the system menu box, or presses Alt+F4.


Lines 67-69

DIALOGDISMISS hides the dialog box after the message box is dismissed.  WAIT(10) pauses the macro for one second.  DIALOGSHOW redisplays the dialog box.


Line 70

ENDIF closes the IF statement (line 65).


Line 71

RETURN sends macro execution to the message loop (lines 39-42).


Macro: CB_SCBAR.WCM
CB_SCBAR.WCM

CB_SCBAR.WCM creates a callback function that responds to Windows* WM_VSCROLL, WM_ACTIVATE, and WM_SYSCOMMAND messages.  It uses DIALOGADDSCROLLBAR to display a list item.  Click the comment buttons [image] for detailed explanations.

// Name: CB_SCBAR.WCM // 1

// Directory: C:\OFFICE7\MACROS\... // 2

// Description: Use DIALOGADDSCROLLBAR and a callback function // 3

APPLICATION(WP; WPPrWin; Default; "US") // 4

//********************************************************* // 5

// MAIN CALL STATEMENTS // 6

//********************************************************* // 7

CALL(InitializeVariables) // 8

CALL(CreateDlg) // 9

CALL(DisplayDlg) // 10

CALL(StartMessageLoop) // 11

CALL(QuitMacro) // 12

//********************************************************* // 13

// MAIN LABEL STATEMENTS // 14

//********************************************************* // 15

LABEL(InitializeVariables) // 16

SB_LINEUP := 0 // 17

SB_LINEDOWN := 1 // 18

SB_PAGEUP := 2 // 19

SB_PAGEDOWN := 3 // 20

SB_THUMBPOSITION := 4 // 21

SB_THUMBTRACK := 5 // 22

SB_TOP := 6 // 23

SB_BOTTOM := 7 // 24

SB_ENDSCROLL := 8 // 25

vOldPos := 10 // 26

y := 1 // 27

WM_SYSCOMMAND:= 274 // 28

WM_VSCROLL := 277 // 29

WM_ACTIVATE := 6 // 30

vLoop := 1 // 31

DECLARE List[10] // 32

vElement := 1 // 33

FOREACH(vFruit; {"Apples"; "Oranges"; "Papaya"; "Grapes"; "Bananas"; "Pears"; "Watermelon"; "Apricots"; "Peaches"; "Plums"}) // 34

List[vElement] := vFruit // 35

vElement := vElement + 1 // 36

ENDFOR // 37

RETURN // 38

LABEL(CreateDlg) // 39

DIALOGDEFINE(1000; 50; 50; 155; 160; 16; "Scroll Bar Callback Function") // 40

DIALOGADDSCROLLBAR(1000; "Scroll"; 135; 10; 0; 100; 2 + 8;BarPos; 1; 10) // 41

FORNEXT(yPos; 10; 100; 10) // 42

DIALOGADDTEXT(1000; 0; 10; yPos; 40; 10; 2; List[yPos / 10]) // 43

ENDFOR // 44 [image] DIALOGADDTEXT(1000; 0; 60; 10; 40; 10; 1; "Apples") // 45

DIALOGADDTEXT(1000; 0; 50; yPos + 15; 70; 10; 1; "Thumb Position   1") // 46

RETURN // 47

LABEL(DisplayDlg)  // 48

DIALOGSHOW (1000; 121; MsgLoop) // callback function = MsgLoop // 49

RETURN // 50

LABEL (StartMessageLoop) // 51

WHILE(vLoop = 1) // message loop // 52

ENDWHILE // 53

RETURN // 54

LABEL(QuitMacro) // 55

DIALOGDESTROY(1000) // 56

QUIT // 57

//********************************************************* // 58

// CALLBACK FUNCTION // 59

//********************************************************* // 60

LABEL(MsgLoop) // 61

SWITCH(MsgLoop[5]) // 62

CASEOF WM_SYSCOMMAND: // 63

GO(QuitMacro) // 64

CASEOF WM_VSCROLL: // 65

CALL(ScrollCtrl) // 66

CASEOF WM_ACTIVATE: // 67

CALL(MsgBox) // 68

ENDSWITCH // 69

SWITCH(MsgLoop[3]) // 70

CASEOF "CancelBttn": // 71

GO(QuitMacro) // 72

ENDSWITCH // 73

RETURN // 74

LABEL(ScrollCtrl) // 75

SWITCH(MsgLoop[6]) // 76

CASEOF SB_LINEUP: // 77

CALL(LineUp) // 78

CASEOF SB_LINEDOWN: // 79

CALL(LineDown) // 80

CASEOF SB_PAGEUP: // 81

CALL(PageUp) // 82

CASEOF SB_PAGEDOWN: // 83

CALL(PageDown) // 84

CASEOF SB_THUMBPOSITION: // 85

CALL(Thumb) // 86

//CASEOF SB_THUMBTRACK: // 87

//CALL(Thumb) // 88

CASEOF SB_TOP: // 89

CALL(PageUp) // 90

CASEOF SB_BOTTOM: // 91

CALL(PageDown) // 92

CASEOF SB_ENDSCROLL: // 93

DIALOGADDTEXT(1000; 0; 107; 125; 10; 10; 1; y) // 94

ENDSWITCH // 95

RETURN // 96

LABEL(Thumb) // 97

y := MsgLoop[7] // 98

y := y  & 65535 // 99

CALL(TypeFruit) // 100

RETURN // 101

LABEL(LineUp) // 102

IF(NOT(y = 1)) // 103

y := y - 1 // 104

CALL(TypeFruit) // 105

Else // 106

BEEP // 107

ENDIF // 108

RETURN // 109

LABEL(LineDown) // 110

IF(NOT(y = 10)) // 111

y := y + 1 // 112

CALL(TypeFruit) // 113

Else // 114

BEEP // 115

ENDIF // 116

RETURN // 117

LABEL(PageUp) // 118

y := 1 // 119

CALL(TypeFruit) // 120

RETURN // 121

LABEL(PageDown) // 122

y := 10 // 123

CALL(TypeFruit) // 124

RETURN // 125

LABEL(TypeFruit) // 126

vBlank := "                         " // 127

DIALOGADDTEXT(1000; 0; 60; vOldPos; 40; 10; 1; vBlank) // 128

DIALOGADDTEXT(1000; 0; 60; y * 10; 40; 10; 1; List[y]) // 129

vOldPos := y * 10 // 130

RETURN // 131

LABEL(MsgBox) // 132

MESSAGEBOX(vStatus; "Message Box"; "Do you want to cancel this message?"; YesNo! | IconQuestion!) // 133

IF(vStatus = 6) // 134

WM_ACTIVATE := 0 // 135

ENDIF // 136

RETURN // 137


Lines 1-3

Comments about the macro.


Line 2

Macros are generally saved to the default macros directory.


Line 4

WordPerfect* identified as the default application.


Lines 5-7

Comments identify the opening CALL statements which outline and define the macro's basic operations.


Line 8

Call LABEL(InitializeVariables), which initializes all variables (lines 16-38).  A run-time error occurs if you reference a variable that has not been assigned a value.  See VarErrChk.


Line 9

Call LABEL(CreateDlg) after LABEL(InitializeVariables) returns.  LABEL(CreateDlg) creates a dialog box in memory (lines 39-47).  It does not display the dialog box.


Line 10

Call LABEL(DisplayDlg) after LABEL(CreateDlg) returns.  LABEL(DisplayDlg) displays the dialog box and identifies a callback function.  See DialogShow.


Line 11

CALL LABEL(MessageLoop) after LABEL(DisplayDlg) returns.  LABEL(MessageLoop) starts a message loop that suspends the dialog box for callback function (lines 61-74).


Line 12

CALL LABEL(QuitMacro) after LABEL(MessageLoop) returns.  LABEL(QuitMacro) removes the dialog box from memory and ends the macro.


Lines 13-15

Comments identify LABELs that correspond to the opening CALL statements (lines 8-12).


Lines 16-38

LABEL(InitializeVariables) initializes all variables.


Lines 17-25

Initialize variables with numbers that correspond to positions on the scroll bar.  See DialogAddScrollBar.


Line 26

The position of the most recent list item displayed in the dialog box.  This position is cleared of text when a new list item is displayed (lines 127-128).


Line 27

The current position for displaying a new list item (line 129).


Lines 28-30

Initialize variables to contain Windows* message numbers.  Using variables makes the macro easier to read.  The variable names are user defined, but match the Windows message names.  See DialogShow.


Line 31

Initialize the loop variable.  In this example, vLoop does not receive a new value.  The loop ends when the macro ends (line 57).  It is possible to end the message loop and not the macro by changing the value of vLoop.


Line 32

Creates a 10-element array named List.


Lines 33-37

Fills array with the names of 10 fruits.  Variable vElement identifies the element to fill.


Line 38

RETURN sends macro execution to CALL(CreateDlg).


Lines 39-47

LABEL(CreateDlg) creates a dialog box in memory.


Lines 42-44

A FORNEXT statement creates a list of names.  The Control parameter of DIALOGADDTEXT is set to 0 to allow this command to execute in a FORNEXT statement.  This is possible for controls that do not accept input.


Line 43

List is a 10-element array.  The initial value of variable yPos is also 10.  Dividing yPos by 10 reduces yPos to a number that corresponds to an element in the array.  DIALOGADDTEXT uses the number to display the contents of the corresponding element.


Line 44

ENDFOR closes the FORNEXT statement (line 42).


Line 45

Displays the first list item in a second column.


Line 46

Displays the initial thumb position.


Line 47

RETURN sends macro execution to CALL(DisplayDlg).


Lines 48-50

LABEL(DisplayDlg) displays the dialog box and identifies the callback function MsgLoop.  RETURN sends macro execution to CALL(StartMessageLoop).


Lines 51-54

LABEL(StartMessageLoop) starts the message loop that suspends the dialog box for callback functions (lines 61-74).  RETURN sends macro execution to CALL(QuitMacro).


Lines 55-57

LABEL(QuitMacro) removes the dialog box from memory and ends the macro.


Lines 58-60

Comments identify the callback function.


Lines 61-74

Callback function MsgLoop responds to three Windows* messages and one Control parameter message.  See DialogShow.


Line 62

SWITCH tests the fifth element of the callback function array.  See DialogShow.


Lines 63-64

A WM_SYSCOMMAND message is received when the user chooses Close from the system menu box, double-clicks the system menu box, or presses Alt+F4.  Macro execution jumps to LABEL(QuitMacro).


Lines 65-66

A WM_VSCROLL message is received when the user clicks the scroll bar.  The macro calls LABEL(ScrollCtrl).


Lines 67-68

A WM_ACTIVATE message is received when the dialog box is activated.  The macro calls LABEL(MsgBox).


Line 69

ENDSWITCH closes the SWITCH statement (line 62).


Lines 70-73

SWITCH tests the third element of the callback function array and determines when Cancel is chosen.  See DialogShow.  An IF statement also works here.  There is often more than one choice to test.


Line 74

RETURN sends macro execution to the message loop (lines 52-53).


Lines 75-96

LABEL(ScrollCtrl) tests the wParam of the MW_VSCROLL message (line 76).


Line 76

SWITCH tests the sixth element(wParam value passed with WM_VSCROLL) of the callback function array to determine the mouse's location when clicked.


Lines 77-94

See DialogAddScrollBar for details about WM_VSCROLL messages.


Lines 77-78

Scroll bar's right arrow clicked.  Call LABEL(LineUp).


Lines 79-80

Scroll bar's left arrow clicked.  Call LABEL(LineDown).


Lines 81-82

Area between the right arrow and thumb clicked.  Call LABEL(PageUp).


Lines 83-84

Area between the left arrow and thumb clicked.  Call LABEL(PageDown).


Lines 85-86

Position of thumb after it is dragged, passed as the low-order word of lParam in the seventh element of the callback function array.  Call LABEL(Thumb).


Lines 87-88

Current position of thumb as it is dragged, passed as the low-order word of lParam in the 7th element of the callback function array.  Call LABEL(Thumb).  Lines 87-88 call the same function as lines 85-86 and have comment marks (//).  To test lines 87-88, add comment marks (//) to lines 85-86 and remove them from 87 and 88 (see //).


Lines 89-90

Home key pressed while the scroll bar has the input focus.  Call LABEL(PageUp).


Lines 91-92

End key pressed while the scroll bar has the input focus.  Call LABEL(PageDown).


Lines 93-94

Scroll bar activity has ended.  Display the current thumb position, contained in variable y.


Line 95

ENDSWITCH closes the SWITCH statement (line 76).


Line 96

RETURN sends macro execution to LABEL(MsgLoop) callback function.


Lines 97-101

LABEL(Thumb) retrieves the thumb position after it is dragged (MsgLoop[6] = SB_THUMBPOSITION), or as it is dragged (MsgLoop[6] = SB_THUMBTRACK).


Line 98

Assign the value of MsgLoop[7] (element 7 of the callback function array) to variable y.


Line 99

Calculate the low-order word of variable y using the bitwise AND operator.  See Bitwise Operators.  The value assigned to y is the current thumb position.


Line 100

Call LABEL(TypeFruit) to display the list item that corresponds to the current thumb position.


Line 101

RETURN sends macro execution to LABEL(ScrollCtrl).


Lines 102-109

LABEL(LineUp) is called when the right arrow is clicked to make the current line (value of y) equal to the current thumb position.


Lines 103-105

If the current line is not 1, assign the value of y - 1 to y, and call LABEL(TypeFruit) to display the list item that corresponds to the current thumb position.


Lines 106-107

Beep if the value of y equals 1 (if the first item is displayed).  (Try changing this so the last item is displayed.)


Line 108

ENDIF closes the IF statement (line 103).


Line 109

RETURN sends macro execution to LABEL(ScrollCtrl).


Lines 110-117

LABEL(LineDown) is called when the left arrow is clicked to make the current line (value of y) equal to the current thumb position.


Lines 111-113

If the current line is not 10, assign the value of y + 1 to y, and call LABEL(TypeFruit) to display the list item that corresponds to the current thumb position.


Lines 114-115

Beep if the value of y equals 10 (if the last item is displayed).  (Try changing this so the first item is displayed.)


Line 116

ENDIF closes the IF statement (line 111).


Line 117

RETURN sends macro execution to LABEL(ScrollCtrl).


Lines 118-121

LABEL(PageUp) is called when the area between the right arrow and thumb is clicked.


Line 119

Assign 1 to variable y to make 1 the current line and thumb position.


Line 120

Call LABEL(TypeFruit) to display the first list item on the first line.


Line 121

RETURN sends macro execution to LABEL(ScrollCtrl).


Lines 122-125

LABEL(PageDown) is called when the area between the left arrow and thumb is clicked.


Line 123

Assign 10 to variable y to make 10 the current line and thumb position.


Line 124

Call LABEL(TypeFruit) to display the last list item on the last line.


Line 125

RETURN sends macro execution to LABEL(ScrollCtrl).


Lines 126-131

LABEL(TypeFruit) displays a list item on the line that corresponds to the current thumb position.


Line 127

Assign blank spaces to variable vBlank to erase the previous list item when a new one is displayed.


Line 128

Erase the previous list item.  The vertical position is contained in variable vOldPos that has an initial value of 10 (line 26).  This value is updated (line 130) every time LABEL(TypeFruit) is called.


Line 129

Type a new list item at the current thumb position times 10 (the current line position).  The current thumb position (value of y) identifies the current list item (List[y]).


Line 130

Assign the current line position to variable vOldPos to be used (line 128) when this subroutine is called again.


Line 131

RETURN sends macro execution to the subroutine's caller.


Lines 132-137

LABEL(MsgBox) is called when the dialog box is activated (lines 67-68).  If you choose No, the dialog box is activated when the message box is dismissed and LABEL(MsgBox) is called again.  The message box is called until the user chooses Yes (lines 134-136).


Line 133

See MessageBox.


Lines 134-136

If variable vStatus equals 6 (Yes chosen), assign 0 to WM_ACTIVATE.  Changing the value of WM_ACTIVATE invalidates it as a Windows* activate message (lines 30 and 67-68).


Line 137

RETURN sends macro execution to LABEL(MsgLoop) callback function.


Macro: CALENDAR.WCM

DDE is a method of the Windows* operating system that transfers commands and other information between applications.  For example, you can use DDE to execute GroupWise* commands from WordPerfect*.

CALENDAR.WCM opens the GroupWise 4.1 day calendar.  Click the comment buttons [image] for detailed explanations.

// Name: CALENDAR.WCM // 1

// Directory: C:\OFFICE7\MACROS\... // 2

// Description: Open GroupWise Day calendar // 3

// Method: Dynamic Data Exchange // 4

APPLICATION(WP; "WPPrWin"; Default; "US") // 5

//********************************************************* // 6

//MAIN CALL STATEMENTS // 7

//********************************************************* // 8

CALL(IsGroupWiseRunning) // 9

CALL(OpenDayCalendar) // 10

CALL(QuitMacro) // 11

//********************************************************* // 12

//MAIN LABEL STATEMENTS // 13

//********************************************************* // 14

LABEL(IsGroupWiseRunning) // 15

IF(APPLOCATE("Novell* GroupWise 4.1") = 0) // 16

vPath := "c:\ofwin40\" // 17

vResult := APPEXECUTEEXT(vPath + "ofwin.exe"; 0) // 18

IF(vResult < 32) // 19

SWITCH(vResult) // 20

CASEOF 2: CALL(FileNotFound) // 21

CASEOF 3: CALL(PathNotFound) // 22

DEFAULT: CALL(ErrorMsg) // 23

ENDSWITCH // 24

ENDIF // 25

ENDIF // 26

RETURN // 27

LABEL(OpenDayCalendar) // 28

ASSIGN(hDay; APPLOCATE("Day")) // 29

IF(hDay) // 30

APPACTIVATE(hDay) // 31

Else // 32

ASSIGN(hConv; DDEINITIATE("GROUPWISE"; "COMMAND")) // 33

IF(hConv) // 34

DDEEXECUTE(hConv; "ViewOpenNamed(ViewName:""Day""; ViewType:Calendar!)") // 35

Else // 36

CALL(QuitMacro) // 37

ENDIF // 38

ENDIF // 39

RETURN // 40

LABEL(QuitMacro) // 41

DDETERMINATEALL // 42

QUIT // 43

//********************************************************* // 44

//SECONDARY LABEL STATEMENTS // 45

//********************************************************* // 46

LABEL(FileNotFound) // 47

BEEP // 48

ASSIGN(vMessage; "File not found - ending macro") // 49

GO(DisplayMessage) // 50

LABEL(PathNotFound) // 51

BEEP // 52

ASSIGN(vMessage; "Path not found - ending macro") // 53

GO(DisplayMessage) // 54

LABEL(ErrorMsg) // 55

BEEP // 56

ASSIGN(vMessage; "Unable to launch GroupWise 4.1 - ending macro") // 57

GO(DisplayMessage) // 58

LABEL(DisplayMessage) // 59

MESSAGEBOX(var; "ERROR"; vMessage; Ok! | IconExclamation!)  [image] // 60

GO(QuitMacro) // 61


Lines 1-4

Comments about the macro.


Line 2

Macros are generally saved to the default macros directory.


Line 5

WordPerfect* identified as the default application.


Lines 6-8

Comments identify the opening CALL statements, which outline and define the macro's basic operations.


Line 9

Call LABEL(IsGroupWiseRunning) to determine if GroupWise is running.


Line 10

Call LABEL(OpenDayCalendar) to initiate a DDE conversation with GroupWise and send an Office command to open the Day calendar view.


Line 11

Call LABEL(QuitMacro) to end the macro.


Lines 12-14

Comments identify the main LABEL statements.


Lines 15-27

LABEL(IsGroupWiseRunning) determines if GroupWise is running.  If GroupWise is not running, this LABEL(IsGroupWiseRunning) starts it.


Line 16

APPLOCATE returns the GroupWise window handle if the window title is found, or returns 0 if not.  If 0 is returned, the next statement is executed (line 17).  If a window handle is returned, RETURN (line 27) sends macro execution to CALL(OpenDayCalendar).  Another way to write the statement is:

vResult := APPLOCATE("Novell* GroupWise 4.1")

IF(vResult = 0)


Line 17

If necessary, change this line to the directory that contains the GroupWise program files.


Line 18

APPEXECUTEEXT returns the application handle if GroupWise is started (line 16), or returns an error value less than 32 if GroupWise is not started.  See AppExecuteExt.


Line 19

If vResult is less than 32 (error occurred), execute SWITCH statement (lines 20-24).


Lines 20-23

IF vResult equals 2, call LABEL(FileNotFound).  If vResult equals 3, call LABEL(PathNotFound).  For any value less than 32, call LABEL(ErrorMsg).  See AppExecuteExt for a list of error values.


Line 24

ENDSWITCH closes the SWITCH statement (line 20).


Line 25

ENDIF closes the IF statement (line 19).


Line 26

ENDIF closes the IF statement (line 16).


Line 27

RETURN sends macro execution to CALL(OpenDayCalendar).


Lines 28-40

LABEL(OpenDayCalendar) determines if the Day calendar view is already open.


Line 29

APPLOCATE returns the Calendar view window handle if the window title is found, or returns 0 if the window title is not found.  The handle or 0 is assigned to variable hDay.


Lines 30-31

If variable hDay equals a window handle (a non-zero number), use APPACTIVATE to activate the Calendar view.  The statement IF(hDay) is equivalent to IF(hDay <> 0).


Lines 32-33

IF variable hDay equals 0 (Else), initiate a conversation with GroupWise and assign the result to variable hConv.


Lines 34-35

If variable hConv equals a window handle (a non-zero number), execute the ViewOpenedNamed Office command.


Lines 36-37

If variable hConv equals 0 (conversation not initiated), call LABEL(QuitMacro).


Line 38

ENDIF closes IF statement (line 34).


Line 39

ENDIF closes IF statement (line 30).


Line 40

RETURN sends macro execution to CALL(QuitMacro).


Lines 41-43

LABEL(QuitMacro) ends the macro.


Lines 44-46

Comments identify the SECONDARY label statements.


Lines 47-50

LABEL(FileNotFound) beeps, assigns a file not found message to variable vMessage, and sends macro execution to LABEL(DisplayMessage).


Lines 51-54

LABEL(PathNotFound) beeps, assigns a path not found message to variable vMessage, and sends macro execution to LABEL(DisplayMessage).


Lines 55-58

LABEL(ErrorMsg) beeps, assigns an unknown error message to variable vMessage, and sends macro execution to LABEL(DisplayMessage).


Lines 59-61

LABEL(DisplayMessage) displays the appropriate error message and sends macro execution to LABEL(QuitMacro).


Line 60

MESSAGEBOX displays the contents of variable vMessage (lines 49, 53, and 57).


Modified Commands and Features

Operator Precedence Levels

New Function Format

Parameter Name Changes

Commands (obsolete)

Application

AppActivate

AppExecute

Assert

BIF Functions

Cancel/Error/NotFound/VarErrChk

DefaultUnits

Dialog and Region Commands

Dialog Sizing

DialogAdd Commands

DialogAddCounter

DialogAddFilenameBox

DialogAddScrollBar

DialogDefine

DialogDismiss and DialogDestroy

DialogShow

DLLCall

ErrorNumber

GetFileDateAndTime

IfPlatform

MMPlay

MMSpeak and MMSpeakClipboard

NumStr

OnCancel/OnError/OnNotFound

Prompt

Region Commands

RegionRemoveListItem

SetFileDateAndTime

StrPos

SubStr


New Commands and Features

Math Operators

** (exponentiation operator)

- (string reduction operator)

<<< (left rotate operator)

>>> (right rotate operator)

= (equality operator defined for arrays)

!= (non-equality operator defined for arrays)

<> (non-equality operators defined for arrays)

IN (membership operator)

Math Functions

[0] (array element count)

AbsVal

acos

acosh

asin

asinh

atan

atan2

atanh

Average

Ceiling

Constants

ConvertType

cos

cosh

CubeRoot

DegreesToRadians

ExponentPart

Factorial

Fibonacci

Floor

gcf

IntegerPart

FractionalPart

FractionStr

lcm

lg

log

ln

logn

MantissaPart

Max

Min

NthRoot

pi

Product

RadiansToDegrees

Randomize

RandomNumber

RoundOff

Sign

sin

sinh

SquareRoot

Sum

tan

tanh

Date and Time Functions

DateAndTime

DateDay

DateMonth

DateMonthName

DateString

DateWeekday

DateWeekdayName

DateYear

TimeHour

TimeHundredth

TimeMinute

TimeSecond

TimeString

Dialog/Region/Coach Commands

CallbackWait

CallbackResume

DialogAddBitmap

DialogAddDate

DialogAddProgress

DialogLoad

DialogSave

DialogSetProperties

DoesDialogExist

RegionGetHandle

RegionGetListCount

RegionGetModified

RegionSetBitmapFilename

RegionSetModified

RegionSetProgressPercent

CoachMessageBoxEx

CoachRegister

Network Commands

NetAddConnection

NetCancelConnection

NetConnectionDlg

NetDisconnectDlg

NetGetConnection

NetGetUniversalName

NetGetUser

Registry Commands

RegistryCloseKey

RegistryCreateKey

RegistryDeleteKey

RegistryDeleteValue

RegistryEnumKey

RegistryEnumValue

RegistryOpenKey

RegistryQueryKeyCount

RegistryQueryLastError

RegistryQueryValue

RegistryQueryValueCount

RegistrySetValue

String Functions

StrPad

StrTrim

StrRight

StrLeft

StrFill

StrInsert

StrReverse

StrScan

StrIsChar

StrTransform

StrToChars

StrFraction

ToInitialCaps

WordCount

Miscellaneous Commands

AppClose

AppShow

BinaryPack

BinaryUnPack

Condition

Constant

EnvVariableGet

EnvVariableSet

FileNameDialog

MacroInfo

MMStopPlay

OnCondition

OnCondition Call

SizeOf

ValueType


Operator Precedence Levels

A new precedence level has been added for the exponentiation operator (**).  All precedence levels after 1 have increased by 1.  See Operator Precedence.


New Function Format

Various commands called as procedures are now called as functions.  The  result of these commands is no longer written to an output variable (formerly the first parameter).  The procedure format is retained for compatibility only.

DDEInitiate

DialogHandle

BIFFilePath

DLLLoad

OnDDEAdvise Call

RegionGetWindowText

RegionGetSelectedText

RegionGetCheck

RegionIsVisible

Commands that have an additional return value

BIFInfo

BIFRead

BIFWrite

MessageBox


Commands that Support Named Parameters

Various commands have been changed to enable the passing of parameter names.

AppActivate

AppExecute

AppExecuteExt

AppLocate

Assert

Beep

Cancel

Chain

CharLen

CharPos

CToN

DDEExecute

DDEExecuteExt

DDEInitiate

DDEPoke

DDERequest

DDETerminate

DDETerminateAll

DefaultUnits

DllFree

DLLLoad

EndPrompt

Error

Fraction

GetNumber

GetString

GetUnits

Nest

NotFound

NToC

NumStr

OnCancel

OnCancel Call

OnDDEAdvise Call

OnError

OnError Call

OnNotFound

OnNotFound Call

Pause

PersistAll

Prompt

Quit

Run

SendKeys

Speed

StrLen

StrNum

StrPos

StrUnit

SubChar

SubStr

ToLower

ToUpper

UnitStr

VarErrChk

Wait


6843 Commands (obsolete)
Commands (obsolete)

AssertCancel

AssertError

AssertNotFound

CancelOff

CancelOn

DialogDisplay

DialogUnDisplay

ErrorOff

ErrorOn

NotFoundOff

NotFoundOn

VarErrChkOff

VarErrChkOn


Application

The product prefix in Application, EndApp, and NewDefault is no longer limited to two characters (it can be the name of the product itself).  It is now easier to read a macro when more than one product is involved.


AppActivate

Now accepts a window handle or a string as its first parameter.

AppActivate


AppExecute

Now supports starting non-program files using Windows's associations.

AppExecute


Assert

Now accepts user-defined conditions.  See Assert and OnCondition for a description of how to specify a user-defined condition.


BIF Functions

BIFFilePath, BIFInfo, BIFRead, and BIFWrite are provided for backward compatibility only.  Settings are now located in the Windows* Registry, and are accessed with the new Registry commands.  If you use the BIF commands, you should specify a BIF filename in the BIFFile parameter.


Cancel/Error/NotFound/VarErrChk

Modified to return the previous state (On! or Off!) of a specified condition.  Setting a new state is now optional, which means you can get the state (On! or Off!) without changing it.

Cancel

Error

NotFound

VarErrChk


DefaultUnits

Modified to return the previous default units value.  You can save the current value, set a new value, then restore the old value.  Setting a new value is now optional, which means you can get the default units value without changing it.

None! has been added to the enumeration list of units values.  With None! set, no conversion is performed when a non-units value is added to a units value.  The non-units value is assumed to be of the same unit type as the units value.

DefaultUnits


Dialog and Region Commands

DialogDefine used to create a dialog immediately.  Now dialogs are assembled in memory and not actually created until a DialogLoad or DialogShow command.  Region commands that reference a dialog or a dialog control will not work until after DialogLoad or DialogShow.  Similarly, DialogHandle will not work until after DialogLoad or DialogShow.

Old macros may have to be edited to reflect this change.

Dialog names are now limited to 25 characters in text-based dialog statements (old-style dialogs) and in dialogs created with the Dialog Editor (new-style dialogs).


Dialog Sizing

Specifying a dialog size used to include the caption and borders.  In Windows* 95, captions and borders can be sized by the user.  To ensure that dialogs display correctly in any environment, dialog sizes no longer include the space occupied by captions and borders.


DialogAdd Commands

You can now add controls to dialogs created with Dialog Editor using DialogAddText, DialogAddListBox, DialogAddPushButton, DialogAddFrame, and so on.


DialogAddCounter

Now accepts counters of various unit formats.  When a value is entered with no unit of measure (24 in stead of 24i), the value is assumed to be the counter type and not the default units type.

DialogAddCounter


DialogAddFilenameBox

The NoValidate! style is no longer supported because of changes to the Open dialog.

DialogAddFilenameBox


DialogAddScrollBar

Left!, Right!, Top!, and Bottom! styles apply to placing a scroll control within a control window.  They no longer apply to placing the thumb within the scroll bar.  By default, the thumb is positioned at the minimum position of the scroll bar.

DialogAddScrollBar


DialogDefine

NoFrame! style no longer works.  In Windows* 95, removing a frame also removes the captions bar.  For backward compatibility, the NoFrame! style compiles but is non-functional.

DialogDefine


DialogDismiss and DialogDestroy

Dialogs created with Dialog Editor that have no callback are destroyed when a button is pushed.  Subsequent calls to DialogDismiss or DialogDestroy result in run-time error messages (the macro system no longer knows anything about the dialog).

When a callback is declared (see DialogShow), the macro continues to receive and execute instructions (it is not destroyed when a button is pushed).  DialogDismiss hides the dialog; DialogDestroy destroys it.


DialogShow

Accepts an optional fourth parameter that specifies a control to receive the initial focus.

The Parent parameter can now be used with text-based (old-style) dialogs.

In callback dialogs, a WM_INITDIALOG (value 272) is now sent in callback array [5] when the dialog is created.

DialogShow

All dialog callbacks should be reviewed and possibly changed to accommodate a 32-bit environment.  In particular, entries in the callback array that refer to the wParam (entry [6]), the lParam ([7]) and the hiword ([8]), and the lParam and the loword ([9]), should be carefully reviewed.  The wParam has been made into a DWord, and many values have been moved between the wParam and the lParam.


DLLCall and DLLCall Prototype

Old macros that use DLLCall must be rewritten to work in Windows* 95.  DLLs and the APIs provided by the DLLs do not exist or have been modified to work in Windows 95.

DLLCall


ErrorNumber

Is now a programming command that returns the last error number, and appears in the documentation with all other commands.  For now, the command does not return any new information.


GetFileDateAndTime

Returns a numeric value representing the date and time the file was written to.  This value is comparable to the value returned by DateAndTime, and can be converted to a string with the DateString and TimeString functions.

This command used to return the number of seconds since January 1, 1980 in an undocumented format.

GetFileDateAndTime


IfPlatform

The PlatformID for Windows* 95 is Win95! (Win32! is also accepted).  The old value of Win! is reserved for 16-bit Windows 3.x.

You can use IfPlatform to start comments, similar to the // command.  When the compiler does not recognize a PlatformID value, it ignores all comments between IfPlatform and EndPlatform.

Example

IfPlatform (SomeNotes)

...comment...

...comment...

...comment...

EndPlatform

Result: Comments between IfPlatform and EndPlatform are ignored by the compiler.


MMPlay

Accepts an optional parameter named Options, with values of DontWait! (start playing and return immediately) and Wait! (wait for play to finish then proceed to the next macro statement).

MMPlay also returns a handle that can be passed to the new command MMStopPlay.

MMPlay

MMStopPlay


MMSpeak and MMSpeakClipboard

Three additional text-to-speech products are supported: TextAssist, ProVoice, and Monologue.

MMSpeak

MMSpeakClipboard


NumStr

No longer compatible with WordPerfect* for Windows 5.2 format.  You must use the current format and parameter order.

NumStr


OnCancel/OnError/OnNotFound

These commands have been modified to return the label associated with a specified condition (Cancel, Error, or NotFound), as well as to set a new label.  If no label was found, "" is returned.

Leaving off the Label parameter resets condition handling to its initial state.

OnCancel

OnError

OnNotFound


Prompt

Accepts a new style named NoButtons!  The prompt displays without OK or Cancel buttons, which is useful for displaying "Please Wait" messages.

Prompt accepts another new style named Pause!, which does the same thing as the Pause command.

Pause

Prompt


Region Commands

Cannot be used on a dialog until after DialogLoad or DialogShow.  DialogLoad creates the dialog in memory; DialogShow creates the dialog and shows it.  Before this happens, regions are not associated with a window and have no meaning.

Storing dialog information and creating the dialog all at once increases performances.

Creating dialogs this way also makes text-based dialogs and dialogs created with Dialog Editor compatible.


RegionRemoveListItem

Removes an item with an exact match before it removes an item with a partial match.

RegionRemoveListItem


SetFileDateAndTime

Sets the date and time a file was last written to, using a value returned from the DateAndTime command.

SetFileDateAndTime used to set the date and time as the number of seconds since January 1, 1980.

DateAndTime

SetFileDateAndTime


StrPos

No longer compatible with WordPerfect* for Windows 5.2.  You must use the current format and parameter order.

StrPos


SubStr

No longer compatible with WordPerfect* for Windows 5.2.  You must use the current format and parameter order.

SubStr


Changing Your Macros to Work with Corel WordPerfect
Changing Your Macros to Work with Corel WordPerfect 7

This page is a quick overview of things you may need to do to your PerfectOffice 3.0 (WPWin 6.1) macros to make them work in PerfectScript 7.

Review all DLLCall statements and make changes to accommodate the 32-bit environment.  In particular, change calls to Windows* APIs (in user.dll, kernel.dll, and gdi.dll) to use 32-bit Windows DLLs and to account for parameter changes.

Review variable, label, procedure, and function names, and change if the name has become a reserved word.  For example, a subroutine with the name sin or cos (math functions).

Review BIF calls.  Settings for 32-bit applications are stored in the Windows Registry.  Use the new Registry tokens to access Corel Office* 7 settings.  Other usages of the BIF may or may not work.  For example, if another PerfectOffice 3.0 application is running (GroupWise*, WordPerfect* 6.1, Presentations* 3.0, or Quattro* Pro), BIFWrite calls do not work on Public! and Private! These applications open the BIF exclusively, preventing changes to the file from other applications.

SubStr, NumStr, and StrPos cannot be used as they were in WPWin 5.2.  This was allowed in WPWin 6.1, but is no longer supported.

DialogHandle will not work until after DialogLoad or DialogShow.  In PerfectOffice 3.0, DialogHandle worked after DialogDefine.

You may have to adjust dialog sizing to get the same look as PerfectOffice 3.0.

Calling DialogDismiss for a dialog created with the Dialog Editor creates an error if a callback is not used.

The PerfectScript 7 platform is Win95 rather than Win (Windows 3.x).  See IfPlatform.

All dialog callbacks should be reviewed and possibly changed to accommodate a 32-bit environment.  In particular, entries in the callback array that refer to the wParam (entry [6]), the lParam ([7]) and the hiword ([8]), and the lParam and the loword ([9]), should be carefully reviewed.  The wParam has been made into a DWord, and many values have been moved between the wParam and the lParam.


Callback Data Description

When a macro executes a callback routine, global return and parameter array variables are automatically created by the macro system that are accessible to the callback routine.  The callback routine can access the callback parameter array for information about the callback event, and will place its return value (if any) in the callback return variable.

The parameters for the callback are placed into a global array variable that has the same name as the callback label.  The return value (if any) returned from callback routines is placed in a (non-array) global variable that has the same name as the callback label.  For example, parameters would be passed to callback routine 'MsgHandler' in an array called 'MsgHandler[ ]', and any return value would be placed into a variable called 'MsgHandler'.

The return value, the number of callback array entries, and the values contained in the callback array depend on the type of callback being called.  The callback type is found in the first ([1]) entry of the callback array.  The callback array element count can be retrieved by using the Dimensions command, or by accessing the [0] callback array element.

Callback array entries

This type of callback is setup by the CoachFilterAdd command.RTN Callback return value (depends on [1])

[0] Count of elements in callback array

[1] Callback type:

0 = CBTYPE_MOUSE - Mouse callback (CoachFilterAdd command)

1 = CBTYPE_KEY - Key and Keystring callback (CoachFilterAdd command)

2 = CBTYPE_TOKEN - Product token (command) callback (CoachFilterAdd command)

3 = CBTYPE_DIALOG - Dialog callback (DialogShow and CoachSetDialogFilter commands)

4 = CBTYPE_CBTMSGBOX - MessageBox callback (CoachMessageBox command)

[2] Repeating (depends on [1])

Entries for Mouse callback (type 0 - CBTYPE_MOUSE)

This type of callback is no longer supported. See CoachInputControl.

Entries for Key and Keystring callback (type 1 - CBTYPE_KEY)

This type of callback is no longer supported.  See CoachInputControl.

Entries for Product token (command) callback (type 2 - CBTYPE_TOKEN)

This type of callback is setup by the CoachFilterAdd command.

RTN Callback return value:

undefined = Pass the event to the application

0 = Pass the event to the application

1 = Discard the event

[0] Callback array contains 7 elements plus 1 for each token parameter (count in [6])

[1] Callback type 2 = CBTYPE_TOKEN

-1 = Error - The callback array is not complete.

0 = Match - The user's actions exactly match the defined actions.

1 = No match - The user's actions do not match the defined actions.

2 = Partial match - The user's actions partially match the defined actions.

3 = Regression - The event undoes previous events, such as a Backspace.  A regression is not a match. Received only if LabelType is Any! or NonMatch!.

4 = Quit filter - The callback is not called.

[3] Name of application that sent this token

[4] Macro id of the macro that sent this token (if sent by a macro)

[5] Product token id

[6] Number of parameters for this token

[7] Token flags

[8] Value of first parameter

[9] Value of second parameter

[10]... Value of ..., etc

Entries for Dialog callbacks (type 3 - CBTYPE_DIALOG)

This type of callback is setup by the DialogShow and CoachSetDialogFilter commands.

RTN Callback return value (only if [5] = WM_COMMAND (273) and from CoachSetDialogFilter, else not used):

undefined = Send the event to the application

0 = Send the event to the application

1 = Do not send the event to the application

[0] Callback array contains 11 elements

[1] Callback type 3 = CBTYPE_DIALOG

[2] Dialog name

[3] Control name (if [5] = WM_COMMAND (273) and not a menu item, or if [5] = TCN_SELCHANGING (-552), else "")

[4] Dialog window handle

[5] Windows* message id being sent (see below)

[6] Value of the 32-bit DWORD wParam parameter that was received with the message

[7] Value of the 32-bit DWORD lParam parameter that was received with the message

[8] Value of the HIWORD of the lParam parameter [7] that was received with the message

[9] Value of the LOWORD of the lParam parameter [7] that was received with the message

[10] Value of the HIWORD of the wParam parameter [6] that was received with the message

[11] Value of the LOWORD of the wParam parameter [6] that was received with the message

Elements [6] to [11] have different meanings for each Windows* message (contained in [5]).  See Windows 95 documentation for more information.  When [5] is:

272 = WM_INITDIALOG

Sent when the dialog is first displayed.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[6] Window handle of the control that will receive focus

2 = WM_DESTROY

Sent when the dialog goes down.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

6 = WM_ACTIVATE

Sent when the dialog is activated or deactivated.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[7] Window handle of the window being activated or deactivated

[10] Minimized flag (non-zero means minimized)

[11] Dialog activation state:

0 = WA_INACTIVE (dialog becomes inactive)

1 = WA_ACTIVE (dialog becomes active)

2 = WA_CLICKACTIVE (dialog becomes active from mouse click)

3 = WM_MOVE (only sent from CoachSetDialogFilter)

Sent when the dialog is moved to a new location.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[8] New X position

[9] New Y position

276 = WM_HSCROLL (not sent from CoachSetDialogFilter),

277 = WM_VSCROLL (not sent from CoachSetDialogFilter)

Sent when the user clicks on a scroll bar control.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[7] Window handle of the ScrollBar control

[10] Position of thumb in ScrollBar control (if [11] = 4 or 5, else not used)

[11] Scroll notification code:

6 = SB_TOP (HOME key pressed - scroll to the top or left)

7 = SB_BOTTOM (END key pressed - scroll to the bottom or right)

8 = SB_ENDSCROLL (Scroll bar activity ended)

0 = SB_LINEDOWN (Down or Right arrow clicked - scroll ahead 1 line)

1 = SB_LINEUP (Up or Left arrow clicked - scroll back 1 line)

2 = SB_PAGEDOWN (Area between Down or Right arrow and thumb clicked - scroll ahead 1 page)

3 = SB_PAGEUP (Area between Up or Left arrow and thumb clicked - scroll back 1 page)

4 = SB_THUMBPOSITION (Position of thumb after it is dragged is in [10])

5 = SB_THUMBTRACK (Current position of thumb as it is dragged is in [10])

274 = WM_SYSCOMMAND (not sent from CoachSetDialogFilter)

Sent when the user presses Alt+F4, chooses Close from the system menu, or double clicks the system menu.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[11] Menu item id of system menu item selected:

61536 if Close, Alt+F4 or double click on system menu

273 = WM_COMMAND

Sent when the user interacts with a control or menu item on the dialog.

These messages can be altered by the callback if sent from the CoachSetDialogFilter command, by returning a value in the callback return variable.

RTN Callback return value (used only from CoachSetDialogFilter command):

undefined = Send the event to the application

0 = Send the event to the application

1 = Don't send the event to the application

[3] Control name or number, or:

"" if from a menu item

"OKBttn" if from the predefined OK button

"CancelBttn" if from the predefined Cancel button

[7] Control window handle ("" if from a menu item)

[10] Notification code (depends on the control type):

Menu items: (not used)

ListBox:

2 = LBN_DBLCLK - Item was double clicked

ComboBox:

2 = CBN_DBLCLK - Item was double clicked

Button:

0 = BN_CLICKED - Button was clicked

5 = BN_DOUBLECLICKED - Button was double clicked

FileNameEntry:

0 = FNEN_DLGDISMISS - Open Dialog was dismissed

1 = FNEN_DLGRAISE - Open Dialog was displayed

HotSpot:

0 = BMPN_CLICKED - Bitmap was clicked

5 = BMPN_DOUBLECLICKED - Bitmap was double clicked

[11] Control id or menu item id (depends on the control type):

Menu item:

Menu item id

Controls:

Control id or:

1 if from the predefined OK button

2 if from the predefined Cancel button

-552 = TCN_SELCHANGING

Sent when a different tab on a tab control is being.

These messages can be altered by the callback by returning a value in the callback return variable.

RTN Callback return value (used only from CoachSetDialogFilter command):

undefined = Send the event to the application

0 = Send the event to the application

1 = Do not send the event to the application

[3] Control name

[9] Zero based tab index number (the first tab is 0)

[11] Tab control id

Entries for MessageBox callback (type 4 - CBTYPE_CBTMSGBOX)

This type of callback is setup by the CoachMessageBoxEx command.

Callbacks called only if Modality parameter is not Simple!.

RTN Callback return value not used

[0] Callback array contains 4 elements

[1] Callback type 4 = CBTYPE_CBTMSGBOX

[2] Name of the message box

[3] Name of the control

[4] Control state:

0 = Checked, pressed or clicked

1 = Unchecked, not pressed, or not clicked


** examples

vResult = 2**3

Result: vResult = 8 (2 to the 3rd power)

vResult = 4**2

Result: vResult = 16 (4 to the 2nd power)


+/- (string) examples
+ (string) example

vStr := "abcdefg" + "xyz"

Result: vStr = "abcdefgxyz"

- (string) example

vStr := "abcdefg xyz" - " xyz"

Result: vStr = "abcdefg"


IN example

z := 3 IN {1; 2; 3}

Result: z = True

z := 3 IN (1; 2; 4}

Result: z = False

z := {1; 2; 3} IN {1; 2; 3}

Result: z = True

z := {1; 2; 3} IN {1; 2; 3; 4}

Result: z = True

z := {1; 2; 3} IN {1; 2; 4}

Result: z = False


Rotate left (<<<) example

-2 <<< 2 is 5


Rotate right (>>>) example

5 >>> 1 is -2147483646


Bitmaps

Display bitmap graphics.  Accept no input, unless used in a callback function with DIALOGADDHOTSPOT.  See DialogAddHotSpot, DialogAddBitmap, DialogShow.


Date Controls

Display a date.  Accept no input.  See DialogAddDate.


Progress Indicators

Display a progress indicator.  See DialogAddProgress.


Bitwise rotate left (<<<) example

x := -2147450881 <<< 1

Result: x equals 65535

Previous example in binary notation

<<<10000000000000000111111111111111

Result: 1111111111111111 (binary 65535)


Bitwise rotate right (>>>) example

x := 65535 >>> 1

Result: x equals -2147450881

Previous example in binary notation

>>>1111111111111111  (binary 65535)

Result: 10000000000000000111111111111111


Glossary

ANSI Character Set

Any (data type)

Argument

Assignment Statements

Boolean (data type)

Callback Function

Character Expression (string)

Check Boxes

Command Name

Command Inserter

Comment Statements

Conditional Statements

Control Statement

Data Type

DLL (Dynamic Link Library)

Drop-down List

Edit Boxes

Enumeration

Expression

Global Variable

Label

List Box

Local Variable

Loop Statements

Macro Feature Bar

Measurement

Measurement Expression

Numeric Expression (numeric)

Numeric Measurement

OLE (Object Linking and Embedding)

Operator

Parameter

PerfectScript

Persist Variable

Product Commands

Product Prefix

Programming Commands

Prompt

Radio Button

Relational Expression

Run-time

Scroll Bars

String

System Variables

Subroutines

Syntax

Toggle

User-defined Dialog Box

Value Set Member

Variables

Window

Window Handle


Reserved Words

You should not use reserved words as names for variables, arrays, labels, functions, or procedures.

A

ADDRESS

AND

ANSISTRING

APPACTIVATE

APPEXECUTE

APPEXECUTEEXT

APPLOCATE

APPLICATION

ASSERT

ASSERTCANCEL

ASSERTERROR

ASSERTNOTFOUND

ASSIGN

B

BEEP

BOOL

BREAK

C

CALL

CANCEL

CANCELCONDITION

CANCELOFF

CANCELON

CASE

CASEOF

CENTIMETERS

CHAIN

CHARLEN

CHARPOS

CONTINUE

CTON

D

DDEEXECUTE

DDEEXECUTEEXT

DDEINITIATE

DDEPOKE

DDEREQUEST

DDETERMINATE

DDETERMINATEALL

DECLAREDEFAULT

DEFAULTUNITS

DIGIT

DISCARD

DIV

DLLCALL

DLLFREE

DLLLOAD

DWORD

E

ELSE

ENDAPP

ENDFOR

ENDFUNC

ENDIF

ENDIFPLATFORM

ENDPROC

ENDPROMPT

ENDSWITCH

ENDWHILE

ERROR

ERRORCONDITION

ERROROFF

ERRORON

ERRORNUMBER

EXISTS

F

FALSE

FILE

FOR

FOREACH

FORNEXT

FRACTION

FUNCTION

G

GETNUMBER

GETUNITS

GETSTRING

GLOBAL

GO

H

HIWORD

I

IF

IFPLATFORM

INCHES

INDIRECT

INPUT

INTEGER

L

LABEL

LENGTH

LETTER

LOCAL

LOWORD

M

MENU

MENULIST

MILLIMETERS

MOD

N

NEST

NEXT

NEWDEFAULT

NOT

NOTFOUND

NOTFOUNDCONDITION

NOTFOUNDOFF

NOTFOUNDON

NTOC

NUMSTR

O

OEMSTRING

OFF

ON

ONCANCEL

ONDDEADVISE

ONERROR

ONNOTFOUND

OR

P

PAUSE

PERSIST

PERSISTALL

POINTS

POSITION

PROCEDURE

PROMPT

PROTOTYPE

Q

QUIT

R

REAL

REPEAT

RETURNRETURNCANCEL

RETURNERROR

RETURNNOTFOUND

RUN

S

SENDKEYS

SPEED

STRING

STRLEN

STRNUM

STRPOS

STRUNIT

SUBCHAR

SUBSTR

SWITCH

T

TOLOWER

TOUPPER

TRUE

U

UNITSTR

UNTIL

USE

V

VALUE

VARERRCHK

VARERRCHKOFF

VARERRCHKON

VOID

W

WAIT

WHILE

WORD

WPSTRING

WPUNITS

WP1200THS

XYZ

XOR


Programming Commands List

[]

~

**

*

/

%

+

+

-

-

<<

>>

<<<

>>>

=

<>

!=

<

<=

>

>=

&

|

^

:=

=

//

[0]

A

AbsVal

acos

acosh

Address

AND

AnsiString

AppActivate

AppClose

AppExecute

AppExecuteExt

Application

AppLocate

AppShow

asin

asinh

Assert

Assign

atan

atan2

atanh

Average

B

Beep

BIFFilePath

BIFInfo

BIFRead

BIFWrite

BinaryPack

BinaryUnPack

Break

C

Call

Call

CallbackResume

CallbackWait

Cancel

Case Call

Case

CaseOf

Ceiling

Chain

CharLen

CharPos

CloseFile

CoachAnimate

CoachFilterAdd

CoachFilterDestroy

CoachFilterDisable

CoachFilterEnable

CoachGetRegionInfo

CoachInputControl

CoachMessageBoxClose

CoachMessageBoxEx

CoachPrompt

CoachPromptClose

CoachRegister

CoachRemoveDialogFilter

CoachSetDialogFilter

Condition

Constant

Constants

Continue

ConvertType

CopyFile

cos

cosh

CreateDirectory

CToN

CubeRoot

D

DateAndTime

DateDay

DateMonth

DateMonthName

DateString

DateWeekday

DateWeekdayName

DateYear

DDEExecute

DDEExecuteExt

DDEInitiate

DDEPoke

DDERequest

DDETerminate

DDETerminateAll

Declare

Default

DefaultUnits

DegreesToRadians

DeleteDirectory

DeleteFile

DialogAddBitmap

DialogAddCheckBox

DialogAddColorWheel

DialogAddComboBox

DialogAddControl

DialogAddCounter

DialogAddDate

DialogAddEditBox

DialogAddFileNameBox

DialogAddFrame

DialogAddGroupBox

DialogAddHLine

DialogAddHotSpot

DialogAddIcon

DialogAddListBox

DialogAddListItem

DialogAddPopupButton

DialogAddProgress

DialogAddPushButton

DialogAddRadioButton

DialogAddScrollBar

DialogAddText

DialogAddViewer

DialogAddVLine

DialogDefine

DialogDestroy

DialogDismiss

DialogHandle

DialogSave

DialogSetProperties

DialogShow

DialogUnDisplay

Dimensions

Discard

DIV

DLLCall Prototype

DLLCall

DLLFree

DLLLoad

DoesDialogExist

DoesDirectoryExist

DoesFileExist

DWord

E

Else

EndApp

EndFor

EndFunc

EndFunction

EndIf

EndIfPlatform

EndProc

EndProcedure

EndPrompt

EndSwitch

EndWhile

EnvVariableGet

EnvVariableSet

Error

ErrorNumber

Exists

ExponentPart

F

Factorial

Fibonacci

FileError

FileFind

FileIsEOF

FileNameDialog

FilePosition

FileRead

FileSize

FileTruncate

FileWrite

Floor

For

ForEach

ForNext

Fraction

FractionalPart

FractionStr

Function

Function Prototype

G

gcf

GetCurrentDirectory

GetFileAttributes

GetFileDateAndTime

GetNumber

GetString

GetUnits

Global

Go

H

No commands

I

Icm

If

IfPlatform

Include

IN

Indirect

Integer

IntegerPart

J

No commands

K

KeyString

L

Label

lg

ln

Local

log

logn

M

MacroArgs[]

MacroDialogResult

MacroFileName

MantissaPart

Max

Menu

MenuList

MessageBox

Min

MMPlay

MMSpeak

MMSpeakClipboard

MMStopPlay

MMStopSpeech

MOD

Mouse String

N

Nest

NetAddConnection

NetCancelConnection

NetConnectionDlg

NetDisconnectDlg

NetGetConnection

NetGetUniversalName

NetGetUser

NewDefault

Next

NOT

NotFound

NthRoot

NToC

NToC

NumStr

O

OemString

OnCancel Call

OnCancel

OnCondition Call

OnCondition

OnDDEAdvise Call

OnError

OnError Call

OnNotFound Call

OnNotFound

OpenFile

OR

P

Pause

Persist

PersistAll

pi

Procedure

Procedure Prototype

Product

Prompt

Q

Quit

R

RadiansToDegrees

Randomize

RandomNumber

Real

RegionAddListItem

RegionEnableWindow

RegionGetCheck

RegionGetHandle

RegionGetListCount

RegionGetModified

RegionGetSelectedText

RegionGetWindowText

RegionIsVisible

RegionMoveWindow

RegionRemoveListItem

RegionResetList

RegionSelectListItem

RegionSetBitmapFilename

RegionSetCheck

RegionSetFocus

RegionSetModified

RegionSetProgressPercent

RegionSetWindowText

RegionShowWindow

RegistryCloseKey

RegistryCreateKey

RegistryDeleteKey

RegistryDeleteValue

RegistryEnumKey

RegistryEnumValue

RegistryOpenKey

RegistryQueryKeyCount

RegistryQueryLastError

RegistryQueryValue

RegistryQueryValueCount

RegistrySetValue

RenameDirectory

RenameFile

Repeat

Return

Return

RoundOff

Run

S

SendKeys

SetCurrentDirectory

SetFileAttributes

SetFileDateAndTime

Sign

sin

sinh

SizeOf

Speed

SquareRoot

Step

StrFill

StrFraction

String

StrInsert

StrIsChar

StrLeft

StrLen

StrNum

StrPad

StrPos

StrReverse

StrRight

StrScan

StrToChars

StrTransform

StrTrim

Structure

StrUnit

SubChar

SubStr

Sum

Switch

T

tan

tanh

TimeHour

TimeHundredth

TimeMinute

TimeSecond

TimeString

ToInitialCaps

ToLower

ToUpper

U

UnitStr

Until

Use

V

Value

ValueType

VarErrChk

W

Wait

While

WordCount

WPString

X

XOR

Y

No commands

Z

No commands


ANSI Character Set

The 256 characters of the American National Standards Institute.


Any (data type)

Accepts more than one data type as input.  For example, the command AppActivate (Windows: Any).  The Windows parameter accepts a window title (string data type) or a window handle (numeric data type).


Argument

A variable, constant, or expression required by a command or function.


Boolean (data type)

Accepts or returns a value of True or False.


Callback Function

A special function that enables a macro to respond immediately and in specific ways to events such as selecting a radio button or check box, without waiting until a dialog box is dismissed.  See DialogShow.


Character Expression (string)

One or more characters enclosed in a quotation marks, which identifies the characters as text, not a variable.


Command Inserter

Inserts product and/or programming commands into a macro document.  Select the Command button on the Macro Feature Bar, or use MacroCommandInserter in a macro.


Control Statement

Alters the sequential execution of macro commands.  See Macro Control Statements.


DLL (Dynamic Link Library)

A library of functions and procedures that can be called from a macro.


Drop-down List

A type of list available to a Combo Box control.  See DialogAddComboBox.


Expression

Represent values, and can be arithmetic, numeric, measurement, relational, logical, bitwise, or a character string.


Macro Feature Bar

A feature bar that contains tools for writing and editing macros.  It contains buttons for saving, compiling, inserting macro commands, and so on.  Click Tools, Macro, Macro Feature Bar.


Measurement Expression

A number followed by a unit of measure (", i, c, m, p, w).


Numeric Expression (numeric)

A number on which mathematical operations may be performed.  Numeric expressions are not enclosed in quotation marks.


OLE (Object Linking and Embedding)

A feature that copies information from one document to another (embedding), through a "live" link.  When the original document changes, the embedded copy reflects the changes.


Operator

A symbol or word that performs a function on one or more expressions.  Operators compare expressions, link words together, and perform mathematical functions.


PerfectScript

An application used to record, play, compile, convert, and edit macros.  PerfectScript is used to build or edit dialog boxes for macros.


Product Prefix

A two-character expression that specifies a product for a macro command.


Prompt

A message box that displays information for the user.


Relational Expression

An expression that evaluates parameters with only two possible states: TRUE and FALSE.


Run-time

Execution time.  Run-time errors occur during macro execution.  Run-time options are application start-up settings, such as the macros default directory.


String

A data type that accepts charactes enclosed in double quotation marks.


User-defined Dialog Box

A custom dialog box created with Dialog programming commands that display options for user input.


Window

Each window has a title bar, a menu bar, and a status bar, and may contain a scroll bar, Toolbar, and Ruler.  The Equation Editor window has separate editing and display areas called panes.


Window Handle

A unique identifier for a window or control.


Data Type

Defines the set of values that a variable can store.  The data types are numeric, string, measurement, boolean, any, enumeration, and label.


Enumerated Type

The parameters for some product commands accept only certain predefined words known as "enumerated types."  Enumerated types end with exclamation points.  For example, DisplayMode parameter accepts only Text!, Graphics!, or FullPage!.


Value Set Member

A value in an enumeration list.  An enumeration is a data type.


Toggle

A toggle command switches between states.  For example, the WordPerfect Bold command can be On! or Off!.  If On! or Off! is not specified, Bold "toggles" between the two states each time it is called.  If Bold is Off!, it is turned On!.  If Bold is On!, it is turned Off!.


Numeric

Pop-up text can be inserted in the ROUTE field of the database or here in the topic file. If you insert it in the database, leave the <ROUTE> style to signal the precompiler to bring in the text. If you wish to enter text in the file remove the <ROUTE> style.


Label

A subroutine similar to a procedure or function.  A Label generally contains one or more statements followed by Return or Quit.  For more information, see Subroutines in Macro Control Statements.


Measurment (data type)

All Measurement return values are returned in WordPerfect Units.  Necessary unit conversions are done internally when comparing two measurement values.  Recorded macros use the units specified in the application preferences.  When specifying a measurement value in a product command parameter, WordPerfect units (w) are assumed unless other units are specified in the parameter or with the DefaultUnits command.


Measurement

A data type that accepts a measurement value in inches, millimeters, WP units, and so on.  For example, 72P (points) is equal to 1I (inch) and to 2.54C (centimeters).


Command Name

Command names often describe the action, such as Font, MarginLeft, Advance, and FootnoteOptions. Command names execute product features (product commands) or direct the execution of the macro (programming commands, for example, If, Else, End If).


Syntax

The command grammar or sequence: command names, parameter names, and parameter types.


Command Names

There are two general types of macro commands: product commands and programming commands.

Product Commands

Product commands are specific for each application, such as WordPerfect or Presentations. They perform various functions in that application, such as:

display a dialog box (InitialCodesStyleDlg)

specify settings such as styles (BorderBottomLine), user preferences (PrefZoom), or attributes (Font)

turn features on and off (InhibitInput or TableCellIgnoreCalculation)

perform 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)

play macros that are included with the application (FontDnShippingMacro)

Product commands that report information (return value) about the state of an application or feature are sometimes called system variables.  In WordPerfect, system variables begin with a leading question mark (?ColumnWidth). In Presentations, they begin with a leading Env (EnvPaths). Some system variables in Presentations have parameters as well as return values.

Programming Commands

Product commands are application specific, and programming commands work across applications. Product commands control or return information about applications and feature functions.  Programming commands generally control macro functions, such as:

specify conditions under which other macro commands or statements will operate (CASE, IF ELSE ENDIF, SWITCH ENDSWITCH)

repeat macro commands or statements a specified number of times or until certain conditions are met (FOR ENFOR, REPEAT UNTIL, WHILE ENDWHILE)

invoke or jump to a specified subroutine (statement block) with CALL or GO

The Command Inserter keeps programming commands and product commands in separate lists. Click the button under Type to display and select the list you want.


Parameter Names

Using parameter names is optional. 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 WordPerfect system variables have no parameters. Their syntax is the command name alone, such as PAUSE and ?FeatureBar.

Italics

Italics in Macros Help 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)

Punctuation

Enclose parameters in parentheses. A missing parenthesis, either opening or closing, is a common error that prevents macros from compiling.

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!)

Enclose repeating parameters in braces. 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!).


Data Types and Return Values

A data type represents information that is needed by a parameter or returned by a command (return value).

A list of return values shows the possible values that can be returned for that command.

In the command syntax, data types are displayed in italics. For example, the enumerations for the Rotation parameter of BoxCaptionRotation are Degrees90!, Degrees 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, enum, numeric. Programming commands also frequently use variable.

string  Represents text you provide, such as a filename, dialog box control names, message box text, or character sequence to insert into a document. Strings may include numbers. Enclose strings in quotation marks. For example, Type ("1") and MESSAGEBOX (vStatus; "VAR" + x; "Continue to next variable?" ; IconQuestion! |YesNo!!)

enumeration   Represents options provided by the program, such as styles, types, methods, state, and so on. For example, in WordPerfect, On!, Heading8Style!, and DefFlushRight! are enumerations used by different commands. Enumerations always end with an exclamation point.

numeric  Represents a number, such as the number of seconds, a line number, an outline level.

measurement  Represents a unit of measure, such as inches, picas, or WordPerfect units.

token id  Represents the name of a macro command (InvokeDialog).

variable A variable name must begin with a letter and is not case-sensitive. (Variables in Macro Help examples all begin with a leading v.) Variables can include any combination of letters or numbers up to 50 characters. For example, you could "assign" the value "C:\COREL\OFFICE7\WPWIN7\" to variable "vPath", then substitute the variable for the path in the rest of the macro.

You can change the value of a variable.  If variable vNmbr equals 5, then the expression vNmbr := vNmbr + 1 results in vNmbr equaling 6.


Buttons

To see how to record a command, click To Record.

For related information, click Related Topics.

For sample macros and command clusters that use this command, click Example.


Enumerations

Options provided by the program, such as styles, types, and methods, are called enumerations. For example, in WordPerfect, On!, Heading8Style!, and DefFlushRight! are enumerations used by different commands. Enumerations always end with an exclamation point.


Program Command Example
Click the red word to read information about that item.


Product Command Example
Click the red word to read information about that item.