Coach Marks
How do I ... Why ... Why can't I ...

Why don't my Dialog Item coaches work?

Dialog Item coaches have some special requirements that must be met for them to work properly: Even if you follow all the rules, Dialog Item coaches don't always work. There's a bug that affects the reliability of Dialog Item coaches in Apple Guide 1.2.5, so sometimes they work, sometimes they don't.

If you cannot get a Dialog Item coach to work, try using a Window coach instead. You can coach individual items by specifying a rectangle within the window - the only real loss is that you must specify coordinates rather than relying on the item number.

Warning - Coach Mark Assistant sometimes gives inaccurate results when testing Dialog Item coaches.

A good strategy for defining Dialog Item coaches is to build a single test sequence that helps you discover which DialogIDs coach each item in the dialog. The test sequences would include a series of panels, each containing a coach mark definition for successive DialogID numbers. As you move through the panels of test sequence, you can observe which item is coached for each Dialog ID.

How do I find the balloon IDs to use in item coach definitions?

Apple Guide can use the balloon hot rect resources ('hrct') or dialog-item help resources ('hdlg') to define coach mark rectangles. These resources are linked to the balloon help messages in a window help resource ('hwin').

Check out pages 3-148 and 3-140 in "Inside Macintosh: More Macintosh Toolbox" to get more information about 'hrct' and 'hdlg'.
  1. Browse the application file with ResEdit or Resorcerer to find the 'hrct' or 'hdlg' resources.
  2. Use the 'hrct' or 'hdlg' ID number for the BalloonID in the coach mark definition.

How do I get a coachmark to appear on ALL windows except floating ones?

Your options regarding the window coach marks are: You can also use the context checking conditions to make sure that a specific window (whose name equals or name contains a string) is frontmost or open.

Only one coach mark can appear on the screen at a time, so there's no way that I know of to coach mark more than one window at once.

How do I coach an item in the Guide/Help menu?

You cannot use {Define Menu Coach> to coach an item in the Guide/Help menu because you need to specify: An alternative strategy - use <Define Window Coach> to draw a coach mark at the location of the Guide/Help menu icon. This doesn't let you coach an item within the menu, but it's better than no coach at all. The Guide/Help menu almost always appears at the same location relative to the upper right corner of the desktop.
<Define Window Coach> "Guide Menu", FRONT, REDCIRCLE, DESKTOP, RECT(5, -61, 15, -41), TOPRIGHT

And for the process menu:
<Define Window Coach> "Process Menu", FRONT, REDCIRCLE, DESKTOP, RECT(5, -35, 15, -16), TOPRIGHT

How do I stop coach marks from drawing in the wrong place while navigating backward through a sequence?

When users navigate backward through the a sequence, they walk back through a history list of panels that have been previously displayed. They see exactly the same panels that originally appeared as they moved forward, and Apple Guide attempts to redraw the coach marks for each panel.

What makes navigating backward tricky is that the context checking rules that typically Make Sure that the correct window is being displayed are ignored. Context checking is suspended when users move backward and doesn't resume until the user starts navigating forward again.

The only way to keep coach marks from drawing in inappropriate places on the backward pass is to target each coach marks to a specific application and a specific window. If the window can't be found (because it isn't open), the coach mark won't be drawn.

For example, use:

<DEFINE WINDOW COACH> "Text Field" ,'APP?', RedCircle, "MyWindowName", Rect(216,240,236,300), TOPLEFT
not:
"Text Field", FRONT, RedCircle, FRONTWINDOW, Rect(216,240,236,300),TOPLEFT

Why can't I coach items in Microsoft Word?

Some informal testing reveals that Apple Guide coach marks don't appear in Microsoft Word 5.1a, even when they are defined properly. Interestingly, coach marks do appear in Microsoft Excel 4.0 - so much for the common code base... go Microsoft! If anyone has tested this with Word 6.0, please send a message. I'd like to know if Microsoft has cleaned up this bug in the latest release. Thanks! Word 6.0 update (Thanks to Dave Thornley!): I have had a quick go and got a coach mark to appear, albeit in a completely different place to where I expected it to. This seems to have something to do with the FRONTWINDOW parameter. In Word 6.0 the tool bar seems to have grabbed this characteristic so coach marks using this appear way out of place.

Why don't my coached menu items uncoach when done?

When you use a RED UNDERLINE coach mark to highlight a menu item, the coach mark may stick around after you're done coaching. Sometimes the red color remains, sometimes the underline remains, sometimes both remain, and sometimes the item returns to normal.

The behavior is determined by how the application you're coaching updates the menu items. Apple Guide doesn't automatically update the menu for the application after it's coached. Managed this within the application by calling HiliteMenu(0) after calling MenuSelect or MenuKey. I recommend that you always include HiliteMenu(0) at the very end of your "DoMenuCommand" function. It does no harm and will insure that the menu items are uncoached.

How do I define menu coaches using numbers rather than menu names?

You can define a menu coach using a menu number rather than the menu name as fourth parameter of the command. For example, to coach the Open item in the File menu in the Finder, you can use either of these forms:
"File:Open", 'MACS', REDCIRCLE, "File", "Open", RED, UNDERLINE "File:Open", 'MACS', REDCIRCLE, 1, 2, RED, UNDERLINE
Warning: There's an error on page 10-106 of Apple Guide Complete in the description of the targetMenu parameter. The correct numbering scheme is:
© 1997, guideWorks, LLC -- Last updated: 970325 GPB