Legacy Document

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

Chapter 10 - Guide Script Command Reference / Guide Script Command Descriptions

/ Creating Coachmarks

<Define Item Coach>

You can use the <Define Item Coach> command to define a coachmark for an item in a dialog box or for some other interface element that can be described by a help balloon rectangle.

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

coachMarkName

A text string specifying the name of this item coach.

targetApp

A four-character sequence specifying the signature of the target application or the constant FRONT to specify the frontmost application. In general, you should always specify the signature of the target application to ensure that the coachmark is directed to the correct application. This parameter is optional. If you omit this parameter, Apple Guide uses FRONT as the default.

coachStyle

A value indicating the coach style to use for the item. You specify how Apple Guide should draw the coachmark for the item using a constant or red arrow specifier:

Constant

REDCIRCLE, REDUNDERLINE, or GREENX

Red arrow specifier
RedArrow(start, end)
Use the RedArrow function to draw a red arrow beginning at a location specified by start and ending at a location specified by end. The values for start and end are integers 1 through 8, where each value indicates a general location in a rectangle:

Location	Value
Top left	1
Top center	2
Top right	3
Middle right	4
Bottom right	5
Bottom center	6
Bottom left	7
Middle left	8

These values indicate the eight possible points for the start and end of the arrow. These locations can be interpreted as:

1 2 3

8 4

7 6 5

The coachStyle parameter is optional. If you omit this parameter, Apple Guide uses REDCIRCLE as the default.

targetWindow

The window associated with this coachmark. For dialog items, you can specify the window's title, the constant FRONTWINDOW, or the constant DESKTOP. For items associated with help-balloon rectangles, if you provide this parameter you must specify the constant FRONTWINDOW. This parameter is optional. If you omit this parameter, Apple Guide uses FRONTWINDOW as the default.

targetItem

An item specifier for an item in a dialog box or an ID specifier for a help balloon. You must provide the targetItem parameter.

To specify the rectangle of an item in a dialog box, use the built-in function DialogID(itemNo).To specify the rectangle of an item that has a help balloon, use the built-in function BalloonID(balloonNo).

itemRectangle

A subrectangle, relative to the upper-left of the item's rectangle, that further specifies the area in which the coachmark should be drawn. This parameter is optional. If you omit this parameter, Apple Guide draws the coachmark according to the item's rectangle.

DESCRIPTION

The <Define Item Coach> command defines an item coach for an item in a dialog box or an interface element in a window (or dialog box) that already has a help balloon associated with it. You associate an item coach with a particular panel using the <Coach Mark> command. When Apple Guide opens a panel that includes a <Coach Mark> command naming a defined item coach, Apple Guide uses the specified coach style to draw a coachmark for the specified item.

To provide a coachmark for an item in a dialog box, use the DialogID function to specify the item's item number in the targetItem parameter. (You can determine an item's item number using a resource editor, such as ResEdit.)

To provide a coachmark for an element in a window or dialog box that already has a help balloon associated with it, use the BalloonID function to specify the index number of the help balloon (corresponding to its position in the help resource) in the targetItem parameter.

Both an item in a dialog box and a help balloon for an interface element have rectangles that define the item or element's location. Usually this rectangle should suffice as the rectangle that defines where the coachmark should be drawn. However, you can further specify the rectangle in which Apple Guide draws the coachmark by providing information in the itemRectangle parameter.

EXAMPLES

#define an item coach for item (item no.7) in a dialog box
<Define Item Coach> "SpellCheckCoach", 'WAVE', REDCIRCLE,\xAC
                   "Spell Check Options", DialogID(7)
<Define Panel> "spell-checking dialog box"
   <Coach Mark> "SpellCheckCoach"
   To spell-check a document and ignore valley slang, 
   click the Ignore valley slang checkbox.
<End Panel> 
#define an item coach based on a help balloon
<Define Item Coach> "page number balloon", 'WAVE', \xAC
                   REDCIRCLE, FRONTWINDOW, BalloonID(8)

#define another item coach based on a help balloon
<Define Item Coach> "current style balloon", 'WAVE', \xAC
                     RedArrow(1,7), \xAC
                     FRONTWINDOW, BalloonID(4)

#define an item coach for item (item no.5) in a dialog box
# and specify a subrectangle for the coachmark
<Define Item Coach> "SlangCheckCoach", 'WAVE', REDCIRCLE,\xAC
                   "Spell Check Options", DialogID(5), \xAC
                    Rect(20,20,70,70)

SEE ALSO

For information on the <Coach Mark> command, see page 10-118. For information on help resources, see the chapter "Help Manager" in Inside Macintosh: More Macintosh Toolbox.