Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager / Help Manager Reference

Application-Defined Routines /

MyBalloonDef

Here's a sample declaration for a balloon definition function called MyBalloonDef.

FUNCTION MyBalloonDef (variant: Integer; theBalloon: WindowPtr; 
                       message: Integer; 
                       param: LongInt): LongInt;

variant

The variation code used to specify the shape and position of the help balloon. You should use the same relative position for the tip of the
help balloon that the standard variation codes 0 through 7 specify. This ensures that the tip of the help balloon points to the object that the help balloon describes.

theBalloon

A pointer to the window of the help balloon.

message

Identifies the action your balloon definition function should perform. Your balloon definition function can be sent the same messages as a window definition function, but the only ones your balloon definition function needs to process are the wCalcRgns and wDraw messages.

When your balloon definition function receives the wCalcRgns message, your function should calculate the content region and structure region of the help balloon.

When your balloon definition function receives the wDraw message, your function should draw the frame of the help balloon.

If you want to process other messages in your balloon definition function (for example, performing any additional initialization), you can also process the other standard 'WDEF' messages.

param

As with a window definition function, the value of this parameter depends on the value of the message parameter. Because this parameter is not used by the wCalcRgns and wDraw messages, your balloon definition function should disregard the value of this parameter.

DESCRIPTION

Your balloon definition function must define the appearance of the help balloon, which is a special type of window. You can implement your own balloon definition function by writing a window definition function that performs the tasks described in this section. (The standard balloon definition function is of type 'WDEF' with resource ID 126.)

Your balloon definition function is also responsible for calculating the content region and structure region of the help balloon window and drawing the frame of the help balloon. The content region is the area inside the balloon frame; it contains the help message. The structure region is the boundary region of the entire balloon, including the content area and the pointer that extends from one of the help balloon's corners.

If you want the Help Manager to use your balloon definition function, you specify its resource ID and the desired variation code either in the HMShowBalloon function or in the appropriate elements of the 'hmnu', 'hdlg', or 'hrct' resource. The Help Manager derives your balloon's window definition ID from its resource ID.

SEE ALSO

In the variant parameter, you should use the same relative position for the tip of the help balloon that the standard variation codes 0 through 7 specify, as illustrated in
Figure 3-4 on page 3-9.

The wCalcRgns and wDraw messages are described in the chapter "Window Manager" of Inside Macintosh: Macintosh Toolbox Essentials.