Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager

This chapter describes how you can use the Help Manager to provide your users with Balloon Help online assistance--information that describes the actions, behaviors, or properties of your application's features. When the user turns on Balloon Help assistance, the Help Manager displays small help balloons as the user moves the cursor over areas such as controls, menus, and rectangular areas in your windows. Help balloons are rounded-rectangle windows that contain explanatory information for the user. (With tips pointing at the objects they annotate, help balloons look like the balloons used for dialog in comic strips.) You provide help messages in the form of descriptive text or pictures that appear inside help balloons. Your help messages should be short and pertinent to the object over which the cursor is located.

For example, when a user moves the cursor to a menu command, a help balloon should point to that command and explain its purpose. The help balloon remains displayed until the user moves the cursor away.

The user turns on Balloon Help online assistance for all applications by choosing the Show Balloons command from the Help menu. All normally available features of your application are still active when Balloon Help is enabled. The help balloons only provide information; the actions that the user performs by pressing the mouse button still take effect as they normally would.

The Help Manager is available in System 7. Use the Gestalt function to determine whether the Help Manager is present.

Read this chapter if you want to provide help balloons for your application, desk accessory, control panel, Chooser extension, or other software that interacts with the user. If you offer an additional help facility for your users, you should give users access to your information through the Help menu. This chapter explains how you can add your own menu items to the Help menu to provide one convenient and consistent place for users to look for help information.

You can provide help balloons for your menus, dialog boxes, alert boxes, and non-document icons by simply adding resources to your resource file. To provide help for the content area of windows, you can use either resources or Help Manager routines. Both methods are described in this chapter.

You typically provide help balloons for your application by creating resources--such as the 'hmnu' resource, which the Help Manager uses when displaying help balloons for your menu items. In the 'hmnu' resource, you specify help balloons for menu titles and menu items in their enabled and disabled (that is, dimmed) states. Menus are described in the chapter "Menu Manager" in Inside Macintosh: Macintosh Toolbox Essentials.

To provide help balloons for alert boxes and dialog boxes, you typically create an 'hdlg' resource that specifies help balloons for the various items identified in the item list ('DITL') resource for the alert box or dialog box. If the items include any controls, such as simple buttons, checkboxes, or complex multipart controls, you specify help according to the control's state--active or inactive (that is, dimmed), and checked or not checked (if applicable). For every item that is not a control, you can provide different help balloons depending on whether the item is enabled or disabled--that is, depending on whether you asked the Dialog Manager to return information regarding events in that item. Dialog boxes and alert boxes are described in the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials; controls are described in the chapter "Control Manager" in Inside Macintosh: Macintosh Toolbox Essentials.

Depending on whether your windows are static or whether they contain changing or scrolling information, you use Help Manager resources or Help Manager routines to provide the content areas of your windows with help balloons. To provide help balloons for the static windows of your application without modifying its code, you create a resource of type 'hwin' and another resource of type 'hrct' or of type 'hdlg'. The 'hwin' resource identifies windows by the titles or the windowKind values in their window records. To provide help balloons for portions of windows that change or scroll, you must identify, track, and update those portions within your windows, and then use the Help Manager function HMShowBalloon to display help balloons for those portions. Windows are described in the chapter "Window Manager" in Inside Macintosh: Macintosh Toolbox Essentials.

This chapter provides a brief description of how the Help Manager displays help balloons. It provides information on the default help balloons and then discusses how to

• use text or a picture for the help message inside a balloon
• create resources for help balloons for menus, dialog boxes, and alert boxes
• create resources for help balloons for windows
• override the default help balloons provided by system software
• add your own menu items to the Help menu
• write your own balloon definition function

---

Chapter Contents

About the Help Manager

How the Help Manager Displays Balloons

Default Help Balloons for Menus, Windows, and Icons

About BalloonWriter

Using the Help Manager

Providing Text or Pictures for Help Balloons

Defining Help Messages

Using Clear, Concise Phrases

Using Active Constructions

Using Parallel Structure

Offering Hints

Using Consistent Terminology

Defining the Help Balloon Position

Specifying the Format for Help Messages

Specifying Options in Help Resources

Providing Help Balloons for Menus

Specifying Header Information for the 'hmnu' Resource

Specifying Help for Menu Items Missing From the Resource

Specifying Help for Menu Titles and for Items Dimmed by System Software

Specifying Help for Menu Items

Specifying Help for a Changing Menu Item

Specifying Resources by Item Name

Providing Help Balloons for Menus You Disable for Dialog Boxes

Providing Help Balloons for Items in Dialog Boxes and Alert Boxes

Specifying Header Information for the 'hdlg' Resource

Specifying Missing-Item Information

Specifying Help for Items in an Alert or Dialog Box

Adding a Help Item to an Item List Resource

Using a Help Item Versus Using an 'hwin' Resource

Providing Help Balloons for Window Content

Providing Help Balloons for Static Windows

Specifying Header Information for the 'hrct' Resource

Specifying Help for Rectangles in Windows

Associating Help Resources With Static Windows

Specifying Header Information for the 'hwin' Resource

Specifying 'hdlg' or 'hrct' Resources in the 'hwin' Resource

Providing Help Balloons for Dynamic Windows

Overriding Help Balloons for Non-Document Icons

Specifying Header Information for the 'hfdr' Resource

Specifying Help for an Icon

Overriding Other Default Help Balloons

Specifying Header Information for the 'hovr' Resource

Overriding Default Help

Adding Menu Items to the Help Menu

Writing Your Own Balloon Definition Function

Help Manager Reference

Data Structures

The Help Message Record

The Help Manager String List Record

Help Manager Routines

Determining Balloon Help Status

Displaying and Removing Help Balloons

Enabling and Disabling Balloon Help Assistance

Adding Items to the Help Menu

Getting and Setting the Font Name and Size

Setting and Getting Information for Help Resources

Determining the Size of a Help Balloon

Getting the Message of a Help Balloon

Application-Defined Routines

Resources

The Menu Help Resource

The Dialog-Item Help Resource

The Rectangle Help Resource

The Window Help Resource

The Finder Icon Help Resource

The Default Help Override Resource

Summary of the Help Manager

Pascal Summary

Constants

Data Types

Help Manager Routines

Application-Defined Routines

C Summary

Constants

Data Types

Help Manager Routines

Application-Defined Routines

Assembly-Language Summary

Data Structures

Trap Macros

Result Codes