All Databases Inside Mac - Basic Toolbox

HMShowBalloon

Display a help balloon

#include <Balloons.h> Help Manager

OSErr HMShowBalloon( aHelpMsg, tip, alternateRect , tipProc,

theProc, variant, method );

HMMessageRecord * aHelpMsg ; the de scriptive help information

Point tip ; the location of the tip

RectPtr alternateRect ; a pointer to an alternate rectangle

Ptr tipProc ; a pointer to a tip function

short theProc ; your own balloon definition function resource

short variant ; variation code

short method ; a constant specifying what method to use for

displaying and removing the balloon

Use the HMShowBalloon function to display a help balloon. You

specify the de scriptive help information for the help balloon using the

help message record. The help message record lets you specify the help

information in a number of formats. If your application uses your own

menu definition procedure, you can use the HMShowMenuBalloon

function to display help balloons for the menus that your menu

definition procedure manages. The next sections describe how to use

Help Manager routines to display and remove help balloons.

aHelpMsg If help is enabled, the HMShowBalloon function displays a help

balloon with the de scriptive help information specified in the

aHelpMsg parameter. You specify the help information in the

aHelpMsg parameter using the help message record.

Help Balloons in Dynamic Windows shows how to specify this

information.

tip the location of the tip the Help Manager should use to display the

help balloon.

alternateRect an alternate rectangle that the Help Manager uses for moving the

help balloon's tip when it tries to fit the help balloon on screen. You

specify the tip and the rectangle pointed to by the alternateRect

parameter in global coordinates. The Help Manager calculates the

location and size of the help balloon. If it fits on screen, the

Help Manager displays the help balloon using the specified tip

location.

tipProc You can supply your own tip function (as described in

Using Your Own Tip Function) and point to it in the tipProc

parameter. The Help Manager calls the tip function after

calculating the location of the help balloon and before displaying it. In

the parameters of your tip function, the Help Manager returns the

tip, the region boundary of the entire balloon, the region boundary

for the content area within the balloon frame, and the variation code

to be used for the help balloon. This allows you to examine and

possibly adjust the balloon before it is displayed.

Once the Help Manager determines the location and size of the help

balloon, the Help Manager calls the function pointed to by the

tipProc parameter before displaying the balloon. Specify NIL in the

tipProc parameter to use the Help Manager's default tip function.

theProc specifies the balloon definition function to use. To use your own

balloon definition function, specify the resource ID of its 'WDEF'

resource in the parameter theProc. The Help Manager reads the

balloon definition function specified by the parameter theProc into

memory if it is not already in memory. If the balloon definition

function can not be read into memory, the help balloon is not

displayed and the HMShowBalloon function returns the

resNotFound result code.

Specify 0 in the parameter theProc to use the standard balloon

definition function.

variant The variant parameter is the variation code for the balloon

definition function. Specify 0 in the variant parameter to use the

default help balloon shape, or specify a code from 1 to 7 to use one of

the other positions provided by the standard balloon definition

function (see the third Figure, Help Balloon Display.). If you

write your own balloon definition function, you should support the tip

locations defined by the standard variation codes.

method The method parameter specifies whether the Help Manager should

save the bits behind the balloon and whether to do an update event. See

Help Manager Data for the constants to use for the parameter.

If you specify kHMRegularWindow, the Help Manager draws and

removes the help balloon as if it were a window. That is, when

drawing the balloon the Help Manager does not save bits behind the

balloon, and when removing the balloon the Help Manager generates

an update event. This is the standard behavior of help balloons-and

the behavior you should normally use.

If you specify kHMSaveBitsNoWindow in the method parameter, the

Help Manager does not create a window for displaying the balloon.

Instead, the Help Manager creates a help balloon that is more like a

menu than a window. The Help Manager saves the bits behind the

balloon when it creates the balloon. When it removes the balloon, the

Help Manager re stores the bits without generating an update

event. You should only use this in a modal environment where the bits

behind the balloon cannot change from the time the balloon is drawn

to the time it is removed. For example, you might specify the

kHMSaveBitsNoWindow constant when providing help balloons for

pop-up menus that overlay complex graphics, which might take a

long time to redraw with an update event.

If you specify kHMSaveBitsWindow, the Help Manager treats the

help balloon as a hybrid having properties of both a menu and a

window. That is, the Help Manager saves the bits behind the balloon

when it creates the balloon and, when it removes the balloon, it both

re stores the bits and generates an update event. You will rarely need

this option. It is necessary only in a modal environment that might

immediately change to a nonmodal environment-that is, where the

bits behind the help balloon are static when the balloon is drawn, but

can possibly change before the help balloon is removed.

Returns: an operating system Error Code.

noErr (0) No error; the help balloon was displayed

paramErr (-50) Error in parameter list

memFullErr (-108) Not enough room in heap zone

resNotFound (-192) Unable to read resource

hmHelpDisabled (-850) Help balloons are not enabled

hmBalloonAborted (-853) Because of constant cursor movement, the help

balloon was not displayed

hmOperationUn supported (-861) Invalid value passed in the method parameter

Notes: If you use help resources to define help balloons, the Help Manager uses

the hot rectangles you specify in the help resources for two purposes: first,

to associate areas of the screen with help balloons and, second, to move the

tip if the help balloon does not fit on screen.

If you use the HMShowBalloon function to display 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. The Help Manager does not know the

locations of your hot rectangles, so it cannot use them for moving the tip if

the help balloon is placed off screen. Instead, the Help Manager uses the

alternate rectangle that you point to with the alternateRect parameter.

Often, you specify the same coordinates for the alternate rectangle that you

specify for your hot rectangle. However, you may choose to make your

alternate rectangle smaller or larger than your hot rectangle. If you make

your alternate rectangle smaller than your hot rectangle, 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.

If you specify a rectangle in the alternateRect parameter, the

Help Manager automatically calls HMRemoveBalloon to remove the

balloon when the cursor leaves the area bounded by the rectangle.

If the balloon's first position is partly offscreen or it intersects the menu

bar, the Help Manager tries a combination of different balloon variation

codes and different tip positions along the sides of the alternate rectangle to

make the balloon fit. The Figure, "Alternate positions of a help balloon,

under the section, Help Balloon Display shows what happens when the

balloon's first two positions are located off screen. If, after exhausting all

possible positions, the Help Manager 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. If

the coordinates specified by both the original tip and the alternateRect

parameter are off screen, the Help Manager does not display the help

balloon at all.

If you specify NIL for the alternateRect parameter, your application is

responsible for tracking the cursor and determining when to remove the

help balloon. The Help Manager also does not attempt to calculate a new tip

location if the help balloon is off screen.

Referenced by (23):