Legacy Document

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

Inside Macintosh: More Macintosh Toolbox /: Chapter 3 - Help Manager

Summary of the Help Manager

Pascal Summary

Constants

CONST    
   gestaltHelpMgrAttr      = 'help';   {Gestalt selector}
   gestaltHelpMgrPresent   =  0;       {if this bit is set, then }
                                       { Help Manager is present}
   hmBalloonHelpVersion    = $0002;    {Help Manager version}
   kBalloonWDEFID          = 126;      {resource ID of standard balloon }
                                       { 'WDEF' function}
   kHMHelpID               = -5696;    {ID of various Help Manager }
                                       { resources (in Pack14 range); }
                                       { also used for 'hfdr' resource ID} 

   {Help menu constants}
   kHMAboutHelpItem        = 1;        {About Balloon Help menu item}
   kHMHelpMenuID           = -16490;   {Help menu resource ID}
   kHMShowBalloonsItem     = 3;        {Show/Hide Balloons menu item}
   
   {HelpItem type for 'DITL' resources}
   helpItem                = 1;        {help item}
         
   {option bits for help resources}
   hmDefaultOptions        = 0;        {use defaults}
   hmUseSubID              = 1;        {use subrange resource IDs }
                                       { for owned resources}
   hmAbsoluteCoords        = 2;        {ignore coords of window }
                                       { origin and treat upper-left }
                                       { corner of window as 0,0}
   hmSaveBitsNoWindow      = 4;        {don't create window; save }
                                       { bits; no update event}
   hmSaveBitsWindow        = 8;        {save bits behind window and }
                                       { generate update event}
   hmMatchInTitle          = 16;       {match window by string }
                                       { anywhere in title string}
         
   {constants for hmmHelpType field of HMMessageRecord}
   khmmString              = 1;        {Pascal string}
   khmmPict                = 2;        {'PICT' resource ID}
   khmmStringRes           = 3;        {'STR#' res ID and index}
   khmmTEHandle            = 4;        {TextEdit handle}
   khmmPictHandle          = 5;        {picture handle}
   khmmTERes               = 6;        {'TEXT' and 'styl' resource ID}
   khmmSTRRes              = 7;        {'STR ' resource ID}
   {resource types for styled text in resources}
   kHMTETextResType        = 'TEXT';   {'TEXT' resource type}
   kHMTEStyleResType       = 'styl';   {'styl' resource type}
   
   {constants for whichState parameter when extracting help }
   { message records from 'hmnu' and 'hdlg' resources}
   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}
   
   {resource types for whichType parameter used when extracting }
   { help message}
   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';   {app icon help resource type}
   
   {constants for method parameter in HMShowBalloon}
   kHMRegularWindow        = 0;        {don't save bits; just update}
   kHMSaveBitsNoWindow     = 1;        {save bits; don't do update}
   kHMSaveBitsWindow       = 2;        {save bits; do update event}
   
   {constants for help types in 'hmnu', 'hdlg', 'hrct', 'hovr', and }
   { 'hfdr' resources--useful only for walking these resources}
   kHMStringItem           = 1;        {Pascal string}
   kHMPictItem             = 2;        {'PICT' resource ID}
   kHMStringResItem        = 3;        {'STR#' resource ID & index}
   kHMTEResItem            = 6;        {'TEXT' & 'styl' resource ID}
   kHMSTRResItem           = 7;        {'STR ' resource ID}
   kHMSkipItem             = 256;      {don't display a balloon}
   kHMCompareItem          = 512;      {for 'hmnu', use help message }
                                       { if menu item matches string}
   kHMNamedResourceItem    = 1024;     {for 'hmnu', use menu item to }
                                       { get a named resource}
   kHMTrackCntlItem        = 2048;     {reserved}

Data Types

TYPE  HMStringResType   =                 {Help Manager string list record}
      RECORD
         hmmResID:      Integer;          {'STR#' resource ID}
         hmmIndex:      Integer;          {index of string}
      END;
      HMMessageRecPtr   = ^HMMessageRecord;
      HMMessageRecord   =                             {help message record}
      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;

Help Manager Routines

Determining Help Balloon Status

FUNCTION HMGetBalloons: Boolean;
FUNCTION HMIsBalloon: Boolean;

Displaying and Removing Help Balloons

FUNCTION HMShowBalloon       (aHelpMsg: HMMessageRecord; tip: Point; 
                              alternateRect: RectPtr; tipProc: Ptr; 
                              theProc: Integer; variant: Integer; 
                              method: Integer): OSErr;
FUNCTION HMShowMenuBalloon   (itemNum: Integer; itemMenuID: Integer; 
                              itemFlags: LongInt; itemReserved: LongInt; 
                              tip: Point; alternateRect: RectPtr; 
                              tipProc: Ptr; theProc: Integer; 
                              variant: Integer): OSErr;
FUNCTION HMRemoveBalloon     : OSErr;

Enabling and Disabling Balloon Help Assistance

FUNCTION HMSetBalloons       (flag: Boolean): OSErr;

Adding Items to the Help Menu

FUNCTION HMGetHelpMenuHandle
                             (VAR mh: MenuHandle): OSErr;

Getting and Setting the Font Name and Size

FUNCTION HMGetFont        (VAR font: Integer): OSErr;
FUNCTION HMGetFontSize    (VAR fontSize: Integer): OSErr;
FUNCTION HMSetFont        (font: Integer): OSErr;
FUNCTION HMSetFontSize    (fontSize: Integer): OSErr;

Setting and Getting Information for Help Resources

FUNCTION HMSetMenuResID   (menuID: Integer; resID: Integer): OSErr;
FUNCTION HMGetMenuResID   (menuID: Integer; VAR resID: Integer): OSErr;
FUNCTION HMScanTemplateItems
                          (whichID: Integer; whichResFile: Integer; 
                           whichType: ResType): OSErr;
FUNCTION HMSetDialogResID (resID: Integer): OSErr;
FUNCTION HMGetDialogResID (VAR resID: Integer): OSErr;

Determining the Size of a Help Balloon

FUNCTION HMBalloonRect    (aHelpMsg: HMMessageRecord; 
                           VAR coolRect: Rect): OSErr;
FUNCTION HMBalloonPict    (aHelpMsg: HMMessageRecord; 
                           VAR coolPict: PicHandle): OSErr;
FUNCTION HMGetBalloonWindow
                          (VAR window: WindowPtr): OSErr;

Getting the Message of a Help Balloon

FUNCTION HMExtractHelpMsg (whichType: ResType; 
                           whichResID: Integer; whichMsg: Integer; 
                           whichState: Integer; 
                           VAR aHelpMsg: HMMessageRecord): OSErr;
FUNCTION HMGetIndHelpMsg  (whichType: ResType; 
                           whichResID: Integer; whichMsg: Integer; 
                           whichState: Integer; 
                           VAR options: LongInt; VAR tip: Point; 
                           VAR altRect: Rect; VAR theProc: Integer; 
                           VAR variant: Integer; 
                           VAR aHelpMsg: HMMessageRecord; 
                           VAR count: Integer): OSErr;

Application-Defined Routines

FUNCTION MyBalloonDef     (variant: Integer; theBalloon: WindowPtr; 
                           message: Integer; param: LongInt): LongInt;
FUNCTION MyTip            (tip: Point; structure: RgnHandle; 
                           VAR r: Rect; VAR variant: Integer): OSErr;

C Summary

Constants

enum {
   #define gestaltHelpMgrAttr  'help'  /*Gestalt selector*/
   gestaltHelpMgrPresent      =  0     /*if this bit is set, then */
                                       /* Help Manager is present*/
};
enum {
   hmBalloonHelpVersion    = 0x0002,   /*Help Manager version*/
   kBalloonWDEFID          = 126,      /*resource ID of standard balloon */
                                       /* 'WDEF' function*/
   kHMHelpID               = -5696,    /*ID of various Help Manager */
                                       /* resources (in Pack14 range); */
                                       /* also used for 'hfdr' resource ID*/ 
   /*Help menu constants*/
   kHMAboutHelpItem        = 1,        /*About Balloon Help menu item*/
   kHMHelpMenuID           = -16490,   /*Help menu resource ID*/
   kHMShowBalloonsItem     = 3,        /*Show/Hide Balloons menu item*/
   
   /*help item type for 'DITL' resources*/
   HelpItem                = 1,        /*help item*/
         
   /*option bits for help resources*/
   hmDefaultOptions        = 0,        /*use defaults*/
   hmUseSubID              = 1,        /*use subrange resource IDs */
                                       /* for owned resources*/
   hmAbsoluteCoords        = 2         /*ignore coords of window */
                                       /* origin and treat upper-left */
                                       /* corner of window as 0,0*/
};
enum {
   hmSaveBitsNoWindow      = 4,        /*don't create window; save */
                                       /* bits; no update event*/
   hmSaveBitsWindow        = 8,        /*save bits behind window and */
                                       /* generate update event*/
   hmMatchInTitle          = 16,       /*match window by string */
                                       /* anywhere in title string*/
         
   /*constants for hmmHelpType field of HMMessageRecord*/
   khmmString              = 1,        /*Pascal string*/
   khmmPict                = 2,        /*'PICT' resource ID*/
   khmmStringRes           = 3,        /*'STR#' res ID and index*/
   khmmTEHandle            = 4,        /*TextEdit handle*/
   khmmPictHandle          = 5,        /*picture handle*/
   khmmTERes               = 6,        /*'TEXT' and 'styl' resource ID*/
   khmmSTRRes              = 7,        /*'STR ' resource ID*/
   /*resource types for styled text in resources*/
   #define kHMTETextResType    'TEXT'  /*'TEXT' resource type*/
   #define kHMTEStyleResType   'styl'  /*'styl' resource type*/
   /*constants for whichState parameter when extracting help */
   /* message records from 'hmnu' and 'hdlg' resources*/
   kHMEnabledItem          = 0,        /*enabled state for menu items; */
                                       /* contrlHilite value of 0 for */
                                       /* controls*/
};
enum {
   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*/
   
   /*resource types for whichType parameter used when extracting */
   /* help message*/
   #define kHMMenuResType        'hmnu'   /*menu help resource type*/
   #define kHMDialogResType      'hdlg'   /*dialog help resource type*/
   #define kHMWindListResType    'hwin'   /*window help resource type*/
   #define kHMRectListResType    'hrct'   /*rectangle help resource type*/
   #define kHMOverrideResType    'hovr'   /*help override resource type*/
   #define kHMFinderApplResType  'hfdr'   /*app icon help resource type*/
   
   /*constants for method parameter in HMShowBalloon*/
   kHMRegularWindow        = 0,        /*don't save bits; just update*/
   kHMSaveBitsNoWindow     = 1,        /*save bits; don't do update*/
   kHMSaveBitsWindow       = 2         /*save bits; do update event*/
}; 
enum {
   /*constants for help types in 'hmnu', 'hdlg', 'hrct', 'hovr', and */
   /* 'hfdr' resources--useful only for walking these resources*/
   kHMStringItem           = 1,        /*Pascal string*/
   kHMPictItem             = 2,        /*'PICT' resource ID*/
   kHMStringResItem        = 3,        /*'STR#' resource ID & index*/
   kHMTEResItem            = 6,        /*'TEXT' & 'styl' resource ID*/
   kHMSTRResItem           = 7,        /*'STR ' resource ID*/
   kHMSkipItem             = 256,      /*don't display a balloon*/
   kHMCompareItem          = 512,      /*for 'hmnu', use help message */
                                       /* if menu item matches string*/
   kHMNamedResourceItem    = 1024,     /*for 'hmnu', use menu item to */
                                       /* get a named resource*/
   kHMTrackCntlItem        = 2048      /*reserved*/
};

Data Types

struct HMStringResType {      /*Help Manager string list record*/
      short    hmmResID;      /*'STR#' resource ID*/
      short    hmmIndex;      /*index of string*/
};
typedef struct HMStringResType HMStringResType;
struct HMMessageRecord {      /*help message record*/
   short hmmHelpType;         /*type of next field*/
   union {
      char              hmmString[256];   /*Pascal string*/
      short             hmmPict;          /*'PICT' resource ID*/
      Handle            hmmTEHandle;      /*TextEdit handle*/
      HMStringResType   hmmStringRes;     /*'STR#' resource ID and index*/
      short             hmmPictRes;       /*unused*/
      Handle            hmmPictHandle;    /*picture handle*/
      short             hmmTERes;         /*'TEXT'/'styl' resource ID*/
      short             hmmSTRRes;        /*'STR ' resource ID*/
   } u;
};
typedef struct HMMessageRecord HMMessageRecord;
typedef HMMessageRecord *HMMessageRecPtr;

Help Manager Routines

Determining Help Balloon Status

pascal Boolean HMGetBalloons
(void);
pascal Boolean HMIsBalloon(void);

Displaying and Removing Help Balloons

pascal OSErr HMShowBalloon    (const HMMessageRecord *aHelpMsg, Point tip,
                               RectPtr alternateRect, Ptr tipProc, 
                               short theProc, short variant, short method);
pascal OSErr HMShowMenuBalloon
                              (short itemNum, short itemMenuID, 
                               long itemFlags, long itemReserved, 
                               Point tip, RectPtr alternateRect, 
                               Ptr tipProc, short theProc, short variant);
pascal OSErr HMRemoveBalloon
                              (void);

Enabling and Disabling Balloon Help Assistance

pascal OSErr HMSetBalloons    (Boolean flag);

Adding Items to the Help Menu

pascal OSErr HMGetHelpMenuHandle
                              (MenuHandle *mh);

Getting and Setting the Font Name and Size

pascal OSErr HMGetFont        (short *font);
pascal OSErr HMGetFontSize    (short *fontSize);
pascal OSErr HMSetFont        (short font);
pascal OSErr HMSetFontSize    (short fontSize);

Setting and Getting Information for Help Resources

pascal OSErr HMSetMenuResID
                  (short menuID, short resID);
pascal OSErr HMGetMenuResID
                  (short menuID, short *resID);
pascal OSErr HMScanTemplateItems
                  (short whichID, short whichResFile, 
                   ResType whichType);
pascal OSErr HMSetDialogResID
                  (short resID);
pascal OSErr HMGetDialogResID
                  (short *resID);

Determining the Size of a Help Balloon

pascal OSErr HMBalloonRect (const HMMessageRecord *aHelpMsg, 
                            Rect *coolRect);
pascal OSErr HMBalloonPict (const HMMessageRecord *aHelpMsg, 
                            PicHandle *coolPict);
pascal OSErr HMGetBalloonWindow
                           (WindowPtr *window);

Getting the Message of a Help Balloon

pascal OSErr HMExtractHelpMsg
                           (ResType whichType, short whichResID, 
                            short whichMsg, short whichState, 
                            HMMessageRecord *aHelpMsg);
pascal OSErr HMGetIndHelpMsg
                           (ResType whichType, short whichResID, 
                            short whichMsg, short whichState, 
                            long *options, Point *tip, Rect *altRect,
                            short *theProc, short *variant, 
                            HMMessageRecord *aHelpMsg, short *count);

Application-Defined Routines

pascal long MyBalloonDef   (short variant, WindowPtr theBalloon, 
                            short message, long param);
pascal OSErr MyTip         (Point tip, RgnHandle structure,
                            Rect *r, short *variant);

Assembly-Language Summary

Data Structures

Help Message Data Structure
0 hmmHelpType word Resource type
2 hmmHelpMessage variable Help balloon message

Trap Macros

Trap Macros Requiring Routine Selectors

_Pack14

Selector	Routine
$0002	HMRemoveBalloon
$0003	HMGetBalloons
$0007	HMIsBalloon
$0104	HMSetBalloons
$0108	HMSetFont
$0109	HMSetFontSize
$010C	HMSetDialogResID
$0200	HMGetHelpMenuHandle
$020A	HMGetFont
$020B	HMGetFontSize
$020D	HMSetMenuResID
$0213	HMGetDialogResID
$0215	HMGetBalloonWindow
$0314	HMGetMenuResID
$040E	HMBalloonRect
$040F	HMBalloonPict
$0410	HMScanTemplateItems
$0711	HMExtractHelpMsg
$0B01	HMShowBalloon
$0E05	HMShowMenuBalloon
$1306	HMGetIndHelpMsg

Result Codes
noErr 0 No error
fnOpnErr -38 File not open
paramErr -50 Error in parameter list
memFullErr -108 Not enough room in heap zone
resNotFound -192 Unable to read resource
hmHelpDisabled -850 Help balloons are not enabled
hmBalloonAborted -853 Because of constant cursor movement, the help balloon wasn't displayed
hmSameAsLastBalloon -854 Menu and item are same as previous menu and item
hmHelpManagerNotInited -855 Help menu not set up
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
hmOperationUnsupported -861 Invalid value passed in the method parameter
hmNoBalloonUp -862 No balloon showing
hmCloseViewActive -863 Balloon can't be removed because Close View is in use

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

0	hmmHelpType	word	Resource type
2	hmmHelpMessage	variable	Help balloon message

noErr	0	No error
fnOpnErr	-38	File not open
paramErr	-50	Error in parameter list
memFullErr	-108	Not enough room in heap zone
resNotFound	-192	Unable to read resource
hmHelpDisabled	-850	Help balloons are not enabled
hmBalloonAborted	-853	Because of constant cursor movement, the help balloon wasn't displayed
hmSameAsLastBalloon	-854	Menu and item are same as previous menu and item
hmHelpManagerNotInited	-855	Help menu not set up
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
hmOperationUnsupported	-861	Invalid value passed in the method parameter
hmNoBalloonUp	-862	No balloon showing
hmCloseViewActive	-863	Balloon can't be removed because Close View is in use

Legacy Document

Summary of the Help Manager

Pascal Summary

Constants

Data Types

Help Manager Routines

Determining Help Balloon Status

Displaying and Removing Help Balloons

Enabling and Disabling Balloon Help Assistance

Adding Items to the Help Menu

Getting and Setting the Font Name and Size

Setting and Getting Information for Help Resources

Determining the Size of a Help Balloon

Getting the Message of a Help Balloon

Application-Defined Routines

C Summary

Constants

Data Types

Help Manager Routines

Determining Help Balloon Status

Displaying and Removing Help Balloons

Enabling and Disabling Balloon Help Assistance

Adding Items to the Help Menu

Getting and Setting the Font Name and Size

Setting and Getting Information for Help Resources

Determining the Size of a Help Balloon

Getting the Message of a Help Balloon

Application-Defined Routines

Assembly-Language Summary

Data Structures

Help Message Data Structure 0hmmHelpTypewordResource type 2hmmHelpMessagevariableHelp balloon message

Trap Macros

Trap Macros Requiring Routine Selectors

Help Message Data Structure
0 hmmHelpType word Resource type
2 hmmHelpMessage variable Help balloon message