Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 3 - Help Manager / Help Manager Reference

Data Structures

The Help Message Record

A help message record describes a help message. The Help Manager displays a help balloon with that message when the help message record is passed in the aHelpMsg parameter to the HMShowBalloon function. The HMMessageRecord data type defines the help message record.

TYPE HMMessageRecord = 
RECORD
   hmmHelpType:      Integer;             {type of next field}
   CASE Integer OF
      khmmString:    (hmmString: Str255); {Pascal string}
      khmmPict:      (hmmPict: Integer);  {'PICT' resource ID}
      khmmStringRes: (hmmStringRes: HMStringResType); 
                                             {'STR#' resource ID }
                                             { and index}
      khmmTEHandle:  (hmmTEHandle: TEHandle);
                                             {TextEdit handle}
      khmmPictHandle:(hmmPictHandle: PicHandle); 
                                             {picture handle}
      khmmTERes:     (hmmTERes: Integer);    {'TEXT'/'styl' }
                                             { resource ID}
      khmmSTRRes:    (hmmSTRRes: Integer)    {'STR ' resource ID}
END;

Field Description

hmmHelpType

Specifies the data type of the next field of the help message record. You specify one of these constants for the hmmHelpType field.

                  CONST
                  khmmString     = 1; {Pascal string}
                  khmmPict       = 2; {'PICT' resource ID}
                  khmmStringRes  = 3; {'STR#' resource ID/index}
                  khmmTEHandle   = 4; {TextEdit handle}
                  khmmPictHandle = 5; {picture handle}
                  khmmTERes      = 6; {'TEXT'/'styl' resource ID}
                  khmmSTRRes     = 7; {'STR ' resource ID}

Only one field follows the hmmHelpType field, but it can be one of seven different data types. The field that follows the hmmHelpType field specifies the help message itself.

hmmString

Contains a Pascal string for a help message when you supply the khmmString constant in the hmmHelpType field. (This is generally not recommended; instead, you should store the help message in a resource, which makes localization easier.)

hmmPict

Contains the resource ID of a 'PICT' resource for a help message when you supply the khmmPict constant in the hmmHelpType field.

hmmStringRes

Contains a Help Manager string list record (described in "The Help Manager String List Record" on page 3-90) when you supply the khmmStringRes constant in the hmmHelpType field.

hmmTEHandle

Specifies a TextEdit handle to a help message when you supply the khmmTEHandle constant in the hmmHelpType field.

hmmPictHandle

Specifies a handle to a 'PICT' graphic containing a help message when you supply the khmmPictHandle constant in the hmmHelpType field.

hmmTERes

Specifies the resource ID of both a 'TEXT' and an 'styl' resource for a help message when you supply the khmmTEHandle constant in the hmmHelpType field.

hmmSTRRes

Specifies the resource ID of an 'STR ' resource for a help message when you supply the khmmSTRRes constant in the hmmHelpType field.

Because the Help Manager uses the resource itself or the actual handle that you pass to HMShowBalloon, your 'PICT' resource should be purgeable, or, when using a handle to a 'PICT' resource, you should release the handle or dispose of it when you are finished with it.

Examples of how to use a help message record are provided in "Providing Help Balloons for Dynamic Windows" on page 3-69.