Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager / Help Manager Reference

Help Manager Routines / Getting the Message of a Help Balloon

HMExtractHelpMsg

You can use the HMExtractHelpMsg function to extract the help balloon messages from existing help resources.

FUNCTION HMExtractHelpMsg (whichType: ResType; 
                           whichResID, whichMsg, 
                           whichState: Integer; 
                           VAR aHelpMsg: HMMessageRecord): OSErr;

whichType

The type of help resource. You can use one of these constants: kHMMenuResType, kHMDialogResType, kHMRectListResType, kHMOverrideResType, or kHMFinderApplResType.

whichResID

The resource ID of the help resource whose help message you wish to extract.

whichMsg

The index of the component you wish to extract. The header and missing-items components don't count as components to index, because this function always skips those two components. For help resources that include both header and missing-items components, specify 1 to get the help messages contained in a help resource's menu-title component.

whichState

For menu items and items in alert or dialog boxes, specifies the state of the item whose message you wish to extract. Use one of the following constants: kHMEnabledItem, kHMDisabledItem, kHMCheckedItem, or kHMOtherItem.

aHelpMsg

A help message record.

DESCRIPTION

The HMExtractHelpMsg function returns in its aHelpMsg parameter the help message for an item in a specified state.

The whichType parameter identifies the type of resource from which you are extracting the help message. You can use one of these constants for the whichType parameter.

CONST kHMMenuResType       = 'hmnu';{menu help resource type}
      kHMDialogResType     = 'hdlg';{dialog help resource type}
      kHMWindListResType   = 'hwin';{window help resource type}
      kHMRectListResType   = 'hrct';{rectangle help resource type}
      kHMOverrideResType   = 'hovr';{help override resource }
                                    { type}
      kHMFinderApplResType = 'hfdr';{application icon help }
                                    { resource type}

The whichState parameter specifies the state of the item whose message you want to extract. You can use one of these constants for the whichState parameter.

CONST kHMEnabledItem  = 0; {enabled state for menu items; }
                           { contrlHilite value of 0 for }
                           { controls}
      kHMDisabledItem = 1; {disabled state for menu items; }
                           { contrlHilite value of 255 for }
                           { controls}
      kHMCheckedItem  = 2; {enabled-and-checked state for }
                           { menu items; contrlHilite value }
                           { of 1 for controls that are "on"}
      kHMOtherItem    = 3; {enabled-and-marked state for menu }
                           { items; contrlHilite value }
                           { between 2 and 253 for controls}

For the kHMRectListResType, kHMOverrideResType, and kHMFinderApplResType resource types--which don't have states--supply
the kHMEnabledItem constant for the whichState parameter.

The application-defined procedure shown in Listing 3-21 extracts the help balloon message from the 'hmnu' resource with a resource ID of 128. A value of 1 is supplied as the whichMsg parameter to retrieve information about the resource's first component (after the header and missing-items components, that is), which is the menu title. The menu title has four possible states; to retrieve the help message for the menu title in its dimmed state, the constant kHMDisabledItem is used for the whichState parameter. The help message record returned in aHelpMsg is then passed to HMShowBalloon, which displays the message in a balloon whose tip is located at the point specified in the tip parameter.

Listing 3-21 Using the HMExtractHelpMsg function

FUNCTION MyShowBalloonForDimMenuTitle: OSErr;
VAR
   aHelpMsg:         HMMessageRecord;
   tip:              Point;
   alternateRect:    Rect;
   err:              OSErr;
BEGIN
   err := HMExtractHelpMsg(kHMMenuResType, 128, 1,
                           kHMDisabledItem, aHelpMsg);
   IF err = noErr THEN
   {be sure to assign a tip and rectangle coordinates here}
      err := HMShowBalloon(aHelpMsg, tip, alternateRect,
                           NIL, 0, 0, kHMRegularWindow);
   MyShowBalloonForDimMenuTitle:= err;
END;

To retrieve all of the help messages for a given resource, set whichMsg to 1 and make repeated calls to HMExtractHelpMsg, incrementing whichMsg by 1 on each subsequent call until it returns the hmSkippedBalloon result code.

SPECIAL CONSIDERATIONS

If HMCompareItem appears as a component of an 'hmnu' resource that you're examining, neither this function nor HMGetIndHelpMsg performs a comparison against the current name of any menu item. Instead, these functions return the messages listed in your HMCompareItem components in the order in which they appear in the 'hmnu' resource.

When supplying an index for the whichMsg parameter, don't count the header component or the missing-items component as components to index. This function always skips both components; therefore, for help resources that include both header and missing-items components, specify 1 to get the help messages contained in a help resource's menu-title component.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the HMExtractHelpMsg function are

Trap macro	Selector
_Pack14	$0711

RESULT CODES

noErr	0	No error
paramErr	-50	Error in parameter list
memFullErr	-108	Not enough room in heap zone
resNotFound	-192	Unable to read resource
hmSkippedBalloon	-857	No help message to fill in
hmWrongVersion	-858	Wrong version of Help Manager resource
hmUnknownHelpType	-859	Help message record contained a bad type

SEE ALSO

The aHelpMsg parameter is of data type HMMessageRecord. "Providing Help Balloons for Dynamic Windows" beginning on page 3-69 describes the fields of the help message record.