Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager / Using the Help Manager

Specifying the Format for Help Messages

You specify the format for your help messages as text strings within help resources, as text strings within 'STR ' resources, as lists of text strings within 'STR#' resources, as styled text using 'TEXT' and 'styl' resources, or as pictures described in 'PICT' resources.

Later sections in this chapter describe all the help resources in detail. Common to all
the help resources are the following identifiers, by which you identify the format of your help messages.

Identifier	Help message format
HMStringItem	A text string (a Pascal string stored in the help resource)
HMPictItem	A picture (stored in a 'PICT' resource)
HMStringResItem	A text string (stored in a list of strings as an 'STR#' resource)
HMTEResItem	Styled text (stored in both a 'TEXT' and an 'styl' resource)
HMSTRResItem	A text string (stored in an 'STR ' resource)
HMSkipItem	No help message--skip this item

You specify the identifiers within the help resources; the Help Manager reads these identifiers to determine where and how your help messages are stored. You can use the HMStringItem identifier to store Pascal strings directly in a help resource. However, you can make it much easier to localize your product by storing your help messages in separate resources--namely, in 'STR#', 'PICT', 'STR ', and 'TEXT' resources--that can be modified by nonprogrammers using tools like BalloonWriter and the ResEdit resource editor.

To display a diagram or illustration in 'PICT' format, use the HMPictItem identifier. You provide a help message by specifying the resource ID of the 'PICT' resource that contains the diagram or illustration, and the Help Manager displays the picture in a help balloon.

To display a text string stored in a string list ('STR#') resource, use the HMStringResItem identifier. You provide a help message by specifying two items in your help resource: the resource ID of an 'STR#' resource, and the index to a particular text string from within that list. For more information on these items, see "Providing Help Balloons for Menus" beginning on page 3-24.

To display styled text, use the HMTEResItem identifier. You provide a help message by specifying a resource ID that is common to both a style scrap ('styl') resource and a 'TEXT' resource, and the Help Manager employs TextEdit routines to display your text with your prescribed styles. For example, you might create a 'TEXT' resource with resource ID 1000 that contains the words "Displays your text in boldface print" and a 'styl' resource with resource ID 1000 that applies boldface style to the message. (See the chapter "TextEdit" in Inside Macintosh: Text for a description of the style scrap.)

To display text from a simple text string ('STR ') resource, use the HMSTRResItem identifier. You provide a help message by specifying the resource ID of an 'STR ' resource, and the Help Manager displays the text from that resource in a help balloon. With 'STR ' resources, each text string must be stored in a separate resource. It is usually more convenient to group related help messages in a single 'STR#' resource and use the HMStringResItem identifier as previously described.

You can use the HMSkipItem identifier for items for which you don't want to provide a help balloon. For example, you specify HMSkipItem for the divider lines that appear in menus. (Divider lines cannot have help balloons.)