Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager / Using the Help Manager

Writing Your Own Balloon Definition Function

The Help Manager takes care of positioning, sizing, and drawing your help balloons, and the standard balloon definition function provides a consistent and attractive shape to balloons across all applications.

Although it takes extra work on your part, and your balloons will not share the consistent appearance of help balloons used by the Finder and by other applications, you can create your own balloon definition function. The balloon definition function defines the appearance of the help balloon, which is a special type of window. You implement a 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.

A balloon definition function is 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. (Figure 3-4 on page 3-9 illustrates the structure regions of the eight standard help balloons.)

The Help Manager first calculates the size of the rectangle that can enclose the help message and determines where to display the help balloon. The Help Manager uses TextEdit to determine any word and line breaks in the help message. The Help Manager determines where to display the help balloon based on the tip and alternate rectangle.

The Help Manager then adds a system-defined distance to the size of the rectangle. This distance allows for the tip of the help balloon. Note that the tip must always align with an edge of the boundary rectangle. The Help Manager uses the resulting rectangle as the boundary rectangle for the help balloon window.

To create the help balloon, the Help Manager uses the Window Manager function NewWindow. The Help Manager specifies the calculated rectangle and the window definition ID as parameters to NewWindow.

The NewWindow function calls the balloon definition function in the same manner as a window definition function. See the chapter "Window Manager" in Inside Macintosh: Macintosh Toolbox Essentials for more information on writing a window definition function.

The NewWindow function calls your balloon definition function with four parameters: the variation code that specifies the shape and relative tip position of the help balloon, a pointer to the window, the action to perform, and a parameter that has variable contents depending on the action to perform.

Here's an example that shows the declaration for a balloon definition function called MyBalloonDef.

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

The variant parameter is 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 (see Figure 3-4 on page 3-9). This ensures that the tip of the help balloon points to the object that the help balloon describes.

The parameter theBalloon is a pointer to the window of the help balloon.

The message parameter 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 wDraw and wCalcRgns 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. These messages, along with the wDraw and wCalcRgns messages, are described in the chapter "Window Manager" in Inside Macintosh: Macintosh Toolbox Essentials.

The value of the param parameter depends on the value of the message parameter. The wCalcRgns and wDraw messages do not use this parameter.

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.