Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager / Help Manager Reference

Help Manager Routines / Displaying and Removing Help Balloons

HMShowBalloon

To display a help balloon of the content area of any window of your application, you can use the HMShowBalloon function. If the user has enabled Balloon Help assistance, the HMShowBalloon function displays a help balloon containing the message specified by the aHelpMsg parameter.

FUNCTION HMShowBalloon (aHelpMsg: HMMessageRecord; 
                        tip: Point; alternateRect: RectPtr;
                        tipProc: Ptr; theProc, variant: Integer; 
                        method: Integer): OSErr;

aHelpMsg

The message displayed in the help balloon.

tip

The location, in global coordinates, of the help balloon's tip.

alternateRect

A rectangle, in global coordinates, that the Help Manager uses if necessary to calculate a new tip location. If you specify a rectangle in this parameter, the Help Manager automatically calls the HMRemoveBalloon function to remove the help balloon when the user moves the cursor outside the area bounded by the rectangle. If you instead pass NIL in this parameter, your application must use the HMRemoveBalloon function to remove the help balloon when appropriate.

tipProc

The tip function called by the Help Manager 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

The balloon definition function. To use the standard balloon
definition function, specify 0 in this parameter. To use your own
balloon definition function, specify the resource ID of the 'WDEF' resource containing your balloon definition function.

variant

The variation code for the balloon definition function. Specify 0 in the variant parameter to use the default help balloon position, specify a code from 1 to 7 to use one of the other positions provided by the standard balloon definition function, or specify another code to use one of the positions provided by your own balloon definition function.

method

A value that indicates whether the Help Manager should save the bits behind the balloon and whether to generate an update event.
You can pass one of the following constants in this parameter: kHMRegularWindow, kHMSaveBitsNoWindow,
or kHMSaveBitsWindow.

DESCRIPTION

If help is enabled, the HMShowBalloon function displays a help balloon with the help message you specify in the aHelpMsg parameter. You use global coordinates to specify the tip and the rectangle pointed to by the alternateRect parameter. The Help Manager calculates the location and size of the help balloon. If it fits onscreen, the
Help Manager displays the help balloon using the specified tip location.

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 offscreen. 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 onscreen; if you specify an alternate rectangle that is larger than your hot rectangle, you have greater assurance that the balloon will not obscure the object it explains.

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 if 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. Figure 3-5 on page 3-9 shows what happens when the balloon's first two positions are located offscreen. If, after exhausting all possible positions, the Help Manager cannot fit the entire balloon onscreen, the Help Manager displays a balloon at the position that best fits onscreen and clips the help message to fit at this position. If the coordinates specified by both the original tip and the alternateRect parameter are offscreen, the Help Manager does not display the 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 balloon. The Help Manager also does not attempt to calculate a new tip location if the balloon is offscreen.

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.

You can supply 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 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 balloon. This allows you to examine and possibly adjust the balloon before it is displayed.

The Help Manager reads the balloon definition function specified by the parameter theProc into memory if it isn't already in memory. If the balloon definition function can't be read into memory, the help balloon is not displayed and the HMShowBalloon function returns the resNotFound result code.

The method parameter specifies whether the Help Manager should save the bits behind the balloon and whether to generate an update event. You can supply one of these constants for the parameter.

CONST kHMRegularWindow     = 0;  {don't save bits; just update}
      kHMSaveBitsNoWindow  = 1;  {save bits; don't do update}
      kHMSaveBitsWindow    = 2;  {save bits; do update event}

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; it is 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 restores the bits without generating an update event. You should use this method only 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 restores the bits and generates an update event. You'll 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 balloon are static when the balloon is drawn, but can possibly change before the balloon is removed.

HMShowBalloon returns the noErr result code if the help balloon was successfully displayed.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and the routine selector for the HMShowBalloon function are

Trap macro	Selector
_Pack14	$0B01

RESULT CODES

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 wasn't displayed
hmOperationUnsupported	-861	Invalid value passed in the method parameter

SEE ALSO

You specify the help message in the aHelpMsg parameter. "Providing Help Balloons for Dynamic Windows" beginning on page 3-69 shows how to specify this information.

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.

Figure 3-4 on page 3-9 illustrates the variation codes you can specify in the variant parameter and their corresponding help balloon positions for the standard balloon definition function.

If your application uses its own menu definition procedure, you can use the HMShowMenuBalloon function to display help balloons for the menus that your menu definition procedure manages. The HMShowMenuBalloon function is next.