Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager / Help Manager Reference

Application-Defined Routines /

MyTip

Here's a sample declaration of a tip function called MyTip.

FUNCTION MyTip (tip: Point; structure: RgnHandle; VAR r: Rect;
                VAR variant: Integer): OSErr;

tip

The location of the help balloon tip.

structure

A handle to the help balloon's region structure. The Help Manager returns this value. 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.

r

The coordinates of the help balloon's content region. The content region is the area inside the balloon frame; it contains the help message. If this rectangle is not appropriate for the current screen display, you can specify different coordinates in this parameter.

variant

Variation code to be used for the help balloon. If this variation code is not appropriate for the current screen display, you can specify different coordinates in this parameter.

DESCRIPTION

Before displaying a help balloon created with the HMShowBalloon or HMShowMenuBalloon function, the Help Manager calls this function if you point to it in the tipProc parameter of either HMShowBalloon or HMShowMenuBalloon. The Help Manager returns the location of the help balloon tip, a handle to the help balloon's region structure, the coordinates of its content region, and the variation code to be used for the help balloon. If the help balloon that HMShowBalloon or HMShowMenuBalloon initially calculates is not appropriate for your current screen display, you can make minor adjustments to it by specifying a different rectangle in the r parameter (in which case the Help Manager automatically adjusts the structure parameter so that the entire balloon is larger or smaller as necessary) or by specifying a different variation code in the variant parameter.

If you need to make a major adjustment to the help balloon, return the hmBalloonAborted result code and call HMShowBalloon or HMShowMenuBalloon with appropriate new parameter values. To use the values returned in your tip function's parameters, return the noErr result code.

Listing 3-22 shows an example of using a tip function to refrain from displaying a balloon if it obscures an area of the screen that requires extensive drawing.

Listing 3-22 Using a tip function

VAR
   temprect:         Rect;
   DontObscureRect:  Rect;
   tip:              Point;
   structure:        RgnHandle;
   aHelpMsg:         HMMessageRecord;

BEGIN
      {be sure to determine DontObscureRect and fill in aHelpMsg}
      IF HMShowBalloon(aHelpMsg, tip, NIL, @MyTip, 0, 0,
                       kHMRegularwindow) = noErr
      THEN
         {test whether balloon obscures complex graphic }
         { in DontObscureRect}
         IF SectRect(structure^^.rgnBBox, DontObscureRect,
                     temprect) THEN 
            {don't show this balloon but call HMShowBalloon later}
            MyTip := hmBalloonAborted
         ELSE  {use the balloon as calculated by the Help Manager}
            MyTip := noErr;
END;

SEE ALSO

Figure 3-4 on page 3-9 illustrates the structure regions and positions of the eight standard help balloons.

The HMShowBalloon function is described on page 3-93, and the HMShowMenuBalloon function is described on page 3-96.