All Databases Inside Mac - Basic Toolbox

HMShowMenuBalloon

Display a help balloon

#include <Balloons.h> Help Manager

OSErr HMShowMenuBalloon(itemNum, itemMenuID, itemFlags,

itemReserved, tip, alternateRect, tipProc, theProc,

variant );

short itemNum ; the menu item number

short itemMenuID ; the menu ID of the menu

long itemFlags ; tells whether a menu item is enabled or dimmed

long itemReserved; reserved for future use by Apple

Point tip; specifies the tip for the help balloon

RectPtr alternateRect; is a pointer to the rectangle the Help Manager

uses to calculate a new tip location.

Ptr tipProc; is a pointer to the tip function values

short theProc; reserved

short variant; specifies the variation code for the standard balloon

definition function

The HMShowMenuBalloon function uses the standard balloon

definition function to display the help balloon. If you want to use your

own balloon definition function from within your menu definition

procedure, call the HMShowBalloon function.

After your menu definition procedure determines that the cursor is

over a menu item, you can use the HMShowMenuBalloon function to

display any help balloons associated with that item. You must then use

the HMRemoveBalloon function to remove the balloon when the

cursor moves away from the menu item.

itemNum is the menu item number of the item that the cursor is currently

over. Use a positive number in the itemNum parameter to specify a

menu item, use -1 if the cursor is over a dashed line, or use 0 if the

cursor is over the menu title.

itemMenuID is the menu ID of the menu the cursor is currently in.

itemFlags is a long integer from the menu flags, which tells whether a menu

item is enabled or dimmed, and whether the menu itself is enabled or

dimmed. The Help Manager uses this value to determine which

balloon to display from the 'hmnu' resource.

itemReserved is reserved for future use by Apple. Specify 0 in this parameter.

tip specifies the tip for the help balloon. The standard menu definition

procedure places the tip eight pixels from either the right or left

edge of the menu item. For menu titles, the standard menu definition

procedure centers the tip at the bottom of the menu bar. Note that you

should not specify a tip with coordinates in the menu bar for any

menu titles. The Help Manager uses the tip you specify unless it

places the help balloon offscreen or in the menu bar. If the tip is

off screen, the Help Manager uses the rectangle specified in the

alternateRect parameter to calculate a new tip location.

If you use the HMShowMenuBalloon 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 HMShowMenuBalloon 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.

alternateRect is the rectangle the Help Manager uses to calculate a new tip

location. (The standard menu definition procedure specifies the

alternate rectangle as the rectangle that encloses the menu title or

menu item.) If the balloon's first position is offscreen or in the menu

bar, the Help Manager tries a different balloon variation code or

calculates a new tip by transposing it to an opposite side of the

alternate rectangle. If you specify NIL for the alternateRect

parameter, the Help Manager does not attempt to calculate a new

tip position if the help balloon is off screen.

Note that, unlike the way the alternateRect parameter works in the

HMShowBalloon function, specifying an alternate rectangle to

HMShowMenuBalloon does not cause the Help Manager to track

the cursor and remove the balloon for you. You must still track the

cursor and use the HMRemoveBalloon function to remove the

balloon when the cursor moves out of the area specified by the hot

rectangle.

tipProc Specify NIL in the tipProc parameter to use the tip function values

calculated by the Help Manager. If you supply your own tip

function (as described in Using Your Own Tip Function) and

specify it in the tipProc parameter, 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 before displaying it. This allows you to

examine and possibly adjust the balloon before it is displayed.

theProc is reserved for use by Apple. Specify 0 in this parameter.

variant specifies the variation code for the standard balloon definition

function. Specify 0 to use the default balloon position or a code

between 1 and 7 to use one of the other standard positions shown in

the third Figure in the section Help Balloon Display.

Returns: an operating system Error Code.

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

memFullErr (-108) Not enough room in heap zone

hmHelpDisabled (-850) Help balloons are not enabled

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

balloon was not displayed

hmSameAsLastBalloon (-854) Menu and item are same as last menu and item

Notes: The HMShowMenuBalloon function saves the bits behind the help

balloon before displaying the help balloon. When the help balloon is

removed, the

Help Manager re stores the bits that were previously behind the help

balloon.

Referenced by (15):