Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager / Using the Help Manager

Providing Help Balloons for Static Windows

To provide help balloons for the static windows of your application without modifying its code, create a resource of type 'hwin' (window help) and additional resources of type 'hrct' (rectangle help) or 'hdlg' (dialog-item help). With these resources, the Help Manager automatically tracks the cursor and displays and removes help balloons as the cursor moves into and out of the hot rectangles associated with these resources.

The 'hwin' resource allows you to associate 'hrct' and 'hdlg' resources with your static windows. You use the 'hrct' and 'hdlg' resources to define help balloons for the individual objects within your windows. While the Help Manager uses the display rectangles defined in the item list resource as the hot rectangles for 'hdlg' resources, you can specify your own hot rectangles for alert boxes and dialog boxes and other static windows by using 'hrct' resources.

Note

BalloonWriter gives nonprogrammers an easy, intuitive way to create help balloons for static windows and dialog and alert boxes. BalloonWriter creates 'hdlg', 'hwin', and 'hrct' resources as appropriate and places them in the resource file of your application; BalloonWriter likewise creates and stores 'STR ', 'STR#', and 'TEXT' resources that contain the help messages authored by nonprogramming writers.

You use an 'hrct' resource to specify tip coordinates, hot rectangles, balloon definition functions, variation codes, and help messages for areas within a static window.

As explained in "Providing Help Balloons for Items in Dialog Boxes and Alert Boxes" on page 3-47, you use the 'hdlg' resource to specify the tip, alternate rectangle, and help messages for items in an alert box or dialog box. "Adding a Help Item to an Item List Resource" on page 3-57 describes how to associate either an 'hdlg' or an
'hrct' resource with an alert box or a dialog box by adding an item of type HelpItem to the box's item list resource. This section describes how you can instead treat your dialog boxes or alert boxes as static windows and use an 'hwin' resource instead of HelpItem items to associate 'hdlg' and 'hrct' resources with the boxes.

The 'hwin' resource identifies windows by their titles or by their windowKind values. You can list all of your windows within one 'hwin' resource, or you can create separate 'hwin' resources for your separate windows. (You'll probably find it easier to maintain your window help if you create only one 'hwin' resource, but, as described later in this section, you must create separate 'hwin' resources for windows that require different options. For example, one window may be matched to its 'hwin' resource by a string anywhere in the window's title, and another window may be matched to its 'hwin' resource only by the exact string of the window's title.) An 'hwin' resource contains
the resource ID (or IDs) of one or more 'hrct' or 'hdlg' resources. With an 'hwin' resource, you can use both 'hrct' and 'hdlg' resources for various parts of the same window.

To use an 'hwin' resource, the window's window record must specify either a title
or a windowKind value that adequately distinguishes it from other windows.
Within an 'hwin' resource, you could identify the Verb Tenses window shown in
Figure 3-20 on page 3-67 by its title, and you could identify the palette window
in Figure 3-19 on page 3-65 by its windowKind value.

The chapter "Window Manager" in Inside Macintosh: Macintosh Toolbox Essentials describes the windowKind field of the window record. Note that windowKind values of 0, 1, and 3 through 7 are reserved by system software and that dialog boxes or alert boxes must have a value of 2. Because your dialog boxes and alert boxes must have a windowKind value of 2, you can use this value to define only one 'hwin' resource for all untitled dialog boxes and alert boxes. You may find it difficult--using 'hwin', 'hrct', and 'hdlg' resources alone--to provide help balloons for untitled dialog and alert boxes. However, you can use an 'hwin' resource to associate generic help for the common objects of all your untitled dialog boxes and alert boxes, and you can use the HMSetDialogResID function to provide help for the unique objects among them.
The HMSetDialogResID function is explained on page 3-110.

You describe the tip, a rectangle, and help messages for each object in static windows using either 'hrct' or 'hdlg' resources. As shown here, an 'hrct' resource consists of two types of components: a header component and a hot-rectangle component. You use hot-rectangle components to specify the hot rectangles within the window and the help messages for each hot rectangle. (For a description of 'hdlg' resources, see "Providing Help Balloons for Items in Dialog Boxes and Alert Boxes" beginning on page 3-47.)

Component	Element
Header	Help Manager version
	Options
	Balloon definition function
	Variation code
First hot rectangle	Identifier for help message
	Tip's coordinates
	Hot rectangle coordinates
	Help message for hot rectangle
Next hot rectangle	(Same as for first hot rectangle)
	.
	.
	.
Last hot rectangle	(Same as for first hot rectangle)

Specifying Header Information for the 'hrct' Resource

As with the other help resources, specify the HelpMgrVersion constant for the first element of the header component of the 'hrct' resource. For the second element, specify a constant (normally, hmDefaultOptions) or the sum of several constants' values from the following list. ("Specifying Options in Help Resources" beginning on page 3-22 describes these options.)

CONST hmDefaultOptions     = 0;  {use defaults}
      hmUseSubID           = 1;  {use subrange resource IDs }
                                 { for owned resources}
      hmAbsoluteCoords     = 2;  {ignore coords of window }
                                 { origin and treat upper-left }
                                 { corner of window as 0,0}
      hmSaveBitsNoWindow   = 4;  {don't create window; save }
                                 { bits; no update event}
      hmSaveBitsWindow     = 8;  {save bits behind window }
                                 { and generate update event}

Specify the balloon definition function and the variation code (both typically 0) in the third and fourth elements, respectively, of the header component. (The balloon definition function and the variation code are described in detail in "Specifying Header Information for the 'hmnu' Resource" on page 3-29.)

Specifying Help for Rectangles in Windows

Following the header component, use hot-rectangle components to specify tip coordinates, hot rectangles, and help messages for all the areas in the window that would benefit from having help balloons.

For the first element of each hot-rectangle component, specify the format that the help messages take. As with the other help resources, specify the format using one of these identifiers: HMStringItem, HMSTRResItem, HMStringResItem, HMPictItem, HMTEResItem, or HMSkipItem, described in "Specifying the Format for Help Messages" on page 3-21.

Use the second element of the hot-rectangle component to specify the coordinates (local to the window) of the balloon tip. Use the third element to specify the coordinates
(local to the window) of the hot rectangle. Use the fourth element to specify your help message, as either a text string or a resource ID.

In a hot-rectangle component, you specify the tip, hot rectangle, and help message for every applicable area in the window. As explained in "Adding a Help Item to an Item List Resource" on page 3-57, you can associate an 'hrct' resource with an alert box or a dialog box by adding an item of type HelpItem to the box's item list resource. For windows, you create an 'hwin' resource that contains the resource ID of this 'hrct' resource and that associates the 'hrct' resource with the window. In either case, the Help Manager automatically tracks the cursor and displays and removes help balloons as the user moves the cursor into and out of the hot rectangles defined in this 'hrct' resource.

If you need to supply a help balloon for an area within a larger area that needs a different help balloon, create 'hrct' resources for both the inner and outer areas and specify their areas as hot rectangles. In your resource file, list the 'hrct' resource
for the inner area before the 'hrct' resource for the outer area. Then, when the cursor is in the inner hot rectangle, the Help Manager scans its 'hrct' resource first and displays its help balloon instead of the help balloon for the outer hot rectangle. When the cursor moves from the inner hot rectangle to the outer, the Help Manager removes the inner area's help balloon and displays the balloon for the outer hot rectangle.

As previously explained, you can create an 'hdlg' resource to specify the tips, alternate rectangles, balloon definitions, variation codes, and help messages for items in an item list resource, and you can use an 'hwin' resource to associate that 'hdlg' resource with a dialog box or alert box. When help is enabled and your application calls the Dialog Manager routine ModalDialog, IsDialogEvent, Alert, NoteAlert, CautionAlert, or StopAlert, the Help Manager automatically tracks the cursor and displays and removes help balloons for items specified in the 'hdlg' resource.