Framework |
Carbon/Carbon.h |
Declared in | MacHelp.h |
The Carbon Help Manager is an API that provides an interface for displaying short onscreen hints in help tags. You can attach identifying text to individual windows, menus, or controls. Help tags replace Balloon Help, introduced with System 7.
This document is relevant for developers creating a user interface for their Carbon application. To use this document, you should be familiar with the basics of programming with the fundamental objects of the Mac OS user interface (windows, menus, controls, and so forth)
HMSetControlHelpContent
HMSetWindowHelpContent
HMSetMenuItemHelpContent
HMGetControlHelpContent
HMGetWindowHelpContent
HMGetMenuItemHelpContent
HMInstallControlContentCallback
HMInstallWindowContentCallback
HMInstallMenuItemContentCallback
HMInstallMenuTitleContentCallback
HMGetControlContentCallback
HMGetWindowContentCallback
HMGetMenuItemContentCallback
HMGetMenuTitleContentCallback
NewHMControlContentUPP
NewHMWindowContentUPP
NewHMMenuItemContentUPP
NewHMMenuTitleContentUPP
DisposeHMControlContentUPP
DisposeHMWindowContentUPP
DisposeHMMenuItemContentUPP
DisposeHMMenuTitleContentUPP
InvokeHMControlContentUPP
InvokeHMWindowContentUPP
InvokeHMMenuItemContentUPP
InvokeHMMenuTitleContentUPP
Disposes of a universal procedure pointer (UPP) to a help tag callback for a control.
void DisposeHMControlContentUPP ( HMControlContentUPP userUPP );
The UPP to dispose of.
To create a UPP to a help tag callback for a control, use NewHMControlContentUPP
. For a description of the help tag callback for a control, see HMControlContentProcPtr
.
MacHelp.h
Disposes of a universal procedure pointer (UPP) to a help tag callback for a menu item.
void DisposeHMMenuItemContentUPP ( HMMenuItemContentUPP userUPP );
The UPP to dispose of.
To create a UPP to a help tag callback for a menu item, use NewHMMenuItemContentUPP
. For a description of the help tag callback for a menu item, see HMMenuItemContentProcPtr
.
MacHelp.h
Disposes of a universal procedure pointer (UPP) to a help tag callback for a menu title.
void DisposeHMMenuTitleContentUPP ( HMMenuTitleContentUPP userUPP );
The UPP to dispose of.
To create a UPP to a help tag callback for a menu title, use NewHMMenuTitleContentUPP
. For a description of the help tag callback for a menu title, see HMMenuTitleContentProcPtr
.
MacHelp.h
Disposes of a universal procedure pointer (UPP) to a help tag callback for a window.
void DisposeHMWindowContentUPP ( HMWindowContentUPP userUPP );
The UPP to dispose of.
To create a UPP to a help tag callback for a window, use NewHMWindowContentUPP
. For a description of the help tag callback for a window, see HMWindowContentProcPtr
.
MacHelp.h
Determines whether help tags are currently enabled.
Boolean HMAreHelpTagsDisplayed ( void );
true
if help tags are currently enabled; otherwise, false
.
MacHelp.h
Displays a help tag at an application-defined location.
OSStatus HMDisplayTag ( const HMHelpContentRec *inContent );
A pointer to a help tag structure that describes the help tag you want to display.
A result code. See “Result Codes.”
Use the HMDisplayTag
function to display a help tag at a location not associated with a control, window, or menu.
MacHelp.h
Retrieves the help tag callback associated with a control.
OSStatus HMGetControlContentCallback ( ControlRef inControl, HMControlContentUPP *outContentUPP );
A reference to the control for which to retrieve the help tag callback.
On return, a universal procedure pointer to the help tag callback.
A result code. See “Result Codes.”
To install a help tag callback for a control, use the HMInstallControlContentCallback
function.
MacHelp.h
Returns the help tag associated with a control.
OSStatus HMGetControlHelpContent ( ControlRef inControl, HMHelpContentRec *outContent );
A reference to the control for which to retrieve the help tag.
A pointer to a help tag structure. On return, this structure describes the help tag for the control.
A result code. See “Result Codes.”
To attach a help tag to a control, use the HMSetControlHelpContent
function.
MacHelp.h
Returns a reference to the Help menu.
OSStatus HMGetHelpMenu ( MenuRef *outHelpMenu, MenuItemIndex *outFirstCustomItemIndex );
On return, a pointer to a menu reference to the Help menu.
On return, a pointer to the menu item index that will be used by the first application-supplied item added to the menu. This parameter may be NULL
.
A result code. See “Result Codes.”
The HMGetHelpMenu
function returns a reference to the Help menu, to which you can add your own custom menu items.
MacHelp.h
Retrieves the help tag callback associated with a menu’s items.
OSStatus HMGetMenuItemContentCallback ( MenuRef inMenu, HMMenuItemContentUPP *outContentUPP );
A reference to the menu for which to retrieve the menu item help tag callback.
On return, a universal procedure pointer to the help tag callback.
A result code. See “Result Codes.”
To install a menu item help tag callback, use the HMInstallMenuItemContentCallback
function.
MacHelp.h
Returns the help tag associated with a menu item.
OSStatus HMGetMenuItemHelpContent ( MenuRef inMenu, MenuItemIndex inItem, HMHelpContentRec *outContent );
A reference to the menu containing the menu item for which to retrieve the help tag.
The index of the menu item.
A pointer to a help tag structure. On return, this structure describes the help tag for the menu item.
A result code. See “Result Codes.”
To attach a help tag to a menu item, use the HMSetMenuItemHelpContent
function.
MacHelp.h
Retrieves the help tag callback associated with a menu’s title.
OSStatus HMGetMenuTitleContentCallback ( MenuRef inMenu, HMMenuTitleContentUPP *outContentUPP );
A reference to the menu for which to retrieve the help tag callback.
On return, a universal procedure pointer to the help tag callback.
A result code. See “Result Codes.”
To install a menu title help tag callback, use the HMInstallMenuTitleContentCallback
function.
MacHelp.h
Returns the current help tag delay time.
OSStatus HMGetTagDelay ( Duration *outDelay );
On return, a pointer to the help tag delay time. A positive value represents the delay time in milliseconds; a negative value represents the delay time in microseconds.
A result code. See “Result Codes.”
The help tag delay time returned by the HMGetTagDelay
function is the amount of time that the mouse must remain motionless over a control, window, menu title, or menu item before the associated help tag is displayed.
MacHelp.h
Retrieves the help tag callback associated with a window.
OSStatus HMGetWindowContentCallback ( WindowRef inWindow, HMWindowContentUPP *outContentUPP );
A reference to the window for which to retrieve the help tag callback.
On return, a universal procedure pointer to the help tag callback.
A result code. See “Result Codes.”
To install a help tag callback for a window, use the HMInstallWindowContentCallback
function.
MacHelp.h
Returns the help tag associated with a window.
OSStatus HMGetWindowHelpContent ( WindowRef inWindow, HMHelpContentRec *outContent );
A reference to the window for which to retrieve the help tag.
A pointer to a help tag structure. On return, this structure describes the help tag for the window.
A result code. See “Result Codes.”
To attach a help tag to a window, use the HMSetWindowHelpContent
function.
MacHelp.h
Hides the most recently displayed help tag.
OSStatus HMHideTag ( void );
A result code. See “Result Codes.”
The Carbon Help Manager automatically removes help tags from the screen when user input occurs. To hide a tag before the Carbon Help Manager removes it, use the HMHideTag
function. HMHideTag
removes the most recently displayed help tag from the screen. If no help tag is currently visible, HMHideTag
does nothing.
MacHelp.h
Installs a help tag callback for a control.
OSStatus HMInstallControlContentCallback ( ControlRef inControl, HMControlContentUPP inContentUPP );
A reference to the control for which to install the help tag callback.
A universal procedure pointer to the help tag callback.
A result code. See “Result Codes.”
HMInstallControlContentCallback
associates your help tag callback with the control specified in the inControl
parameter. Thereafter, whenever the user hovers the mouse over this control, the Carbon Help Manager calls your callback to determine the content to display in the help tag for the control. For a description of the help tag callback for a control, see HMControlContentProcPtr
.
MacHelp.h
Installs a help tag callback for a menu’s items.
OSStatus HMInstallMenuItemContentCallback ( MenuRef inMenu, HMMenuItemContentUPP inContentUPP );
A reference to the menu for which to install the help tag callback.
A universal procedure pointer to the help tag callback.
A result code. See “Result Codes.”
HMInstallMenuItemContentCallback
associates your help tag callback with the menu specified in the inMenu
parameter. Thereafter, whenever the user hovers the mouse over a menu item in this menu, the Carbon Help Manager calls your callback to determine the content to display in the help tag for the menu item. For a description of the help tag callback for a menu item, see HMMenuItemContentProcPtr
.
Although the HMInstallMenuItemContentCallback
function is available in CarbonLib, CarbonLib currently does not support menu item help tags. Any help tag content you supply for a menu item using a help tag callback in CarbonLib is not displayed.
MacHelp.h
Installs a help tag callback for a menu title.
OSStatus HMInstallMenuTitleContentCallback ( MenuRef inMenu, HMMenuTitleContentUPP inContentUPP );
A reference to the menu for which to install the help tag callback.
A universal procedure pointer to the help tag callback.
A result code. See “Result Codes.”
HMInstallMenuTitleContentCallback
associates your help tag callback with the menu specified in the inMenu
parameter. Thereafter, whenever the user hovers the mouse over the title of this menu in the menu bar, the Carbon Help Manager calls your callback to determine the content to display in the help tag for the menu title. For a description of the help tag callback for a menu title, see HMMenuTitleContentProcPtr
.
Although the HMInstallMenuTitleContentCallback
function is available in CarbonLib, CarbonLib does not support menu title help tags. Any help tag content you supply for a menu title using a help tag callback in CarbonLib is not displayed.
MacHelp.h
Installs a help tag callback for a window.
OSStatus HMInstallWindowContentCallback ( WindowRef inWindow, HMWindowContentUPP inContentUPP );
A reference to the window for which to install the help tag callback.
A universal procedure pointer to the help tag content callback.
A result code. See “Result Codes.”
HMInstallWindowContentCallback
associates your help tag callback with the window specified in the inWindow
parameter. Thereafter, whenever the user hovers the mouse over this window, the Carbon Help Manager calls this callback to determine the content to display in the help tag for the window. For a description of the help tag callback for a window, see HMWindowContentProcPtr
.
MacHelp.h
Associates a help tag with a control.
OSStatus HMSetControlHelpContent ( ControlRef inControl, const HMHelpContentRec *inContent );
A reference to the control with which you want to associate the help tag.
A pointer to a help tag structure that describes the help tag for the control.
A result code. See “Result Codes.”
Once you attach a help tag to a control using the HMSetControlHelpContent
function, this help tag is displayed by the Carbon Help Manager whenever the user hovers the mouse over the control while help tags are enabled.
Use HMSetControlHelpContent
to supply the content for a help tag when you create a control. To supply the content for a help tag only when the tag is about to be displayed to the user, install a help tag callback for the control with the function HMInstallControlContentCallback
.
MacHelp.h
Enables or disables help tags.
OSStatus HMSetHelpTagsDisplayed ( Boolean inDisplayTags );
Pass true
to enable help tags; false
to disable help tags.
A result code. See “Result Codes.”
Help tags are enabled by default when an application is launched; your application does not need to call HMSetHelpTagsDisplayed
to turn on help tag display. Disabling help tags with HMSetHelpTagsDisplayed
only turns off help tags in your application; help tag display in other applications is unaffected.
MacHelp.h
Associates a help tag with a menu item.
OSStatus HMSetMenuItemHelpContent ( MenuRef inMenu, MenuItemIndex inItem, const HMHelpContentRec *inContent );
A reference to the menu containing the menu item with which to associate the help tag.
The index of the menu item.
A pointer to a help tag structure that describes the help tag for the menu item.
A result code. See “Result Codes.”
Once you attach a help tag to a menu item using the HMSetMenuItemHelpContent
function, this help tag is displayed by the Carbon Help Manager whenever the user hovers the mouse over the menu item while help tags are enabled.
Use HMSetMenuItemHelpContent
to supply the content for a help tag when you create a menu. To supply the content for a help tag only when the tag is about to be displayed to the user, install a help tag callback for the menu’s items with the function HMInstallMenuItemContentCallback
.
CarbonLib does not support menu item help tags. Any help tag content you supply with the HMSetMenuItemHelpContent
function in CarbonLib is not displayed.
In versions of Mac OS X version 10.1 and earlier, the Carbon Help Manager does not correctly interpret an empty rectangle in the absHotRect
field of the help tag structure passed to HMSetMenuItemHelpContent
when setting the help content for a menu title. Because there is no Menu Manager function for determining the bounds of a menu title, Apple recommends that you install a help tag callback to supply help content for a menu title. See HMMenuTitleContentProcPtr
for a description of the help tag callback for a menu title.
MacHelp.h
Sets the help tag delay time.
OSStatus HMSetTagDelay ( Duration inDelay );
The help tag delay time. A positive value represents the delay time in milliseconds; a negative value represents the delay time in microseconds.
A result code. See “Result Codes.”
The help tag delay time is the amount of time that the mouse must remain motionless over a control, window, menu title, or menu item before the associated help tag is displayed.
MacHelp.h
Associates a help tag with a window.
OSStatus HMSetWindowHelpContent ( WindowRef inWindow, const HMHelpContentRec *inContent );
A reference to the window with which to associate the help tag.
A pointer to a help tag structure that describes the help tag for the window.
A result code. See “Result Codes.”
Once you attach a help tag to a window using the HMSetWindowHelpContent
function, this help tag is displayed by the Carbon Help Manager whenever the user hovers the mouse over the window while help tags are enabled.
Use HMSetWindowHelpContent
to supply the content for a help tag when you create a window. To supply the content for a help tag only when the tag is about to be displayed to the user, install a help tag callback for the window with the function HMInstallWindowContentCallback
.
MacHelp.h
Calls your help tag callback for a control.
OSStatus InvokeHMControlContentUPP ( ControlRef inControl, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentRec *ioHelpContent, HMControlContentUPP userUPP );
A reference to the control for which the callback should supply help tag content.
The current mouse position, in global coordinates.
A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.
On output, a pointer to a value that indicates whether the help tag callback was able to fulfill the request specified in the inRequest
parameter. See “Content Provided Types” for a description of the values returned here.
A pointer to a help tag structure that describes the help tag for the control. On input, you must supply a value in the version
field. On output, if the value of the outContentProvided
parameter is kHMContentProvided
, the help tag structure describes the help tag for the control.
A universal procedure pointer to the help tag callback to invoke.
A result code. See “Result Codes.”
Use this function to invoke your help tag callback for a control, rather than calling your callback directly, to ensure code compatibility across different compiler targets. Typically, you do not need to invoke a help tag callback yourself. If you associate your callback with a control, using the HMInstallControlContentCallback
function, the operating system calls your callback when it is needed. For more information on the help tag callback for a control, see HMControlContentProcPtr
.
MacHelp.h
Calls your help tag callback for a menu item.
OSStatus InvokeHMMenuItemContentUPP ( const MenuTrackingData *inTrackingData, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentRec *ioHelpContent, HMMenuItemContentUPP userUPP );
A pointer to the tracking information for the menu for which the callback should provide a menu-item help tag. The specific menu item for which the callback should provide a help tag is at the index number given in the itemUnderMouse
field of the tracking data structure.
A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.
On output, a pointer to a value that indicates whether the help tag callback was able to fulfill the request specified in the inRequest
parameter. See “Content Provided Types” for a description of the values returned here.
A pointer to a help tag structure that describes the help tag for the menu item. On input, you must supply a value in the version
field. On output, if the value of the outContentProvided
parameter is kHMContentProvided
, the help tag structure describes the menu-item help tag.
A universal procedure pointer to the help tag callback to invoke.
A result code. See “Result Codes.”
Use this function to invoke your help tag callback for a menu item, rather than calling your callback directly, to ensure code compatibility across different compiler targets. Typically, you do not need to invoke a help tag callback yourself. If you associate your callback with a menu’s items, using the HMInstallMenuItemContentCallback
function, the operating system calls your callback when it is needed. For more information on the help tag callback for a menu item, see HMMenuItemContentProcPtr
.
MacHelp.h
Calls your help tag callback for a menu title.
OSStatus InvokeHMMenuTitleContentUPP ( MenuRef inMenu, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentRec *ioHelpContent, HMMenuTitleContentUPP userUPP );
A reference to the menu for which to provide a help tag.
A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.
On output, a pointer to a value that indicates whether the help tag callback was able to fulfill the request specified in the inRequest
parameter. See “Content Provided Types” for a description of the values returned here
A pointer to a help tag structure that describes the help tag for the menu title. On input, you must supply a value in the version
field. On output, if the value of the outContentProvided
parameter is kHMContentProvided
, the help tag structure describes the menu-title help tag.
A universal procedure pointer to the help tag callback to invoke.
A result code. See “Result Codes.”
Use this function to invoke your help tag callback for a menu title, rather than calling your callback directly, to ensure code compatibility across different compiler targets. Typically, you do not need to invoke a help tag callback yourself. If you associate your callback with a menu, using the HMInstallMenuTitleContentCallback
function, the operating system calls your callback when it is needed. For more information on the help tag callback for a menu title, see HMMenuTitleContentProcPtr
.
MacHelp.h
Calls your help tag callback for a window.
OSStatus InvokeHMWindowContentUPP ( WindowRef inWindow, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentRec *ioHelpContent, HMWindowContentUPP userUPP );
A reference to the window for which the callback should provide a help tag.
The current mouse position, in global coordinates.
A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.
On output, a pointer to a value that indicates whether the help tag callback was able to fulfill the request specified in the inRequest
parameter. See “Content Provided Types” for a description of the values returned here.
A pointer to a help tag structure that describes the help tag for the window. On input, you must supply a value in the version
field. On output, if the value of the outContentProvided
parameter is kHMContentProvided
, the help tag structure describes the help tag for the window.
A universal procedure pointer to the help tag callback to invoke.
A result code. See “Result Codes.”
Use this function to invoke your help tag callback for a window, rather than calling your callback directly, to ensure code compatibility across different compiler targets. Typically, you do not need to invoke a help tag callback yourself. If you associate your callback with a window, using the HMInstallWindowContentCallback
function, the operating system calls your callback when it is needed. For more information on the help tag callback for a window, see HMWindowContentProcPtr
.
MacHelp.h
Creates a new universal procedure pointer (UPP) to a help tag callback for a control.
HMControlContentUPP NewHMControlContentUPP ( HMControlContentProcPtr userRoutine );
A pointer to your help tag callback. See HMControlContentProcPtr
data type fir a description.
On return, a UPP to the help tag callback. See HMControlContentUPP
data type for a description.
Pass the UPP returned by NewHMControlContentUPP
to the HMInstallControlContentCallback
function to install your help tag callback with a control. When you are finished with the help tag callback—for example, when you dispose of the control—you should dispose of the UPP with the DisposeHMControlContentUPP
function.
MacHelp.h
Creates a new universal procedure pointer (UPP) to a help tag callback for a menu item.
HMMenuItemContentUPP NewHMMenuItemContentUPP ( HMMenuItemContentProcPtr userRoutine );
A pointer to your help tag callback.
On return, a UPP to the help tag callback. See the HMMenuItemContentUPP
data type for a description.
Pass the UPP returned by NewHMMenuItemContentUPP
to the HMInstallMenuItemContentCallback
function to install your help tag callback with a menu’s items. When you are finished with the help tag callback—for example, when you dispose of the menu—you should dispose of the UPP with the DisposeHMMenuItemContentUPP
function.
MacHelp.h
Creates a new universal procedure pointer (UPP) to a help tag callback for a menu title.
HMMenuTitleContentUPP NewHMMenuTitleContentUPP ( HMMenuTitleContentProcPtr userRoutine );
A pointer to your help tag callback.
On return, a UPP to the help tag callback. See the HMMenuTitleContentUPP
data type for a description
Pass the UPP returned by NewHMMenuTitleContentUPP
to the HMInstallMenuTitleContentCallback
function to install your help tag callback with a menu’s title. When you are finished with the help tag callback—for example, when you dispose of the menu—you should dispose of the UPP with the DisposeHMMenuTitleContentUPP
function.
MacHelp.h
Creates a new universal procedure pointer (UPP) to a help tag callback for a window.
HMWindowContentUPP NewHMWindowContentUPP ( HMWindowContentProcPtr userRoutine );
A pointer to your help tag callback.
On return, a UPP to the help tag callback function. See the HMWindowContentUPP
data type for a description.
Pass the UPP returned by NewHMWindowContentUPP
to the HMInstallWindowContentCallback
function to install your help tag callback with a window. When you are finished with the help tag callback—for example, when you dispose of the window—you should dispose of the UPP with the DisposeHMWindowContentUPP
function.
MacHelp.h
Defines a pointer to the help tag callback for a control. Your help tag callback provides help tag content for a control.
typedef OSStatus(* HMControlContentProcPtr) ( ControlRef inControl, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent );
If you name your function MyHMControlContentCallback
,
you would declare it like this:
OSStatus MyHMControlContentCallback ( ControlRef inControl, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent );
A reference to the control for which your callback should supply help tag content.
The current mouse position, in global coordinates.
A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.
On output, a pointer to a value that indicates
whether your help tag callback was able to fulfill the request specified
in the inRequest
parameter.
Your callback should return one of the constants described in “Content Provided Types.”
A pointer to a help tag structure that describes
the help tag for the control. On input, the Carbon Help Manager
supplies a value in the version
field.
If the value of the inRequest
parameter
is kHMSupplyContent
,
your callback must fill in the remaining fields of the structure
or specify that it was unable to fulfill the help tag content request.
A result code. See “Result Codes.”
When the user hovers the mouse over a control for which you’ve
registered a help tag callback, the Carbon Help Manager calls your
callback with a kHMSupplyContent
request
in the inRequest
parameter.
To supply a help tag, your callback should fill in the fields of
the help tag structure pointed to in the ioHelpContent
parameter.
When the help tag for the control is no longer needed, the
Carbon Help Manager calls your callback with a kHMDisposeContent
request.
When you receive this request, you should free any memory allocated
for the help tag content and perform any other cleanup necessary before
the Carbon Help Manager removes the help tag from the screen.
If your help tag callback handles the content request, your
callback should return the constant kHMContentProvided
in
the outContentProvided
parameter.
Otherwise, your callback should indicate that it was unable to handle
the help tag content request by returning the constant kHMContentNotProvided
in
the outContentProvided
parameter.
To register a help tag callback with a control, pass a universal
procedure pointer (UPP) to your callback function to the HMInstallControlContentCallback
function.
You can create a UPP to your callback function with the NewHMControlContentUPP
function.
MacHelp.h
Defines a pointer to the help tag callback for a menu item. Your help tag callback provides help tag content for a menu item.
typedef OSStatus(* HMMenuItemContentProcPtr) ( const MenuTrackingData *inTrackingData, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent );
If you name your function MyHMMenuItemContentCallback
,
you would declare it like this:
OSStatus MyHMMenuItemContentCallback ( const MenuTrackingData *inTrackingData, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent );
A pointer to the tracking information for
the menu for which your callback should provide a menu-item help
tag. The specific menu item for which your callback should provide
a help tag is at the index number given in the itemUnderMouse
field
of the tracking data structure.
A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.
On output, a pointer to a value that indicates
whether your help tag callback was able to fulfill the request specified
in the inRequest
parameter.
Your callback should return one of the constants described in “Content Provided Types.”
A pointer to a help tag structure that describes
the help tag for the menu item. On input, the Carbon Help Manager
supplies a value in the version
field.
If the value of the inRequest
parameter
is kHMSupplyContent
,
your callback must fill in the remaining fields of the structure
or specify that it was unable to fulfill the help tag content request.
A result code. See “Result Codes.”
When the user hovers the mouse over a menu item in a menu
for which you’ve registered a help tag callback, the Carbon Help
Manager calls your callback with a kHMSupplyContent
request
in the inRequest
parameter.
To supply a help tag, your callback should fill in the remaining
fields of the help tag structure pointed to in the ioHelpContent
parameter.
When the help tag for the menu item is no longer needed, the
Carbon Help Manager calls your callback with a kHMDisposeContent
request.
When you receive this request, you should free any memory allocated
for the help tag content and perform any other cleanup necessary
before the Carbon Help Manager removes the help tag from the screen.
If your help tag callback handles the request for help tag
content, your callback should return the constant kHMContentProvided
in
the outContentProvided
parameter.
Otherwise, your callback should indicate that it was unable to handle
the help tag content request by returning the constant kHMContentNotProvided
in
the outContentProvided
parameter.
To register a menu-item help tag callback with a menu, pass
a universal procedure pointer (UPP) to your callback function to
the HMInstallMenuItemContentCallback
function.
You can create a UPP to your callback function with the NewHMMenuItemContentUPP
function.
MacHelp.h
Defines a pointer to the help tag callback for a menu title. Your help tag callback provides help tag content for a menu’s title.
typedef OSStatus(* HMMenuTitleContentProcPtr) ( MenuRef inMenu, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent );
If you name your function MyHMMenuTitleContentCallback
,
you would declare it like this:
OSStatus MyHMMenuTitleContentCallback ( MenuRef inMenu, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent );
A reference to the menu for which to provide help tag content.
A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.
On output, a pointer to a value that indicates
whether your help tag callback was able to fulfill the request specified
in the inRequest
parameter.
Your callback should return one of the constants described in “Content Provided Types.”
A pointer to a help tag structure that describes
the help tag for the menu title. On input, the Carbon Help Manager
supplies a value in the version
field. If
the value of the inRequest
parameter
is kHMSupplyContent
,
your callback must fill in the remaining fields of the structure
or specify that it was unable to fulfill the help tag content request.
A result code. See “Result Codes.”
When the user hovers the mouse over the title of a menu for
which you’ve registered a help tag callback, the Carbon Help Manager
calls your callback with a kHMSupplyContent
request in
the inRequest
parameter.
To supply a help tag, your callback should fill in the remaining fields
of the help tag structure pointed to in the ioHelpContent
parameter.
When the help tag for the menu title is no longer needed,
the Carbon Help Manager calls your callback with a kHMDisposeContent
request.
When you receive this request, you should free any memory allocated
for the help tag content and perform any other cleanup necessary
before the Carbon Help Manager removes the help tag from the screen.
If your help tag callback handles the request for help tag
content, your callback should return the constant kHMContentProvided
in
the outContentProvided
parameter.
Otherwise, your callback should indicate that it was unable to handle
the help tag content request by returning the constant kHMContentNotProvided
in
the outContentProvided
parameter.
To register a menu title help tag callback with a menu, pass
a universal procedure pointer (UPP) to your callback function to
the HMInstallMenuTitleContentCallback
function.
You can create a UPP to your callback function with the NewHMMenuTitleContentUPP
function.
MacHelp.h
Defines a pointer to the help tag callback for a window. Your help tag callback provides help tag content for a window.
typedef OSStatus(* HMWindowContentProcPtr) ( WindowRef inWindow, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent );
If you name your function MyHMWindowContentCallback
,
you would declare it like this:
OSStatus MyHMWindowContentCallback ( WindowRef inWindow, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent );
A reference to the window for which your callback should provide help tag content.
The current mouse position, in global coordinates.
A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.
On output, a pointer to a value that indicates
whether your help tag callback was able to fulfill the request specified
in the inRequest
parameter.
Your callback should return one of the constants described in “Content Provided Types.”
A pointer to a help tag structure that describes
the help tag for the window. On input, the Carbon Help Manager supplies
a value in the version
field.
If the value of the inRequest
parameter
is kHMSupplyContent
,
your callback must fill in the remaining fields of the structure
or specify that it was unable to fulfill the help tag content request.
A result code. See “Result Codes.”
When the user hovers the mouse over a window for which you’ve
registered a help tag callback, the Carbon Help Manager calls your
callback with a kHMSupplyContent
request
in the inRequest
parameter.
To supply a help tag, your callback should fill in the fields of
the help tag structure pointed to in the ioHelpContent
parameter.
When the help tag for the window is no longer needed, the
Carbon Help Manager calls your callback with a kHMDisposeContent
request.
When you receive this request, you should free any memory allocated
for the help tag content and perform any other cleanup necessary
before the Carbon Help Manager removes the help tag from the screen.
If your help tag callback handles the request for help tag
content, your callback should return the constant kHMContentProvided
in
the outContentProvided
parameter.
Otherwise, your callback should indicate that it was unable to handle
the help tag content request by returning the constant kHMContentNotProvided
in
the outContentProvided
parameter.
To register a help tag callback with a window, pass a universal
procedure pointer (UPP) to your callback function to the HMInstallWindowContentCallback
function.
You can create a UPP to your callback function with the NewHMWindowContentUPP
function.
MacHelp.h
Describes a help tag.
struct HMHelpContentRec { SInt32 version; Rect absHotRect; HMTagDisplaySide tagSide; HMHelpContent content[2]; }; typedef struct HMHelpContentRec HMHelpContentRec;
version
The structure version.
absHotRect
The hot rectangle for the help tag, expressed in global coordinates. The hot rectangle defines the area on the screen over which the user must hover the mouse to trigger the Carbon Help Manager to display the help tag.
You may pass an empty rectangle—a rectangle with coordinates (0,0,0,0)—in this field. The Carbon Help Manager automatically substitutes the current location of the control, window, or menu item for the empty rectangle when the help tag is displayed.
tagSide
A value that specifies which side of the hot rectangle the help tag is displayed. For a description of the constants used here, see “Help Tag Display Locations.”
content
An array of two help tag content structures describing the help message for the tag. The first structure describes the content displayed by default in the help tag (the minimum content). The second structure describes additional content that is displayed in the help tag if the user holds down the Command key while the help tag is displayed (the maximum, or expanded, content).
On Mac OS X version 10.1.x and earlier, you cannot supply
an empty hot rectangle from a help tag callback. You can, however,
supply an empty hot rectangle to the HMSetControlHelpContent
, HMSetWindowHelpContent
,
and HMSetMenuItemHelpContent
functions.
When you supply an empty hot rectangle for a control help
tag, the Carbon Help Manager uses the function LocalToGlobal
to
convert the control’s bounds from window-local coordinates into
global coordinates. LocalToGlobal
only
returns true global coordinates if the port origin is (0,0). If
your application sets the port origin to a non-zero value, it should
do so only temporarily; your application should never leave the
port origin set to a non-zero value across calls to the event system
that may attempt to display a help tag. Setting the port origin
to a non-zero value typically prevents help tags from being displayed.
MacHelp.h
A pointer to a help tag structure.
typedef HMHelpContentRec* HMHelpContentPtr;
See HMHelpContentRec
for
more information.
MacHelp.h
Contains a help tag message.
struct HMHelpContent { HMContentType contentType; union { CFStringRef tagCFString; Str255 tagString; HMStringResType tagStringRes; TEHandle tagTEHandle; SInt16 tagTextRes; SInt16 tagStrRes; } u; };
contentType
A value that indicates the format of the help content contained in the structure. The help tag content formats that are allowed are described by the constants “Help Tag Content Types.”
tagCFString
If the value of the contentType
field
is kHMCFStringContent
,
a CFString specifying the help tag message. If the value of the contentType
field
is kHMCFStringLocalizedContent
,
a CFString containing the name of the localized help tag message
in the Localizable.strings
file.
tagString
If the value of the contentType
field
is kHMPascalStrContent
,
a Pascal string specifying the help tag message.
tagStringRes
If the value of the contentType
field
is kHMStringResContent
,
a ‘STR#
’ resource
ID and an index number specifying the help tag message.
tagTEHandle
If the value of the contentType
field
is kHMTEHandleContent
,
a TextEdit handle specifying the help tag message. This type of
help tag content is only supported in CarbonLib and in Mac OS X
version 10.2 and later.
tagTextRes
If the value of the contentType
field
is kHMTextResContent
,
the resource ID of a ‘TEXT
’
resource and a ‘styl
’
resource describing the help tag message. This type of help tag
content is only supported in CarbonLib and in Mac OS X version 10.2
and later.
tagStrRes
If the value of the contentType
field
is kHMStrResContent
,
a ‘STR
‘ resource
ID, specifying the help tag message.
The HMHelpContent
structure
is used in the content
field
of the HMHelpContentRec
structure
to hold the help content associated with a help tag. The HMHelpContent
structure
describes a single help message.
Defines a universal procedure pointer to the help tag callback for a control.
typedef struct OpaqueHMControlContentProcPtr* HMControlContentUPP;
For more information, see the description of the HMControlContentProcPtr
callback
function.
MacHelp.h
Defines a universal procedure pointer to the help tag callback for a window.
typedef struct OpaqueHMWindowContentProcPtr* HMWindowContentUPP;
For more information, see the description of the HMWindowContentProcPtr
callback
function.
MacHelp.h
Defines a universal procedure pointer to the help tag callback for a menu item.
typedef struct OpaqueHMMenuItemContentProcPtr* HMMenuItemContentUPP;
For more information, see the description of the HMMenuItemContentProcPtr
callback
function.
MacHelp.h
Defines a universal procedure pointer to the help tag callback for a menu title.
typedef struct OpaqueHMMenuTitleContentProcPtr* HMMenuTitleContentUPP;
For more information, see the description of the HMMenuTitleContentProcPtr
callback
function.
MacHelp.h
Represents the current version of the HMHelpContentRec
structure.
enum { kMacHelpVersion = 3 };
kMacHelpVersion
The current structure version.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
When the Carbon Help Manager calls your help tag callback,
it supplies the kMacHelpVersion
constant
in the version
field
of the HMHelpContentRec
structure
it passes to your callback.
Identify the type of request made to a help tag callback.
typedef SInt16 HMContentRequest; enum { kHMSupplyContent = 0, kHMDisposeContent = 1 };
kHMSupplyContent
The help tag callback should supply help content.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMDisposeContent
The help tag callback should dispose of help content.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
These constants are passed to your help tag callback in the inRequest
parameter
to indicate the nature of the help tag content request. In particular,
the Carbon Help Manager passes kHMSupplyContent
when
the user pauses with the mouse above a user interface object for which
a help tag callback is registered. When the user moves the mouse
away from the object, the Carbon Help Manager passes kHMDisposeContent
to
your callback.
Identify the type of content contained in a help tag.
typedef UInt32 HMContentType; enum { kHMNoContent = 'none', kHMCFStringContent = 'cfst', kHMCFStringLocalizedContent = ‘cfsl’, kHMPascalStrContent = 'pstr', kHMStringResContent = 'str#', kHMTEHandleContent = 'txth', kHMTextResContent = 'text', kHMStrResContent = 'str ' };
kHMNoContent
The help tag contains no content.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMCFStringContent
The help tag content is a CFString object.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMCFStringLocalizedContent
The help tag content is a localized string
contained in the Localizeable.strings
file. The content
field
of the help tag structure contains a CFString key which the Carbon
Help Manager uses to retrieve the help tag string from the Localizable.strings
file
in the appropriate language folder.
Available in Mac OS X v10.2 and later.
Declared in MacHelp.h
.
kHMPascalStrContent
The help tag content is a Pascal string.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMStringResContent
The help tag content is a text string, stored
in the list of strings in a resource of type 'STR#
'.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMTEHandleContent
The help tag content is contained in a TextEdit record, referred to by a TextEdit handle. This type of help tag content is only supported in CarbonLib and in Mac OS X version 10.2 and later.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMTextResContent
The help tag content is styled text, described
by the combination of a text resource ('TEXT
')
and a style resource ('styl
').
This type of help tag content is only supported in CarbonLib and
in Mac OS X version 10.2 and later.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMStrResContent
The help tag content is a text string stored
in a resource of type 'STR
'.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
These constants are used in the contentType
field
of the HMHelpContent
structure
to identify the format of the help content contained in that structure.
Specify which side of the hot rectangle to display the help tag.
typedef SInt16 HMTagDisplaySide; enum { kHMDefaultSide = 0, kHMOutsideTopScriptAligned = 1, kHMOutsideLeftCenterAligned = 2, kHMOutsideBottomScriptAligned = 3, kHMOutsideRightCenterAligned = 4, kHMOutsideTopLeftAligned = 5, kHMOutsideTopRightAligned = 6, kHMOutsideLeftTopAligned = 7, kHMOutsideLeftBottomAligned = 8, kHMOutsideBottomLeftAligned = 9, kHMOutsideBottomRightAligned = 10, kHMOutsideRightTopAligned = 11, kHMOutsideRightBottomAligned = 12, kHMOutsideTopCenterAligned = 13, kHMOutsideBottomCenterAligned = 14, kHMInsideRightCenterAligned = 15, kHMInsideLeftCenterAligned = 16, kHMInsideBottomCenterAligned = 17, kHMInsideTopCenterAligned = 18, kHMInsideTopLeftCorner = 19, kHMInsideTopRightCorner = 20, kHMInsideBottomLeftCorner = 21, kHMInsideBottomRightCorner = 22, kHMAbsoluteCenterAligned = 23 };
kHMDefaultSide
Display the help tag at the default system location. The system default is below the hot rectangle, horizontally centered.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideTopScriptAligned
Display the help tag above the hot rectangle, aligned with the right or left side, depending upon the direction of the system script.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideLeftCenterAligned
Display the help tag to the left of the hot rectangle, centered vertically.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideBottomScriptAligned
Display the help tag below the hot rectangle, aligned with the right or left side, depending upon the direction of the system script.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideRightCenterAligned
Display the help tag to the right of the hot rectangle, centered vertically.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideTopLeftAligned
Display the help tag above the hot rectangle, with their left edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideTopRightAligned
Display the help tag above the hot rectangle, with their right edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideLeftTopAligned
Display the help tag to the left of the hot rectangle, with their top edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideLeftBottomAligned
Display the help tag to the left of the hot rectangle, with their bottom edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideBottomLeftAligned
Display the help tag below the hot rectangle, with their left edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideBottomRightAligned
Display the help tag below the hot rectangle, with their right edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideRightTopAligned
Display the help tag to the right of the hot rectangle, with their top edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideRightBottomAligned
Display the help tag to the right of the hot rectangle, with their bottom edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideTopCenterAligned
Display the help tag above the hot rectangle, centered horizontally.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMOutsideBottomCenterAligned
Display the help tag below the hot rectangle, centered horizontally.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMInsideRightCenterAligned
Display the help tag inside the hot rectangle, with their right edges aligned and centered vertically.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMInsideLeftCenterAligned
Display the help tag inside the hot rectangle, with their left edges aligned and centered vertically.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMInsideBottomCenterAligned
Display the help tag inside the hot rectangle, with their bottom edges aligned and centered horizontally.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMInsideTopCenterAligned
Display the help tag inside the hot rectangle, with their top edges aligned and centered horizontally.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMInsideTopLeftCorner
Display the help tag inside the hot rectangle, with their top and left edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMInsideTopRightCorner
Display the help tag inside the hot rectangle, with their top and right edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMInsideBottomLeftCorner
Display the help tag inside the hot rectangle, with their bottom and left edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMInsideBottomRightCorner
Display the help tag inside the hot rectangle, with their bottom and right edges aligned.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMAbsoluteCenterAligned
Display the help tag centered vertically and horizontally within the hot rectangle.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
The locations described by these constants are relative to
the help tag’s hot rectangle, which defines, in global coordinates,
the area on the screen with which the help tag is associated. These
constants are used in the tagSide
field
of the HMHelpContentRec
structure.
Indicate whether or not help tag content has been supplied.
typedef SInt16 HMContentProvidedType; enum { kHMContentProvided = 0, kHMContentNotProvided = 1, kHMContentNotProvidedDontPropagate = 2 };
kHMContentProvided
Help tag content has been provided.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMContentNotProvided
Help tag content was not provided. When your callback returns this constant, the Carbon Help Manager calls up to the next help tag callback in the hierarchy. If that callback also fails to provide help content, the Carbon Help Manager continues to propagate the request for help tag content until the request is fulfilled, the top of the hierarchy is reached, or a help tag callback tells the Carbon Help Manager to stop propagating the request.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMContentNotProvidedDontPropagate
Help tag content was not provided. When your callback returns this constant, the Carbon Help Manager assumes that there is no help content for the control, window, menu title, or menu item and does not propagate the request.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
Your help tag callback function should return one of these
constants in its outContentProvided
parameter.
Identify an index into the array of help tag content structures in a help tag.
enum { kHMMinimumContentIndex = 0, kHMMaximumContentIndex = 1 };
kHMMinimumContentIndex
The index of the help tag’s minimum (or default) content.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
kHMMaximumContentIndex
The index of the help tag’s maximum (or expanded) content.
Available in Mac OS X v10.0 and later.
Declared in MacHelp.h
.
These constants are used to access the minimum or maximum
content of a help tag, in the content
field
of the HMHelpContentRec
structure.
Indicate the side of the hot rectangle on which the help tag should be displayed.
enum { kHMTopSide = 1, kHMLeftSide = 2, kHMBottomSide = 3, kHMRightSide = 4, kHMTopLeftCorner = 5, kHMTopRightCorner = 6, kHMLeftTopCorner = 7, kHMLeftBottomCorner = 8, kHMBottomLeftCorner = 9, kHMBottomRightCorner = 10, kHMRightTopCorner = 11, kHMRightBottomCorner = 12 };
These constants have been replaced by the constants described in “Help Tag Display Locations”; you should use those constants instead.
The most common result codes returned by the Carbon Help Manager are listed in the table below.
© 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-03-01)