
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:
- Window uses DLOG/DITL resources - make sure that the dialog
that you're trying to coach uses DLOG/DITL resources. Modal dialogs (identified
by a thin purple box that surrounds the window on all sides and no title
bar) always do, but it's harder to tell for other types of dialogs. The
only sure way to know is to use a resource editor (such as ResEdit) to open
the application, then look for the dialog in the DLOG resources.
- Target App required - unlike other coach marks, you must specify
the target application's signature and cannot use constant FRONT. If you're
working with Finder dialogs or control panels, the signature is 'MACS'.
You can find the signature of other applications by opening them with ResEdit.
- Window name optional - even if a window name appears on the
dialog, it's typically safer to use the constant FRONTWINDOW instead.
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'.
- Browse the application file with ResEdit or Resorcerer to find the
'hrct' or 'hdlg' resources.
- 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:
- use FRONTWINDOW as the targetWindow parameter and FRONT as the targetApp
parameter to coach the frontmost window in any application. This will usually
coach any floating palettes in the application, but it doesn't coach true
system windows (like Apple Guide's windows).
- use FRONTWINDOW as the targetWindow parameter and your application's
signature as the targetApp parameter to coach the frontmost window in the
app.
- use "window name" as the target window parameter to coach
a specific window in an application.
- use AppleScript (if your application supports it) to find the coordinates
of some window that doesn't fit either of these two criteria.
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:
- the menu title (and this menu has no title)
OR
- the menu number (counted from the left). Because so many utilities
(disk compression, faxing, and so on) add menus to the menubar, it's difficult
to use the menu number reliably.
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:
- Menu 0 = Apple menu
- Menu 1 = File menu
- Menu 2 = Edit menu
- and so on ...
© 1997, guideWorks, LLC -- Last updated: 970325 GPB