Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: More Macintosh Toolbox /
Chapter 3 - Help Manager / Help Manager Reference
Help Manager Routines / Getting the Message of a Help Balloon


HMGetIndHelpMsg

To extract the help messages in existing help resources as well as additional information regarding the help resource, such as its variation code, tip location, and so on, use the HMGetIndHelpMsg function.

FUNCTION HMGetIndHelpMsg (whichType: ResType; 
                          whichResID, whichMsg, 
                          whichState: Integer; 
                          VAR options: LongInt; VAR tip: Point; 
                          VAR altRect: Rect; VAR theProc: Integer; 
                          VAR variant: Integer; 
                          VAR aHelpMsg: HMMessageRecord; 
                          VAR count: Integer): 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 and 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.
options
The value of the options element of the help resource.
tip
The coordinates of the help balloon's tip location.
altRect
The coordinates of the help balloon's alternate rectangle.
theProc
The resource ID of the help balloon's 'WDEF' resource.
variant
The balloon definition function's variation code.
aHelpMsg
The help message.
count
The number of components defined in the resource (not counting the header and missing-items components).
DESCRIPTION
Like the HMExtractHelpMsg function, the HMGetIndHelpMsg function returns in its aHelpMsg parameter the help message for an item in a specified state. The HMGetIndHelpMsg function uses additional parameters to return even more information about the help balloon than does HMExtractHelpMsg.

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

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.

SPECIAL CONSIDERATIONS
If HMCompareItem appears as a component of an 'hmnu' resource that you're examining, neither this function nor HMExtractHelpMsg 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 HMGetIndHelpMsg function are
Trap macroSelector
_Pack14$1306

RESULT CODES
noErr0No error
paramErr-50Error in parameter list
memFullErr-108Not enough room in heap zone
resNotFound-192Unable to read resource
hmSkippedBalloon-857No help message to fill in
hmWrongVersion-858Wrong version of Help Manager resource
hmUnknownHelpType-859Help 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.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996