Inside Macintosh: Apple Guide Complete / Part 4 - Scripting Guide Files

Chapter 10 - Guide Script Command Reference

Guide Script Command Syntax

A Guide Script command line begins with a command, comment, or text that is part of a text block or panel definition, and is terminated by a carriage return. Any number of blank spaces or tabs can precede a command or comment.

Guide Script commands are named keywords that are enclosed in angle brackets (< >). Command keywords are case-insensitive, although headline-style capitalization is used in this book. Most Guide Script commands are followed by a series of parameters, separated by commas. Parameters must be included on the same line as the Guide Script command; however, with some word processors you can use a soft return (Option-Return) to break parameters across lines when necessary. In this chapter, the character \xAC is used to indicate a line that does not contain a hard return; you must either wrap these lines or use a soft return, depending on your word processor. You can also include any number of spaces or tabs between parameters to make command lines easier to read.

This chapter describes Guide Script commands in this format:

<Command Name> parameter1, parameter2 [, optionalParameter1]

Here's a specific example:

<Help Menu> itemString, helpType [, helpCmdKey]

In this example, the command <Help Menu> indicates the Guide Script command. (You don't have to use this sequence of uppercase and lowercase characters. For example, you can use <help menu> if you prefer.) Parameters are shown in italicized words following the command name. Brackets ( [] ) are used to show optional parameters. In this example, itemString and helpType are required parameters, and helpCmdKey is an optional parameter.

You can omit optional parameters. If you do so and the optional parameter is followed by another parameter that you do specify, then you must include a comma for each parameter that you omit. For example:

<Define Item Coach> coachMarkName [, targetApp] [, coachStyle]
                     [, targetWindow] , targetItem
                     [, itemRectangle] 

For the <Define Item Coach> command just shown, you must specify the coachMarkName parameter and targetItem parameter, but all other parameters are optional. To specify the coachMarkName and coachStyle and targetItem parameters (omitting the targetApp, targetWindow, and itemRectangle parameters), you could specify the command in this format:

<Define Item Coach> "coachName",, REDCIRCLE,,DialogID(2)

Parameters are one of the following types:

• Strings. Any string of characters enclosed by straight double quotes (" "). Curly double quotes ( " ") are not valid as string delimiters; they are considered part of the text string if used. To include a line feed in a string, use the carriage return character between the string delimiters. Do not specify an empty string for a parameter; instead, specify at least one blank space in the string, such as " ".
• Constants. Values represented by constant names that are defined by Guide Maker for a particular parameter. For example, LEFT, CENTER, RIGHT, TRUE, or FALSE. All Guide Script constants are defined as single words (no spaces), and are case insensitive (for example, LEFT, Left, and left are all valid constants).
• Four-character values (also sometimes called OSType or ResType). A four-character value must be enclosed by straight single quotes (' '). For example, 'MACS', 'WAVE'.
• Numbers. Short, long, or unsigned integers. Each parameter description gives information on the specific type. You can specify numbers using either decimal or hexadecimal form (precede hexadecimal numbers by 0x).
• Structures. Groups of related values that are linked together according to a defined Guide Script convention. For example, you can specify a point, rectangle, column location, or RGB color using these conventions:
  Point(x, y); RECT(top, left, bottom, right); Column(top, left, right); and RGBColor(integer, integer, integer). Note that no space is allowed between the name and the first parenthesis.
• Event functions. You can specify event functions in conjunction with the <Standard Button>, <3D Button>, <Define Nav Button>, <On Panel Create>, <On Panel Destroy>, <On Panel Show>, and <On Panel Hide> commands. Guide Maker provides the following built-in event functions: DoScript, GoPanel, LaunchNewSequence, LaunchNewSequenceNewWindow, PlaySound, QuitTopicOops, and StartTopicOops. In addition, you can create your own event functions using the <Define Event> command. When you specify an event function, you must also specify within parentheses all parameters required by that event function.
• Condition functions. You can specify condition functions in conjunction with the <If>, <Skip If>, <Make Sure>, and <Start Making Sure> commands. You define condition functions using the <Define Context Check> command.

You use the # character to indicate that the text that follows, up to the carriage return, should be treated as a comment. You can start a comment at the beginning or at the end of a command line, for example:

#here's a comment
<App Text> "SurfWriter Guide"    #here's another comment

To use the "#" character as the first character on a line of panel text, use "##". To use the "<" character as the first character on a line of panel text use "<<".