Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager / Help Manager Reference

Help Manager Routines / Displaying and Removing Help Balloons

HMRemoveBalloon

To remove a help balloon that your application displays using the function HMShowMenuBalloon, use the HMRemoveBalloon function. If your application
does not specify an alternate rectangle to the HMShowBalloon function, use HMRemoveBalloon to remove the help balloon you display with HMShowBalloon.

FUNCTION HMRemoveBalloon: OSErr;

DESCRIPTION

The HMRemoveBalloon function removes any balloon that is currently visible--unless the user is using Close View and is pressing the Shift key. (This action keeps the help balloon onscreen even while the user moves away from the hot rectangle under Close View.)

If you use the HMShowBalloon function to display help balloons, you can either let the Help Manager track the cursor and remove the balloon when the cursor moves out of the hot rectangle, or your application can track the cursor and determine when to remove the balloon. To let the Help Manager track the cursor and remove the balloon when using the HMShowBalloon function, specify a rectangle in the alternateRect parameter. If you want your application to track the cursor and remove the balloon when using the HMShowBalloon function, specify NIL in the alternateRect parameter. You must then use the HMRemoveBalloon function to remove the balloon when the user moves the cursor outside the rectangle.

If you use the HMShowMenuBalloon function to display help balloons, you must always track the cursor and use the HMRemoveBalloon function to remove the balloon when the cursor moves out of the hot rectangle.

WARNING

The HMRemoveBalloon function removes any help balloon that is currently visible, regardless of the application that displayed it. You should call HMRemoveBalloon only when the cursor is in the content area of your application window but not in a hot rectangle, and you should never call it when your application is in the background.

If the user is using Close View and is pressing the Shift key, the help balloon stays onscreen even while the user moves away from the hot rectangle. The HMRemoveBalloon function returns a result code of hmCloseViewActive in this case.

If you use your own menu definition procedure, you should call HMRemoveBalloon when your procedure receives messages about saving or restoring bits. (These messages are described in the chapter "Menu Manager" in Inside Macintosh: Macintosh Toolbox Essentials.)

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the HMRemoveBalloon function are

Trap macro	Selector
_Pack14	$0002

RESULT CODES

noErr	0	No error or the help balloon was removed
hmHelpDisabled	-850	Help balloons are not enabled
hmNoBalloonUp	-862	No balloon showing
hmCloseViewActive	-863	Balloon can't be removed because Close View is in use

SEE ALSO

The description of the HMShowBalloon function begins on page 3-93; the description of the HMShowMenuBalloon function begins on page 3-96.