All Databases Inside Mac - Basic Toolbox

Help Balloon Display

The Help Manager performs most of the work involved with

rendering help balloons for your application. This section gives an

overview of the facilities that the Help Manager uses to display

balloons and how you employ them in your application.

The Help Manager uses the Window Manager to create a special

type of window for the help balloon and then draws the content of the

help balloon in the port rectangle of the window. The Help Manager

is responsible for

• calculating the size of the help balloon (based on the content of

the user help information you provide)

• determining line breaks for text in a help balloon

• calculating where to display the help balloon so that it appears

on screen

• drawing the help balloon and its content on screen

A balloon definition function, which is an implementation of a window

definition function, defines the general appearance of the help balloon.

A standard balloon definition function is provided for you, and it is

responsible for

• calculating the content region and structure region of the help

balloon (based on the rectangle calculated by the

Help Manager)

• drawing the frame of the help balloon

The standard balloon definition function is the window definition

function (a 'WDEF' resource) with resource ID 126. The Figure below

shows the general shape of a help balloon drawn with this standard

balloon definition function.

A help balloon drawn with the standard balloon definition function

Every help balloon is further defined by its tip, a hot rectangle, and a

variation code.

A small pointer extends from a corner of every help balloon; this

element indicates what object or area is explained in the help balloon.

The tip is the point at the end of that element. The Figure below shows

an example of a help balloon for a control. The balloon tip is at

coordinates (38,158) of the window.

The tip and hot rectangle for a help balloon

The hot rectangle encloses the area for which you want to provide

Balloon Help on-line assistance. If the cursor is over a hot rectangle,

the

Help Manager displays its help balloon. The Help Manager

removes the help balloon when the cursor is moved away. The user

must pause with the cursor at the same location for a brief amount of

time (around one-tenth of a second) before the Help Manager

displays the help balloon. This prevents excessive flashing of help

balloons. The length of time that a user must pause before a help

balloon appears is set by the system software and cannot be changed.

In the Figure above, the help balloon is displayed for a hot rectangle

defined by local coordinates (0, 0, 65, 165). The Help Manager

displays and removes the help balloon as the cursor moves in and out of

the area defined by the hot rectangle.

A variation code specifies the preferred position of the help balloon

relative to the hot rectangle. The balloon definition function draws the

frame of the help balloon based on that variation code.

As shown in the Figure below, the standard balloon definition function

provides eight different positions, which you can specify with a

variation code from 0 to 7. The figure also shows the boundary

rectangle for each shape. Note that the tip of the help balloon always

aligns with an edge of the boundary rectangle. If you write your own

balloon definition function, you should support the tip locations defined

by the standard variation codes.

Standard balloon positions and their variation codes

For most of the help balloons it displays, the Finder uses variation

code 6. A balloon with variation code 6 has its tip in the lower-left

corner and projects up slightly and to the right.

If a help balloon is on screen and not in the menu bar, the

Help Manager uses the specified variation code to display the help

balloon. If a help balloon is offscreen or in the menu bar, the

Help Manager attempts to display the help balloon by using a

combination of different variation codes and different tip locations.

Usually, the Help Manager moves the tip by transposing it across

the horizontal and vertical planes of the hot rectangle. However, when

you use dialog item help ('hdlg') resources or the HMShowBalloon

and HMShowMenuBalloon functions, the Help Manager allows you

to specify alternate rectangles for transposing balloon tips. Alternate

rectangles give you additional flexibility in positioning your help

balloons on screen. If you make your alternate rectangle smaller than

your hot rectangle, for example, you have greater assurance that the

Help Manager will be able to fit the help balloon on screen; if you

specify an alternate rectangle that is larger than your hot rectangle,

you have greater assurance that the help balloon will not obscure some

element explained by the balloon.

The Figure below shows the Help Manager making three attempts to

fit a help balloon on screen by moving the tip to three different sides

of the hot rectangle and using an appropriate variation code for each

tip.

When positioning a help balloon on screen, the Help Manager first

checks whether the screen has enough horizontal space and then enough

vertical space to display the balloon using the specified variation code

and tip. If the help balloon is either too wide or too long to fit on

Alternate positions of a help balloon

screen at this position, the Help Manager tries a different variation

code. If the help balloon lies within the hot rectangle (or, if

appropriate, within the alternate rectangle), the Help Manager

--using the new variation code--keeps the specified tip and again tests

whether the help balloon fits. If, as in the Figure above, the help

balloon lies outside of the hot rectangle (or the alternate rectangle),

the Help Manager --using the new variation code-moves the tip to a

different side of the rectangle and again tests whether the help balloon

fits. If, after exhausting all possible positions,

the Help Manager still cannot fit the entire help balloon on screen,

the

Help Manager displays a help balloon at the position that best fits

on screen and clips the content of the balloon to fit at this position.

You create help resources that describe the content, the balloon

definition function, the variation code, and, when necessary, the tip

and the hot rectangle or alternate rectangle for the Help Manager to

use in drawing a help balloon. These help resources are

• the menu help ('hmnu') resource to provide help balloons for

menus and menu items

• the dialog item help ('hdlg') resource to provide help balloons

for items in dialog boxes or alert boxes

• the rectangle help ('hrct') resource to associate a help balloon

with a hot rectangle in a static window

• the window help ('hwin') resource to map an 'hrct' or 'hdlg'

resource to a hot rectangle in a window or to a dialog item in a

dialog box or alert box

• the Finder help override ('hfdr') resource to provide a

customized help balloon for your application icon

• the default help override ('hovr') resource to override the

content of default help balloons provided in system software

To put help balloons in your application, you are responsible for

• Creating any necessary help resources for your application.

• Providing the user help information that forms the content of

the help balloons. Although you can store this information in the

help resources themselves or in data structures, localizing your

help content is much easier if you store it in other

resources-such as 'PICT', 'STR#', 'STR ', 'TEXT', and 'styl'

resources-that are easier to edit.

• Specifying in your help resources a balloon definition function

for your help balloons. Typically, you should use the standard

balloon definition function that draws shapes similar to that

shown in this section's first Figure. This helps maintain a

consistent look across all help balloons used by the Finder and

other applications. However, if you feel absolutely compelled to

change the shape of help balloons in your application, you can

write your own balloon definition function,

see, Writing Your Own Balloon Definition Function. Be

aware that a different help balloon shape may initially confuse

your users.

• Specifying in your help resources a variation code. The

variation code positions your balloons on screen according to the

general shape described by their balloon definition function. If

you use the standard balloon definition function, you will use

variation codes 0 to 7 to display the help balloons shown in the

third Figure of this sections. The preferred variation code is 0.

If you are unsure of which variation code you should use, specify

0; the Help Manager will use a different variant if another is

more appropriate. If you write your own balloon definition

function, you must define your own variation codes.

For objects other than menu items, you are also responsible for

• Specifying in your help resources the tip location for the help

balloon. For menu items, the Help Manager automatically

places the tip just inside the right edge of the menu item.

• Specifying rectangles in your help resources. The rectangles

around menu items and dialog items define their hot rectangles

for you. For 'hdlg' resources, you specify alternate rectangles

for moving the help balloon. For 'hrct' resources, you specify

hot rectangles, which define the areas on screen for association of

help balloons.

• Tracking the cursor in dynamic windows, and, when the cursor

moves over a hot rectangle in your window, calling

Help Manager routines (such as HMShowBalloon) to

display your help balloons. You can let your application or the

Help Manager remove the help balloon when the user moves

the cursor off the hot rectangle.

In summary then, the Help Manager automatically displays help

balloons in the following manner. The user turns Balloon Help

assistance on, then moves the cursor to an area described by a hot

rectangle. The Help Manager calculates the size of the help balloon

based on its content. For text or strings, the Help Manager uses

TextEdit to determine the word and line breaks of text in the help

balloon. The Help Manager then determines the size of the help

balloon and uses the Window Manager to create a new help balloon.

The Window Manager calls the balloon definition function to

determine the help balloon's general shape and position. (If the

variation code places the help balloon offscreen or in the menu bar, the

Help Manager tries a different variation code or moves the tip of

the help balloon to another side of the hot rectangle or the alternate

rectangle.) The window definition function draws the window frame,

and the Help Manager draws the content of the help balloon.

For most interface elements that you want to provide help for, you

create the content of the help balloon (preferably in a separate, easily

edited resource) and, in the help resources themselves, you specify

the standard balloon definition function, one of the eight variation

codes, the tip location, and a hot rectangle.

The Help Manager does not automatically display help balloons for

dynamic windows or for menus using customized menu definitions. To

provide help balloons for these elements or in other circumstances

where you want more control over help balloons, you must identify hot

rectangles, create your own data structures to store their locations,

track the cursor yourself, and call HMShowBalloon when the cursor

moves to your hot rectangles. If you wish to, you can also write your

own balloon definition function and tip function.

Referenced by (13):