Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

Chapter 2 - Color Picker Manager Reference /

Color Picker Manager Functions / Getting the Menu State and the Help Balloons for a Color Picker

ExtractPickerHelpItem

Extracts and changes the messages and other characteristics of the help balloons for a color picker.

The Color Picker Manager provides help balloons for color picker dialog boxes. For all types of color picker dialog boxes, applications generally don't need to determine or change the default help balloons. However, if your application absolutely requires greater control over Balloon Help, it can use the ExtractPickerHelpItem function to obtain and change the messages and other characteristics of the default help balloons.

pascal OSErr ExtractPickerHelpItem (
picker thePicker, 
short itemNo, 
short whichState, 
HelpItemInfo *helpInfo);

thePicker

The color picker whose help balloons you wish to obtain.

itemNo

A number corresponding to the position of an item in the item list resource of the color picker's dialog box.

whichState

For menu items and items in alert or dialog boxes, the state of the item specified in the itemNo parameter. The following constants are used to represent the possible states: kHMEnabledItem, kHMDisabledItem, kHMCheckedItem, and kHMOtherItem. See the chapter "Help Manager" in Inside Macintosh: More Macintosh Toolbox for descriptions of these states for various types of dialog items.

helpInfo

A pointer to a HelpItemInfo structure (page 2-32). In the helpMessage field of this structure, the Color Picker Manager passes the default help message in an HMHelpMessage structure. The Color Picker Manager passes the default characteristics of the help balloon--that is, the value of the options element of its help resource, its tip location, its alternate rectangle, its tip function, and its variation code--in the rest of the fields of the HelpItemInfo structure.

DISCUSSION

For the color picker specified in the parameter thePicker, the ExtractPickerHelpItem function reports the messages and other characteristics for its help balloons. If your application needs to override the help message or another help balloon characteristic for the item specified in the itemNo parameter, your application should specify the desired help message and characteristics in the HelpItemInfo structure pointed to in the helpInfo parameter, and then use the Help Manager function HMShowBalloon to display the altered help balloon.

SEE ALSO

Listing 2-14 (page 2-27) in Advanced Color Imaging on the Mac OS illustrates how to use this function. See the chapter "Help Manager" in Inside Macintosh: More Macintosh Toolbox for more information about help balloons.