Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager

Using the Help Manager

You can use the Help Manager to provide information to the user that describes the action, behavior, or properties of your application's features. For example, you can create a help balloon for each menu item to describe what it does.

To determine whether the Help Manager is available, use the Gestalt function with
the gestaltHelpMgrAttr selector. Test the bit field indicated by the gestaltHelpMgrPresent constant in the response parameter. If the bit is set, then the Help Manager is present.

CONST gestaltHelpMgrPresent   = 0;     {if this bit is set, then }
                                       { Help Manager is present}

The Help Manager is initialized at startup time. The user controls whether help is enabled by choosing the Show Balloons or Hide Balloons command from the Help menu.

The Help menu is specific to each application, just as the File and Edit menus are specific to each application. The Help menu items that are defined by the Help Manager are common to all applications, but you can add your own menu items for help-related information.

The Help Manager automatically appends the Help menu when your application inserts an Apple menu into its menu bar. The Menu Manager automatically appends the Help menu to the right of all your menus and to the left of the Application menu (and to the left of the Keyboard menu if a non-Roman script system is installed).

You can create help balloons for the menus, dialog boxes, alert boxes, or content area of windows belonging to your application. You can also override some of the default help balloons--such as the default help balloon for the title bar of a window.

You can specify the help message by using plain text, styled text, or pictures. Although you should always strive for brevity in your help messages, plain text strings can contain up to 255 characters. Styled text can contain up to 32 KB of information. The Help Manager determines the actual size of the help balloon and, for text strings, uses TextEdit to determine word breaks and line breaks.

The Help Manager automatically tracks the cursor and generates help balloons defined in standard help resources. Your application can also track the cursor and use Help Manager routines to display and remove help balloons.

---

Subtopics

Providing Text or Pictures for Help Balloons

Specifying the Format for Help Messages

Specifying Options in Help Resources

Providing Help Balloons for Menus

Providing Help Balloons for Items in Dialog Boxes and Alert Boxes

Providing Help Balloons for Window Content

Providing Help Balloons for Static Windows

Associating Help Resources With Static Windows

Providing Help Balloons for Dynamic Windows

Overriding Help Balloons for Non-Document Icons

Overriding Other Default Help Balloons

Adding Menu Items to the Help Menu

Writing Your Own Balloon Definition Function