Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager / Help Manager Reference

Help Manager Routines / Displaying and Removing Help Balloons

HMShowMenuBalloon

The Help Manager displays help balloons for applications that provide 'hmnu' resources and use the standard menu definition procedure. If your application uses your own menu definition procedure, you can still use the Help Manager to display help balloons for the menus that your menu definition procedure manages. Use the HMShowMenuBalloon function to display balloons described by the standard balloon definition function. If you want to use your own balloon definition function from within your menu definition procedure, call the HMShowBalloon function (described in the previous section) and specify the kHMSaveBitsNoWindow constant for the method parameter. You can also use the HMShowMenuBalloon function as an alternative to creating an 'hmnu' resource for your menu.

FUNCTION HMShowMenuBalloon (itemNum: Integer; itemMenuID: Integer; 
                           itemFlags: LongInt; 
                           itemReserved: LongInt; 
                           tip: Point; alternateRect: RectPtr; 
                           tipProc: Ptr; theProc: Integer; 
                           variant: Integer): OSErr;

itemNum

The number of the menu item over which the cursor is currently located. Use a positive number in the itemNum parameter to specify a menu item, use -1 if the cursor is located over a divider line, or use 0 if the cursor is located over the menu title.

itemMenuID

The ID of the menu in which the cursor is currently located.

itemFlags

A long integer from the menu flags, telling 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

Reserved for future use by Apple. Specify 0 in this parameter.

tip

The tip for the help balloon. The standard menu definition procedure places the tip 8 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; you should not specify a tip with coordinates in the menu bar for any menu titles.

The Help Manager uses the tip you specify in this parameter unless it places the help balloon offscreen or in the menu bar. If the tip is offscreen, the Help Manager uses the rectangle specified in the alternateRect parameter to calculate a new tip location.

alternateRect

The rectangle that 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 when the help balloon is offscreen.

tipProc

The tip function that the Help Manager calls before displaying the balloon. Specify NIL to use the Help Manager's default tip function, or supply your own tip function and point to it in this parameter.

theProc

Reserved for use by Apple. Specify 0 in this parameter.

variant

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 Figure 3-4 on page 3-9.

DESCRIPTION

The HMShowMenuBalloon function saves the bits behind the help balloon before displaying the help balloon. When you remove the balloon, the Help Manager restores the bits that were previously behind it.

After your menu definition procedure determines that the cursor is located in 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.

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 balloon is placed offscreen. Instead, the Help Manager uses the alternate rectangle that you point to with the alternateRect parameter.

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.

Specify NIL in the tipProc parameter to use the tip function values calculated by the Help Manager. If you supply 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.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the HMShowMenuBalloon function are

Trap macro	Selector
_Pack14	$0E05

RESULT CODES

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 wasn't displayed
hmSameAsLastBalloon	-854	Menu and item are same as last menu and item

SEE ALSO

You can supply your own tip function (as explained in the description of the MyTip function, which begins on page 3-122) and point to it in the tipProc parameter.

The HMRemoveBalloon function is described next.