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