Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager / Using the Help Manager

Overriding Other Default Help Balloons

The Help Manager also provides default help balloons for the title bar and the close and zoom boxes of an active window, for the windows of inactive applications, for inactive windows of an active application, and for the area outside a modal dialog box.

Apple Computer, Inc., has researched and tested these help messages to ensure that they are as effective as possible for users. Normally, you shouldn't need to override them. However, you can override one or more of these defaults if you feel you absolutely must by creating a resource of type 'hovr'.

Using an 'hovr' resource sets the default help balloons for your application only. It does not affect the default help balloons used by other applications.

An 'hovr' resource consists of exactly nine components: a header component, a missing-items component, and seven components that specify help messages for seven standard user interface features.

Component	Element
Header	Help Manager version
	Options
	Balloon definition function
	Variation code
Missing-items help	Identifier for help message
	Help message for items missing from this resource or lacking help messages
Title bar help	Identifier for help message
	Help message for title bar of active window
Reserved	HMSkipItem identifier (always used here)
	No help message; reserved for future use
Close box help	Identifier for help message
	Help message for close box of active window
Zoom box help	Identifier for help message
	Help message for zoom box of active window
Help for active application's inactive windows	Identifier for help message
	Help message for inactive window of active application
Help for inactive application's windows	Identifier for help message
	Help message for window of inactive application
Help for area outside a modal dialog box or alert box	Identifier for help message
	Help message for area outside a modal dialog box or an alert box

Specifying Header Information for the 'hovr' Resource

As with the other help resources, specify the HelpMgrVersion constant for the first element of the header component of the 'hovr' 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 variation code (both typically 0) in the third and fourth elements, respectively, of the header component. (The balloon definition function and variation code are described in detail earlier in "Specifying Header Information for the 'hmnu' Resource" on page 3-29.)

Overriding Default Help

In the first element of the missing-items component, supply an identifier. As with the other help resources, use one of these identifiers: HMStringItem, HMSTRResItem, HMStringResItem, HMPictItem, HMTEResItem, or HMSkipItem. These identifiers are described in "Specifying the Format for Help Messages" on page 3-21. For the second element, supply either a text string for the help message or the resource ID of the resource that contains the help message.

The Help Manager expects the remaining components of an 'hovr' resource to be listed in the order previously shown. If you specify fewer than seven components in the Rez input file, the Help Manager adds components to the end of your list until there are seven. Each component that the Help Manager adds uses the message specified in the missing-items component. The Help Manager also uses the missing-items component's help message if the Rez input file specifies an empty string or a resource ID of 0 for any other component's help message.

For the first element of each of the remaining components, specify one of these identifiers: HMStringItem, HMSTRResItem, HMStringResItem, HMPictItem, HMTEResItem, or HMSkipItem. To use any of the default help balloons, use the HMSkipItem identifier. For the second element of each of the remaining components, supply either a text string for the help message or the resource ID of the resource that contains the help message.

Listing 3-18 shows a resource of type 'hovr' that overrides all of the default help balloons.

Listing 3-18 Rez input for an 'hovr' resource

resource 'hovr' (1000) {
   /*header component*/
   HelpMgrVersion,
   hmDefaultOptions, /*options*/
   0,       /*the balloon definition ID*/
   0,       /*variation code*/
   /*missing-items component*/
   HMStringItem {    /*missing items in case this resource is */
                     /* short of components*/
      "Missing override message"
      },
   {
   /*remaining components: for overriding default messages*/
      HMSkipItem {         /*title bar help*/
         /*HMSkipItem means use default help balloon for this element*/
      },
      HMSkipItem {      /*reserved; always specify HMSkipItem*/
      },
      HMStringItem {    /*close box help*/
         ""             /*empty string means use missing-items help*/
      },
      HMStringItem {    /*zoom box help*/
         "Get this message if in Zoom In or Zoom Out box."
      },
      HMStringItem {    /*help for active app's inactive window*/
         "Get this message if in inactive window of "
         "active application."
      },
      HMStringItem {    /*help for inactive app's window*/
         "Get this message if in window of inactive application."
      },
      HMStringItem {    /*help when outside of modal dialog box*/
         "Get this message if outside modal dialog box."
      }
   }
};