All Databases Inside Mac - Basic Toolbox

Providing Help Balloons for Menus

If your application uses the standard menu definition procedure, you

will find that it is easier to provide help balloons for menus than for

any of your other interface elements. This section is relatively lengthy

compared to the sections describing dialog boxes, alert boxes, and

windows only because it explains in greater detail much of the work

you will also perform while providing help balloons for those

elements.

This section assumes that your application uses the standard menu

definition procedure. If your application uses its own menu definition

procedure, use Help Manager routines to display and remove help

balloons. See Displaying and Removing Help Balloons . Even if

you use these routines, you should read this section so that your

balloons emulate the behavior that the Help Manager provides for

standard menus.

To create help balloons for a menu-pull-down, pop-up, or

hierarchical-that uses the standard menu definition procedure, create

a resource of type 'hmnu'. You can provide help balloons for the menu

title and for each individual menu item.

The Help Manager can display different help balloons for the

various states of a menu item. Each menu item can have up to four help

balloons associated with it, one for each state:

• enabled

• disabled (that is, dimmed for the user)

• enabled and checked

• enabled and marked (that is, marked by a symbol other than a

checkmark-for example, a bullet or a diamond)

For example, you can define a help balloon that the Help Manager

displays when the Cut command is enabled and another help balloon for

display when the Cut command is dimmed. Remember that the help

balloon that you provide for a dimmed menu item should explain why it

is not currently available or, if more appropriate, how to make it

available.

Note: Although enabled and disabled are the commands you

use in a resource file to display or to dim menus and menu

items, you should not use these terms in your help balloons or

user guides. Rather, use the terms menus, menu commands,

or menu items for those that are enabled, and use the terms

not available or dimmed to distinguish those that have been

disabled.

When your application calls the MenuSelect or MenuKey function,

the

Menu Manager tracks the cursor, highlights enabled menu items,

and pulls down any additional hierarchical or pop-up menus as the

user moves the mouse. As the user drags the cursor across or through a

menu, the Menu Manager uses the Help Manager to display any

help balloons associated with the current state of the menu title or

menu item.

The Figure below shows different help balloons for two instances of a

menu, one with the Cut command dimmed, the other with the Cut

command enabled.

Help balloons for different states of the Cut command

You do not specify hot rectangles or tip locations for menus. The

rectangles defined by the Menu Manager for menu titles and menu

items are used for the hot rectangles. The Help Manager initially

tries to draw a help balloon for a menu item using variation code 0

(shown in the Figure below) with the tip placed eight pixels inside the

right edge and halfway between the top and bottom edges of the menu

item's rectangle. If the balloon's initial position lies wholly or

partially off screen, the Help Manager tries to redraw the balloon by

moving its tip to the left edge of the item rectangle and using variation

code 3. The Help Manager uses variation codes 1 and 2 in its

attempts to draw help balloons for menu titles. The Help Manager

never moves the tip for menu titles; instead, the tip is always located

just below the bottom of the menu bar at the midpoint of the menu

title's text.

The resource ID of each 'hmnu' resource should match the

corresponding menu ID. For example, to provide help balloons for a

menu with ID 130, create an 'hmnu' resource with resource ID 130.

The 'hmnu' resource contains four distinct components: the header,

the help balloon content for any menu items missing from or

unspecified in the rest of the 'hmnu' resource, the help balloon content

for the menu title, and the help balloon content for a variable number

of menu items.

Here is the general format of an 'hmnu' resource.

Menu help

Component resource element

Header Help Manager version

Options

Balloon definition function

Variation code

Missing items Identifier for help balloon content

Balloon content for missing enabled items

Balloon content for missing dimmed items

Balloon content for missing enabled-and-

checked items

Referenced by (11):