Legacy Document

Inside Macintosh: Advanced Color Imaging on the Mac OS /

Chapter 2 - Color Picker Manager / Using the Color Picker Manager

Controlling the Help Balloons for a Color Picker's Dialog Box

The Color Picker Manager supports Balloon Help user assistance (which is described in the chapter "Help Manager" in Inside Macintosh: More Macintosh Toolbox). Most applications don't need to do anything special to use Balloon Help for a color picker in any type of dialog box. However, if your application needs control over a color picker's help balloon, you can use the ExtractPickerHelpItem function to get the help balloon for the color picker. You can then use the Help Manager function HMShowBalloon to override the default help balloon and display the altered balloon.

It's up to your application to determine whether the cursor is over a color picker's item or one of your application's items. You can use the Dialog Manager function FindDialogItem to determine which item the cursor is over. If it's over one of your application items, you can put up your own help balloon. Otherwise, use the ExtractPickerHelpItem function to get the color picker's balloon, which you can alter or display as it is defined by the color picker. The ExtractPickerHelpItem function searches the color picker's help resource for an appropriate balloon. If it can't find one, it returns the noHelpForItem result.

Listing 2-14 illustrates how you can control the help balloons for a color picker dialog box. Everything in this example is performed by the Color Picker Manager internally; the example just gives you a general idea of how to use ExtractPickerHelpItem.

Listing 2-14 Using the ExtractPickerHelpItem function

void MyDoPickerBalloonHelp(void) 
{
   HelpItemInfo   helpInfo;
   short          itemNo;
   Point          where;
   OSErr          err;

   GetMouse(&where);
   itemNo = FindDialogItem(gMyDialog, where) + 1;
   /* get the color picker's help item */
   helpInfo.options = 0;
   helpInfo.tip.v = helpInfo.tip.h = 0;
   SetRect(&helpInfo.altRect, 0, 0, 0, 0);
   helpInfo.theProc = 0;
   helpInfo.variant = 0;
   helpInfo.helpMessage.hmmHelpType = 0;
   helpInfo.helpMessage.u.hmmPictHandle = 0L;
   err = ExtractPickerHelpItem(myPicker, itemNo, 0, &helpInfo);
   /* show the balloon */
   if (err == noErr) 
   {
      /* if altRect is empty, use the item's rectangle */
      if (EmptyRect(&helpInfo.altRect)) 
      {
         short    iType;
         Handle   iHandle;
         GetDialogItem(gMyDialog, itemNo, &iType, &iHandle,
                     &helpInfo.altRect);
      }
      /* convert balloon tip's location to local coordinates */
      helpInfo.tip.h += helpInfo.altRect.left;
      helpInfo.tip.v += helpInfo.altRect.top;
      /* convert the balloon tip and the altRect to global 
         coordinates */
      LocalToGlobal(&helpInfo.tip);
      LocalToGlobal((Point *) &helpInfo.altRect.top);
      LocalToGlobal((Point *) &helpInfo.altRect.bottom);
      /* show the balloon */
      HMShowBalloon (&helpInfo.helpMessage, helpInfo.tip,
                     &helpInfo.altRect, 0L, helpInfo.theProc, 
                     helpInfo.variant, kHMRegularWindow);
   }
}

If your color picker needs to override the help message or another help balloon characteristic for the item specified in the itemNo parameter for the ExtractPickerHelpItem function, you should do so before using the Help Manager function HMShowBalloon to display the help balloon. Specify the desired help message and characteristics in the HelpItemInfo structure pointed to in the helpInfo parameter to HMShowBalloon.