Chapter 11: Ma to Mo

Chapter 11

Corel^Ž PerfectScript^Ž 8 Programming Commands

Three new macro commands have been added: MacroCompile, MacroIsCompiled, and MacroPlay. See online Help for information about these commands. Also, the following commands have been changed: DialogAddControl, DialogDelete, FileFind, FileNameDialog, GetFileAttributes, MacroInfo, OLEAutomation, and SetFileAttributes. See online Help for information about these commands.

MacroArgs[ ]

Purpose

An array variable that contains parameter arguments passed to it by Chain, Nest, or Run, or on the command line with the /m- option.

// Macro: MAIN.WCM

// Include the full path if the macro is not in the 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

Syntax

value := MacroArgs[<Index> numeric]

MacroDialogResult

Purpose

MacroDialogResult is a predefined macro variable that is updated to reflect the status of the Dialog commands. These commands are functions that mostly return the same value placed into MacroDialogResult. The list of commands below are followed by the values placed into MacroDialogResult if successful or if not successful.

Command Name: successful / not successful

DialogDefine: dialog name / empty string ("")

DialogDestroy: True / False

DialogShow (callback dialog): dialog handle / 0

DialogShow (non-callback): control name / empty string ("") The return value for this command is different when the control is the OK or Cancel control. MacroDialogResult returns "1" for OK, and "2" for Cancel. This command returns "OKBttn" and "CancelBttn".

DialogDisplay: True / False

DialogDismiss: control name / empty string ("") See the description of the non-callback DialogShow command above.

DialogUndisplay: True / False

DialogHandle: dialog handle / 0

DialogLoad: dialog handle / 0

DialogSave: True / False

DialogDelete: True / False

DoesDialogExist: True / False

DialogSetProperties: True/ False

DialogControlUpdate: True/ False

DialogControlQuery: True / False

DialogAddListItem: item index / -1

All the following commands return the control name if successful, an empty string ("") if not:

DialogAddBitmap

DialogAddCheckBox

DialogAddColorWheel

DialogAddComboBox

DialogAddControl

DialogAddCounter

DialogAddDate

DialogAddEditBox

DialogAddFileNameBox

DialogAddFrame

DialogAddGroupBox

DialogAddHLine

DialogAddHotSpot

DialogAddIcon

DialogAddListBox

DialogAddPopupButton

DialogAddProgress

DialogAddPushButton

DialogAddRadioButton

DialogAddScrollBar

DialogAddText

DialogAddViewer

DialogAddVLine

Syntax

string := MacroDialogResult

MacroInfo

Purpose

Return information about the system, the state of a macro, or 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 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.

Syntax

any := MacroInfo (InfoItem: enumeration; [CallLevel: enumeration or numeric]; {[ItemData: any]})

Parameters

InfoItem

enumeration Specify an InfoItem (the data type returned is in italics).

System Information:

ComputerName!

string Named assigned to the computer.

UserName!

string Name of currently logged in user.

WindowsDirectory!

string Windows directory path.

SystemDirectory!

string Windows System directory path.

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.

ErrorText!

string Additional error text associated with the last error.

AbortingTokenName!

string Name of the product command token (if any) that caused the last error.

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.

SourceLine!

string Source line if available for the specified CallLevel (source is available for macros compiled with debug).

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.

ExitOn!

Return the exit handler state. Equivalent to ExitHandlerState() = ExitHandlerState.On!

ExitSetup!

Return whether an exit hanlder has been established. Equivalent to the statement OnExit() != ""

ExitCall!

Return True if an exit handler has been established.

ExitHandler!

Return the label of the established exit handler. Equivalent to OnExit()

ErrorOn!

boolean State 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/repeating) 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

Purpose

Get the mantissa portion of a numeric value.

vMntsa := MantissaPart(3.2e18)

Result: vMntsa = 3.2

Return Value

Mantissa portioin of a numeric value.

Syntax

numeric := MantissaPart (Value: numeric)

Parameters

Value

numeric A fractional number (return the mantissa part of).

Max

Purpose

Get the maximum value of a list of values.

Return Value

Maximum value of a list of values.

Syntax

numeric := Max ({Value: numeric})

Parameters

Value

numeric The list of values. Separate multiple values with a semicolon.

Menu

Purpose

Display 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.

Example

Appendix A: 8002

Syntax

Menu (<MenuPick> variable; <MnemonicType> enumeration; [<HorizontalPosition> numeric]; [<VerticalPosition> numeric]; {<MenuChoice> string})

Parameters

variable A number is returned in this variable, whether numbers or letters are used to reference menu items (see the 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.

enumeration Determine whether a letter or number is displayed to the left of a menu item.

Digit!

Numbers (1-9)

Letter!

Alphabetic characters (A-Z)

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.

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

Purpose

Display 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.

Example

Appendix A: 8002

Syntax

MenuList (<VariableName> variable; {<MenuChoice> string}; [<Title> string]; [<HorizontalPosition> numeric]; [<VerticalPosition> numeric])

Parameters

variable A number is returned in this variable, whether numbers or letters are used to reference menu items (see the 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"}; "Title")

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.

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.

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

Purpose

Display a message box.

Provide a limited set of buttons and icons, and an option to include up to 10 different parameter strings in the message.

Example

Appendix A: 8011

Return Value

The control value of the button that dismisses the message box is returned in this variable. 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.

Syntax

enumeration := MessageBox ([Status: variable]; [Caption: string]; Message: string; [Style: enumeration]; {[ParameterData: string]})

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 the 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:

HdReturn = NToC(0F90Ah)

MessageBox(vAns; "Title"; "First line" + HdReturn + HdReturn + "Second line"; IconInformation!)

Style

enumeration (optional) The 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)

IconWarning!

(Exclamation point in a yellow circle)

IconError!

(Stop sign in a red 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

Purpose

Get the minimum value of a list of values.Macro Com Title = Return Value

Minimum value of a list of values.

Syntax

numeric := Min ({Value: numeric})

Parameters

Value

numeric The list of values. Separate multiple values with a semicolon.

MMPlay

Purpose

Play a sound file.

Play 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.

Example

Appendix A: 8025

Return Value

A handle that can be passed to MMStopPlay.

Syntax

numeric := MMPlay (Filename: string; [Options: enumeration])

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

Purpose

Speak an ASCII file or ASCII text.

Example

Appendix A: 8026

Syntax

MMSpeak (String: string)

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

Purpose

Speak 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.

Example

Appendix A: 8026

Syntax

MMSpeakClipboard ()

MMStopPlay

Purpose

Stop a multimedia file started with MMPlay, with the DontWait! option set. With the Wait! option set, MMStopPlay has no effect.

Syntax

MMStopPlay (Handle: numeric)

Parameter

Handle

numeric Returned by MMPlay.

MMStopSpeech

Purpose

Stop 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.

Example

Appendix A: 8026

Syntax

MMStopSpeech ()

MOD

Purpose

Operator. Precedence level 3. See Arithmetic Operators in Chapter 4: Expressions.

Return Value

Return the integer remainder of the quotient of two numbers.

Syntax

numeric := numeric MOD numeric