/* File: MacHelp.h Contains: Macintosh Help Package Interfaces. Version: Technology: CarbonLib 1.0 Release: QuickTime 6.0.2 Copyright: (c) 1998-2001 by Apple Computer, Inc., all rights reserved Bugs?: For bug reports, consult the following page on the World Wide Web: http://developer.apple.com/bugreporter/ */ #ifndef __MACHELP__ #define __MACHELP__ #ifndef __CONTROLS__ #include #endif #ifndef __DIALOGS__ #include #endif #ifndef __EVENTS__ #include #endif #ifndef __MACWINDOWS__ #include #endif #ifndef __MENUS__ #include #endif #ifndef __MOVIES__ #include #endif #if PRAGMA_ONCE #pragma once #endif #ifdef __cplusplus extern "C" { #endif #if PRAGMA_IMPORT #pragma import on #endif #if PRAGMA_STRUCT_ALIGN #pragma options align=mac68k #elif PRAGMA_STRUCT_PACKPUSH #pragma pack(push, 2) #elif PRAGMA_STRUCT_PACK #pragma pack(2) #endif /*----------------------------------------------------------------------------------*/ /* Help Manager constants, etc. */ /*----------------------------------------------------------------------------------*/ #ifndef __BALLOONS__ enum { kMacHelpVersion = 0x0003, hmBalloonHelpVersion = kMacHelpVersion /* Backwards compatibility */ }; #endif /* !defined(__BALLOONS__) */ typedef SInt16 HMContentRequest; enum { kHMSupplyContent = 0, kHMDisposeContent = 1 }; typedef UInt32 HMContentType; enum { kHMNoContent = FOUR_CHAR_CODE('none'), kHMPascalStrContent = FOUR_CHAR_CODE('pstr'), kHMPictResContent = FOUR_CHAR_CODE('pict'), kHMStringResContent = FOUR_CHAR_CODE('str#'), kHMTEHandleContent = FOUR_CHAR_CODE('txth'), kHMPictHandleContent = FOUR_CHAR_CODE('pcth'), kHMTextResContent = FOUR_CHAR_CODE('text'), kHMStrResContent = FOUR_CHAR_CODE('str '), kHMMovieContent = FOUR_CHAR_CODE('moov') }; typedef SInt16 HMTagDisplaySide; enum { kHMDefaultSide = 0, kHMTopSide = 1, kHMLeftSide = 2, kHMBottomSide = 3, kHMRightSide = 4, kHMTopLeftCorner = 5, kHMTopRightCorner = 6, kHMLeftTopCorner = 7, kHMLeftBottomCorner = 8, kHMBottomLeftCorner = 9, kHMBottomRightCorner = 10, kHMRightTopCorner = 11, kHMRightBottomCorner = 12 }; typedef SInt16 HMContentProvidedType; enum { kHMContentProvided = 0, kHMContentNotProvided = 1, kHMContentNotProvidedDontPropagate = 2 }; enum { kHMMinimumContentIndex = 0, kHMMaximumContentIndex = 1 }; enum { kHMIllegalContentForMinimumState = -1000 /* *** Need real numbers here*/ }; enum { kHMHelpPropertyContentTag = FOUR_CHAR_CODE('help') }; #ifndef __BALLOONS__ struct HMStringResType { short hmmResID; short hmmIndex; }; typedef struct HMStringResType HMStringResType; #endif /* !defined(__BALLOONS__) */ struct HMHelpContent { HMContentType contentType; union { Str255 tagString; /* Pascal String*/ SInt16 tagPictID; /* 'PICT' resource ID*/ HMStringResType tagStringRes; /* STR# resource ID and index*/ TEHandle tagTEHandle; /* TextEdit handle*/ PicHandle tagPictHandle; /* Picture handle*/ SInt16 tagTextRes; /* TEXT/styl resource ID*/ SInt16 tagStrRes; /* STR resource ID*/ Movie tagMovie; /* QuickTime movie*/ } u; }; typedef struct HMHelpContent HMHelpContent; struct HMHelpContentRec { SInt32 version; Rect absHotRect; HMTagDisplaySide tagSide; HMHelpContent content[2]; }; typedef struct HMHelpContentRec HMHelpContentRec; typedef HMHelpContentRec * HMHelpContentPtr; /*------------------------------------------------------------------------------------------*/ /* Callback procs */ /*------------------------------------------------------------------------------------------ */ typedef CALLBACK_API( OSStatus , HMControlContentProcPtr )(ControlRef inControl, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent); typedef CALLBACK_API( OSStatus , HMWindowContentProcPtr )(WindowPtr inWindow, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent); typedef CALLBACK_API( OSStatus , HMMenuTitleContentProcPtr )(MenuHandle inMenu, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent); typedef CALLBACK_API( OSStatus , HMMenuItemContentProcPtr )(const MenuTrackingData *inTrackingData, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent); typedef STACK_UPP_TYPE(HMControlContentProcPtr) HMControlContentUPP; typedef STACK_UPP_TYPE(HMWindowContentProcPtr) HMWindowContentUPP; typedef STACK_UPP_TYPE(HMMenuTitleContentProcPtr) HMMenuTitleContentUPP; typedef STACK_UPP_TYPE(HMMenuItemContentProcPtr) HMMenuItemContentUPP; #if OPAQUE_UPP_TYPES EXTERN_API(HMControlContentUPP) NewHMControlContentUPP (HMControlContentProcPtr userRoutine); EXTERN_API(HMWindowContentUPP) NewHMWindowContentUPP (HMWindowContentProcPtr userRoutine); EXTERN_API(HMMenuTitleContentUPP) NewHMMenuTitleContentUPP (HMMenuTitleContentProcPtr userRoutine); EXTERN_API(HMMenuItemContentUPP) NewHMMenuItemContentUPP (HMMenuItemContentProcPtr userRoutine); EXTERN_API(void) DisposeHMControlContentUPP (HMControlContentUPP userUPP); EXTERN_API(void) DisposeHMWindowContentUPP (HMWindowContentUPP userUPP); EXTERN_API(void) DisposeHMMenuTitleContentUPP (HMMenuTitleContentUPP userUPP); EXTERN_API(void) DisposeHMMenuItemContentUPP (HMMenuItemContentUPP userUPP); EXTERN_API(OSStatus) InvokeHMControlContentUPP (ControlRef inControl, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType * outContentProvided, HMHelpContentPtr ioHelpContent, HMControlContentUPP userUPP); EXTERN_API(OSStatus) InvokeHMWindowContentUPP (WindowPtr inWindow, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType * outContentProvided, HMHelpContentPtr ioHelpContent, HMWindowContentUPP userUPP); EXTERN_API(OSStatus) InvokeHMMenuTitleContentUPP (MenuHandle inMenu, HMContentRequest inRequest, HMContentProvidedType * outContentProvided, HMHelpContentPtr ioHelpContent, HMMenuTitleContentUPP userUPP); EXTERN_API(OSStatus) InvokeHMMenuItemContentUPP (const MenuTrackingData * inTrackingData, HMContentRequest inRequest, HMContentProvidedType * outContentProvided, HMHelpContentPtr ioHelpContent, HMMenuItemContentUPP userUPP); #else enum { uppHMControlContentProcInfo = 0x0000FBF0 }; /* pascal 4_bytes Func(4_bytes, 4_bytes, 2_bytes, 4_bytes, 4_bytes) */ enum { uppHMWindowContentProcInfo = 0x0000FBF0 }; /* pascal 4_bytes Func(4_bytes, 4_bytes, 2_bytes, 4_bytes, 4_bytes) */ enum { uppHMMenuTitleContentProcInfo = 0x00003EF0 }; /* pascal 4_bytes Func(4_bytes, 2_bytes, 4_bytes, 4_bytes) */ enum { uppHMMenuItemContentProcInfo = 0x00003EF0 }; /* pascal 4_bytes Func(4_bytes, 2_bytes, 4_bytes, 4_bytes) */ #define NewHMControlContentUPP(userRoutine) (HMControlContentUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppHMControlContentProcInfo, GetCurrentArchitecture()) #define NewHMWindowContentUPP(userRoutine) (HMWindowContentUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppHMWindowContentProcInfo, GetCurrentArchitecture()) #define NewHMMenuTitleContentUPP(userRoutine) (HMMenuTitleContentUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppHMMenuTitleContentProcInfo, GetCurrentArchitecture()) #define NewHMMenuItemContentUPP(userRoutine) (HMMenuItemContentUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppHMMenuItemContentProcInfo, GetCurrentArchitecture()) #define DisposeHMControlContentUPP(userUPP) DisposeRoutineDescriptor(userUPP) #define DisposeHMWindowContentUPP(userUPP) DisposeRoutineDescriptor(userUPP) #define DisposeHMMenuTitleContentUPP(userUPP) DisposeRoutineDescriptor(userUPP) #define DisposeHMMenuItemContentUPP(userUPP) DisposeRoutineDescriptor(userUPP) #define InvokeHMControlContentUPP(inControl, inGlobalMouse, inRequest, outContentProvided, ioHelpContent, userUPP) (OSStatus)CALL_FIVE_PARAMETER_UPP((userUPP), uppHMControlContentProcInfo, (inControl), (inGlobalMouse), (inRequest), (outContentProvided), (ioHelpContent)) #define InvokeHMWindowContentUPP(inWindow, inGlobalMouse, inRequest, outContentProvided, ioHelpContent, userUPP) (OSStatus)CALL_FIVE_PARAMETER_UPP((userUPP), uppHMWindowContentProcInfo, (inWindow), (inGlobalMouse), (inRequest), (outContentProvided), (ioHelpContent)) #define InvokeHMMenuTitleContentUPP(inMenu, inRequest, outContentProvided, ioHelpContent, userUPP) (OSStatus)CALL_FOUR_PARAMETER_UPP((userUPP), uppHMMenuTitleContentProcInfo, (inMenu), (inRequest), (outContentProvided), (ioHelpContent)) #define InvokeHMMenuItemContentUPP(inTrackingData, inRequest, outContentProvided, ioHelpContent, userUPP) (OSStatus)CALL_FOUR_PARAMETER_UPP((userUPP), uppHMMenuItemContentProcInfo, (inTrackingData), (inRequest), (outContentProvided), (ioHelpContent)) #endif /* support for pre-Carbon UPP routines: NewXXXProc and CallXXXProc */ #define NewHMControlContentProc(userRoutine) NewHMControlContentUPP(userRoutine) #define NewHMWindowContentProc(userRoutine) NewHMWindowContentUPP(userRoutine) #define NewHMMenuTitleContentProc(userRoutine) NewHMMenuTitleContentUPP(userRoutine) #define NewHMMenuItemContentProc(userRoutine) NewHMMenuItemContentUPP(userRoutine) #define CallHMControlContentProc(userRoutine, inControl, inGlobalMouse, inRequest, outContentProvided, ioHelpContent) InvokeHMControlContentUPP(inControl, inGlobalMouse, inRequest, outContentProvided, ioHelpContent, userRoutine) #define CallHMWindowContentProc(userRoutine, inWindow, inGlobalMouse, inRequest, outContentProvided, ioHelpContent) InvokeHMWindowContentUPP(inWindow, inGlobalMouse, inRequest, outContentProvided, ioHelpContent, userRoutine) #define CallHMMenuTitleContentProc(userRoutine, inMenu, inRequest, outContentProvided, ioHelpContent) InvokeHMMenuTitleContentUPP(inMenu, inRequest, outContentProvided, ioHelpContent, userRoutine) #define CallHMMenuItemContentProc(userRoutine, inTrackingData, inRequest, outContentProvided, ioHelpContent) InvokeHMMenuItemContentUPP(inTrackingData, inRequest, outContentProvided, ioHelpContent, userRoutine) /*------------------------------------------------------------------------------------------*/ /* API */ /*------------------------------------------------------------------------------------------*/ /* Installing/Retrieving Content */ EXTERN_API( OSStatus ) HMSetControlHelpContent (ControlRef inControl, const HMHelpContentRec * inContent); EXTERN_API( OSStatus ) HMGetControlHelpContent (ControlRef inControl, HMHelpContentRec * outContent); EXTERN_API( OSStatus ) HMSetWindowHelpContent (WindowRef inWindow, const HMHelpContentRec * inContent); EXTERN_API( OSStatus ) HMGetWindowHelpContent (WindowRef inWindow, HMHelpContentRec * outContent); EXTERN_API( OSStatus ) HMSetMenuItemHelpContent (MenuRef inMenu, MenuItemIndex inItem, const HMHelpContentRec * inContent); EXTERN_API( OSStatus ) HMGetMenuItemHelpContent (MenuRef inMenu, MenuItemIndex inItem, HMHelpContentRec * outContent); /* Installing/Retrieving Content Callbacks */ EXTERN_API( OSStatus ) HMInstallControlContentCallback (ControlRef inControl, HMControlContentUPP inContentUPP); EXTERN_API( OSStatus ) HMInstallWindowContentCallback (WindowRef inWindow, HMWindowContentUPP inContentUPP); EXTERN_API( OSStatus ) HMInstallMenuTitleContentCallback (MenuRef inMenu, HMMenuTitleContentUPP inContentUPP); EXTERN_API( OSStatus ) HMInstallMenuItemContentCallback (MenuRef inMenu, HMMenuItemContentUPP inContentUPP); EXTERN_API( OSStatus ) HMGetControlContentCallback (ControlRef inControl, HMControlContentUPP * outContentUPP); EXTERN_API( OSStatus ) HMGetWindowContentCallback (WindowRef inWindow, HMWindowContentUPP * outContentUPP); EXTERN_API( OSStatus ) HMGetMenuTitleContentCallback (MenuRef inMenu, HMMenuTitleContentUPP * outContentUPP); EXTERN_API( OSStatus ) HMGetMenuItemContentCallback (MenuRef inMenu, HMMenuItemContentUPP * outContentUPP); /* Enabling and Disabling Help Tags */ EXTERN_API( Boolean ) HMAreHelpTagsDisplayed (void); EXTERN_API( OSStatus ) HMSetHelpTagsDisplayed (Boolean inDisplayTags); EXTERN_API( OSStatus ) HMSetTagDelay (Duration inDelay); EXTERN_API( OSStatus ) HMGetTagDelay (Duration * outDelay); /* Compatibility */ EXTERN_API( OSStatus ) HMSetMenuHelpFromBalloonRsrc (MenuRef inMenu, SInt16 inHmnuRsrcID); EXTERN_API( OSStatus ) HMSetDialogHelpFromBalloonRsrc (DialogRef inDialog, SInt16 inHdlgRsrcID, SInt16 inItemStart); #if PRAGMA_STRUCT_ALIGN #pragma options align=reset #elif PRAGMA_STRUCT_PACKPUSH #pragma pack(pop) #elif PRAGMA_STRUCT_PACK #pragma pack() #endif #ifdef PRAGMA_IMPORT_OFF #pragma import off #elif PRAGMA_IMPORT #pragma import reset #endif #ifdef __cplusplus } #endif #endif /* __MACHELP__ */