Carbon Help Manager Reference

Overview

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)

Functions by Task

Obtaining a Reference to the Help Menu

• HMGetHelpMenu

Attaching Help Tag Content Directly to an Object

• HMSetControlHelpContent
• HMSetWindowHelpContent
• HMSetMenuItemHelpContent
• HMGetControlHelpContent
• HMGetWindowHelpContent
• HMGetMenuItemHelpContent

Installing and Retrieving Help Tag Callbacks

• HMInstallControlContentCallback
• HMInstallWindowContentCallback
• HMInstallMenuItemContentCallback
• HMInstallMenuTitleContentCallback
• HMGetControlContentCallback
• HMGetWindowContentCallback
• HMGetMenuItemContentCallback
• HMGetMenuTitleContentCallback

Displaying and Hiding Help Tags

• HMDisplayTag
• HMHideTag

Enabling and Disabling Help Tags

• HMAreHelpTagsDisplayed
• HMSetHelpTagsDisplayed

Getting and Setting Help Tag Delay Time

• HMSetTagDelay
• HMGetTagDelay

Working With Universal Procedure Pointers to Help Tag Callback Functions

• NewHMControlContentUPP
• NewHMWindowContentUPP
• NewHMMenuItemContentUPP
• NewHMMenuTitleContentUPP
• DisposeHMControlContentUPP
• DisposeHMWindowContentUPP
• DisposeHMMenuItemContentUPP
• DisposeHMMenuTitleContentUPP
• InvokeHMControlContentUPP
• InvokeHMWindowContentUPP
• InvokeHMMenuItemContentUPP
• InvokeHMMenuTitleContentUPP

Functions

DisposeHMControlContentUPP

Disposes of a universal procedure pointer (UPP) to a help tag callback for a control.

void DisposeHMControlContentUPP (
   HMControlContentUPP userUPP
);

Parameters

userUPP

The UPP to dispose of.

Discussion

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.

DisposeHMMenuItemContentUPP

Disposes of a universal procedure pointer (UPP) to a help tag callback for a menu item.

void DisposeHMMenuItemContentUPP (
   HMMenuItemContentUPP userUPP
);

Parameters

userUPP

The UPP to dispose of.

Discussion

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.

DisposeHMMenuTitleContentUPP

Disposes of a universal procedure pointer (UPP) to a help tag callback for a menu title.

void DisposeHMMenuTitleContentUPP (
   HMMenuTitleContentUPP userUPP
);

Parameters

userUPP

The UPP to dispose of.

Discussion

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.

DisposeHMWindowContentUPP

Disposes of a universal procedure pointer (UPP) to a help tag callback for a window.

void DisposeHMWindowContentUPP (
   HMWindowContentUPP userUPP
);

Parameters

userUPP

The UPP to dispose of.

Discussion

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.

Related Sample Code

• Carbon Porting Tutorial

HMAreHelpTagsDisplayed

Determines whether help tags are currently enabled.

Boolean HMAreHelpTagsDisplayed (
   void
);

HMDisplayTag

Displays a help tag at an application-defined location.

OSStatus HMDisplayTag (
   const HMHelpContentRec *inContent
);

Parameters

inContent

A pointer to a help tag structure that describes the help tag you want to display.

Discussion

Use the HMDisplayTag function to display a help tag at a location not associated with a control, window, or menu.

HMGetControlContentCallback

Retrieves the help tag callback associated with a control.

OSStatus HMGetControlContentCallback (
   ControlRef inControl,
   HMControlContentUPP *outContentUPP
);

Parameters

inControl

A reference to the control for which to retrieve the help tag callback.

outContentUPP

On return, a universal procedure pointer to the help tag callback.

Discussion

To install a help tag callback for a control, use the HMInstallControlContentCallback function.

HMGetControlHelpContent

Returns the help tag associated with a control.

OSStatus HMGetControlHelpContent (
   ControlRef inControl,
   HMHelpContentRec *outContent
);

Parameters

inControl

A reference to the control for which to retrieve the help tag.

outContent

A pointer to a help tag structure. On return, this structure describes the help tag for the control.

Discussion

To attach a help tag to a control, use the HMSetControlHelpContent function.

HMGetHelpMenu

Returns a reference to the Help menu.

OSStatus HMGetHelpMenu (
   MenuRef *outHelpMenu,
   MenuItemIndex *outFirstCustomItemIndex
);

Parameters

outHelpMenu

On return, a pointer to a menu reference to the Help menu.

outFirstCustomItemIndex

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.

Discussion

The HMGetHelpMenu function returns a reference to the Help menu, to which you can add your own custom menu items.

Related Sample Code

• GrabBag

HMGetMenuItemContentCallback

Retrieves the help tag callback associated with a menu’s items.

OSStatus HMGetMenuItemContentCallback (
   MenuRef inMenu,
   HMMenuItemContentUPP *outContentUPP
);

Parameters

inMenu

A reference to the menu for which to retrieve the menu item help tag callback.

outContentUPP

On return, a universal procedure pointer to the help tag callback.

Discussion

To install a menu item help tag callback, use the HMInstallMenuItemContentCallback function.

HMGetMenuItemHelpContent

Returns the help tag associated with a menu item.

OSStatus HMGetMenuItemHelpContent (
   MenuRef inMenu,
   MenuItemIndex inItem,
   HMHelpContentRec *outContent
);

Parameters

inMenu

A reference to the menu containing the menu item for which to retrieve the help tag.

inItem

The index of the menu item.

outContent

A pointer to a help tag structure. On return, this structure describes the help tag for the menu item.

Discussion

To attach a help tag to a menu item, use the HMSetMenuItemHelpContent function.

HMGetMenuTitleContentCallback

Retrieves the help tag callback associated with a menu’s title.

OSStatus HMGetMenuTitleContentCallback (
   MenuRef inMenu,
   HMMenuTitleContentUPP *outContentUPP
);

Parameters

inMenu

A reference to the menu for which to retrieve the help tag callback.

outContentUPP

On return, a universal procedure pointer to the help tag callback.

Discussion

To install a menu title help tag callback, use the HMInstallMenuTitleContentCallback function.

HMGetTagDelay

Returns the current help tag delay time.

OSStatus HMGetTagDelay (
   Duration *outDelay
);

Parameters

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.

Discussion

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.

HMGetWindowContentCallback

Retrieves the help tag callback associated with a window.

OSStatus HMGetWindowContentCallback (
   WindowRef inWindow,
   HMWindowContentUPP *outContentUPP
);

Parameters

inWindow

A reference to the window for which to retrieve the help tag callback.

outContentUPP

On return, a universal procedure pointer to the help tag callback.

Discussion

To install a help tag callback for a window, use the HMInstallWindowContentCallback function.

HMGetWindowHelpContent

Returns the help tag associated with a window.

OSStatus HMGetWindowHelpContent (
   WindowRef inWindow,
   HMHelpContentRec *outContent
);

Parameters

inWindow

A reference to the window for which to retrieve the help tag.

outContent

A pointer to a help tag structure. On return, this structure describes the help tag for the window.

Discussion

To attach a help tag to a window, use the HMSetWindowHelpContent function.

HMHideTag

Hides the most recently displayed help tag.

OSStatus HMHideTag (
   void
);

Discussion

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.

HMInstallControlContentCallback

Installs a help tag callback for a control.

OSStatus HMInstallControlContentCallback (
   ControlRef inControl,
   HMControlContentUPP inContentUPP
);

Parameters

inControl

A reference to the control for which to install the help tag callback.

inContentUPP

A universal procedure pointer to the help tag callback.

Discussion

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.

HMInstallMenuItemContentCallback

Installs a help tag callback for a menu’s items.

OSStatus HMInstallMenuItemContentCallback (
   MenuRef inMenu,
   HMMenuItemContentUPP inContentUPP
);

Parameters

inMenu

A reference to the menu for which to install the help tag callback.

inContentUPP

A universal procedure pointer to the help tag callback.

Discussion

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.

Special Considerations

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.

HMInstallMenuTitleContentCallback

Installs a help tag callback for a menu title.

OSStatus HMInstallMenuTitleContentCallback (
   MenuRef inMenu,
   HMMenuTitleContentUPP inContentUPP
);

Parameters

inMenu

A reference to the menu for which to install the help tag callback.

inContentUPP

A universal procedure pointer to the help tag callback.

Discussion

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.

Special Considerations

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.

HMInstallWindowContentCallback

Installs a help tag callback for a window.

OSStatus HMInstallWindowContentCallback (
   WindowRef inWindow,
   HMWindowContentUPP inContentUPP
);

Parameters

inWindow

A reference to the window for which to install the help tag callback.

inContentUPP

A universal procedure pointer to the help tag content callback.

Discussion

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.

Related Sample Code

• Carbon Porting Tutorial

HMSetControlHelpContent

Associates a help tag with a control.

OSStatus HMSetControlHelpContent (
   ControlRef inControl,
   const HMHelpContentRec *inContent
);

Parameters

inControl

A reference to the control with which you want to associate the help tag.

inContent

A pointer to a help tag structure that describes the help tag for the control.

Discussion

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.

Related Sample Code

• Carbon Porting Tutorial

HMSetHelpTagsDisplayed

Enables or disables help tags.

OSStatus HMSetHelpTagsDisplayed (
   Boolean inDisplayTags
);

Parameters

inDisplayTags

Pass true to enable help tags; false to disable help tags.

Discussion

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.

HMSetMenuItemHelpContent

Associates a help tag with a menu item.

OSStatus HMSetMenuItemHelpContent (
   MenuRef inMenu,
   MenuItemIndex inItem,
   const HMHelpContentRec *inContent
);

Parameters

inMenu

A reference to the menu containing the menu item with which to associate the help tag.

inItem

The index of the menu item.

inContent

A pointer to a help tag structure that describes the help tag for the menu item.

Discussion

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.

Special Considerations

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.

HMSetTagDelay

Sets the help tag delay time.

OSStatus HMSetTagDelay (
   Duration inDelay
);

Parameters

inDelay

The help tag delay time. A positive value represents the delay time in milliseconds; a negative value represents the delay time in microseconds.

Discussion

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.

HMSetWindowHelpContent

Associates a help tag with a window.

OSStatus HMSetWindowHelpContent (
   WindowRef inWindow,
   const HMHelpContentRec *inContent
);

Parameters

inWindow

A reference to the window with which to associate the help tag.

inContent

A pointer to a help tag structure that describes the help tag for the window.

Discussion

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.

InvokeHMControlContentUPP

Calls your help tag callback for a control.

OSStatus InvokeHMControlContentUPP (
   ControlRef inControl,
   Point inGlobalMouse,
   HMContentRequest inRequest,
   HMContentProvidedType *outContentProvided,
   HMHelpContentRec *ioHelpContent,
   HMControlContentUPP userUPP
);

Parameters

inControl

A reference to the control for which the callback should supply help tag content.

inGlobalMouse

The current mouse position, in global coordinates.

inRequest

A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.

outContentProvided

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.

ioHelpContent

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.

userUPP

A universal procedure pointer to the help tag callback to invoke.

Discussion

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.

InvokeHMMenuItemContentUPP

Calls your help tag callback for a menu item.

OSStatus InvokeHMMenuItemContentUPP (
   const MenuTrackingData *inTrackingData,
   HMContentRequest inRequest,
   HMContentProvidedType *outContentProvided,
   HMHelpContentRec *ioHelpContent,
   HMMenuItemContentUPP userUPP
);

Parameters

inTrackingData

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.

inRequest

A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.

outContentProvided

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.

ioHelpContent

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.

userUPP

A universal procedure pointer to the help tag callback to invoke.

Discussion

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.

InvokeHMMenuTitleContentUPP

Calls your help tag callback for a menu title.

OSStatus InvokeHMMenuTitleContentUPP (
   MenuRef inMenu,
   HMContentRequest inRequest,
   HMContentProvidedType *outContentProvided,
   HMHelpContentRec *ioHelpContent,
   HMMenuTitleContentUPP userUPP
);

Parameters

inMenu

A reference to the menu for which to provide a help tag.

inRequest

A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.

outContentProvided

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

ioHelpContent

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.

userUPP

A universal procedure pointer to the help tag callback to invoke.

Discussion

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.

InvokeHMWindowContentUPP

Calls your help tag callback for a window.

OSStatus InvokeHMWindowContentUPP (
   WindowRef inWindow,
   Point inGlobalMouse,
   HMContentRequest inRequest,
   HMContentProvidedType *outContentProvided,
   HMHelpContentRec *ioHelpContent,
   HMWindowContentUPP userUPP
);

Parameters

inWindow

A reference to the window for which the callback should provide a help tag.

inGlobalMouse

The current mouse position, in global coordinates.

inRequest

A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.

outContentProvided

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.

ioHelpContent

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.

userUPP

A universal procedure pointer to the help tag callback to invoke.

Discussion

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.

NewHMControlContentUPP

Creates a new universal procedure pointer (UPP) to a help tag callback for a control.

HMControlContentUPP NewHMControlContentUPP (
   HMControlContentProcPtr userRoutine
);

Parameters

userRoutine

A pointer to your help tag callback. See HMControlContentProcPtr data type fir a description.

Discussion

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.

NewHMMenuItemContentUPP

Creates a new universal procedure pointer (UPP) to a help tag callback for a menu item.

HMMenuItemContentUPP NewHMMenuItemContentUPP (
   HMMenuItemContentProcPtr userRoutine
);

Parameters

userRoutine

A pointer to your help tag callback.

Discussion

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.

NewHMMenuTitleContentUPP

Creates a new universal procedure pointer (UPP) to a help tag callback for a menu title.

HMMenuTitleContentUPP NewHMMenuTitleContentUPP (
   HMMenuTitleContentProcPtr userRoutine
);

Parameters

userRoutine

A pointer to your help tag callback.

Discussion

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.

NewHMWindowContentUPP

Creates a new universal procedure pointer (UPP) to a help tag callback for a window.

HMWindowContentUPP NewHMWindowContentUPP (
   HMWindowContentProcPtr userRoutine
);

Parameters

userRoutine

A pointer to your help tag callback.

Discussion

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.

Related Sample Code

• Carbon Porting Tutorial

Callbacks

HMControlContentProcPtr

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
);

Parameters

inControl

A reference to the control for which your callback should supply help tag content.

inGlobalMouse

The current mouse position, in global coordinates.

inRequest

A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.

outContentProvided

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.”

ioHelpContent

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.

Discussion

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.

HMMenuItemContentProcPtr

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
);

Parameters

inTrackingData

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.

inRequest

A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.

outContentProvided

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.”

ioHelpContent

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.

Discussion

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.

HMMenuTitleContentProcPtr

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
);

Parameters

inMenu

A reference to the menu for which to provide help tag content.

inRequest

A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.

outContentProvided

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.”

ioHelpContent

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.

Discussion

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.

HMWindowContentProcPtr

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
);

Parameters

inWindow

A reference to the window for which your callback should provide help tag content.

inGlobalMouse

The current mouse position, in global coordinates.

inRequest

A value that specifies the type of the help tag content request. See “Content Request Types” for a description of the possible requests.

outContentProvided

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.”

ioHelpContent

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.

Discussion

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.

Data Types

HMHelpContentRec

Describes a help tag.

struct HMHelpContentRec {
   SInt32 version;
   Rect absHotRect;
   HMTagDisplaySide tagSide;
   HMHelpContent content[2];
};
typedef struct HMHelpContentRec HMHelpContentRec;

Fields

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).

Special Considerations

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.

HMHelpContentPtr

A pointer to a help tag structure.

typedef HMHelpContentRec* HMHelpContentPtr;

Discussion

See HMHelpContentRec for more information.

HMHelpContent

Contains a help tag message.

struct HMHelpContent {
   HMContentType contentType;
   union {
      CFStringRef tagCFString;
      Str255 tagString;
      HMStringResType tagStringRes;
      TEHandle tagTEHandle;
      SInt16 tagTextRes;
      SInt16 tagStrRes;
   } u;
};

Fields

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.

Discussion

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.

HMControlContentUPP

Defines a universal procedure pointer to the help tag callback for a control.

typedef struct OpaqueHMControlContentProcPtr* HMControlContentUPP;

Discussion

For more information, see the description of the HMControlContentProcPtr callback function.

HMWindowContentUPP

Defines a universal procedure pointer to the help tag callback for a window.

typedef struct OpaqueHMWindowContentProcPtr* HMWindowContentUPP;

Discussion

For more information, see the description of the HMWindowContentProcPtr callback function.

HMMenuItemContentUPP

Defines a universal procedure pointer to the help tag callback for a menu item.

typedef struct OpaqueHMMenuItemContentProcPtr* HMMenuItemContentUPP;

Discussion

For more information, see the description of the HMMenuItemContentProcPtr callback function.

HMMenuTitleContentUPP

Defines a universal procedure pointer to the help tag callback for a menu title.

typedef struct OpaqueHMMenuTitleContentProcPtr* HMMenuTitleContentUPP;

Discussion

For more information, see the description of the HMMenuTitleContentProcPtr callback function.

Constants

Help Manager Version

Represents the current version of the HMHelpContentRec structure.

enum {
   kMacHelpVersion = 3
};

Constants

kMacHelpVersion

The current structure version.

Available in Mac OS X v10.0 and later.

Declared in MacHelp.h.

Discussion

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.

Content Request Types

Identify the type of request made to a help tag callback.

typedef SInt16 HMContentRequest;
enum {
   kHMSupplyContent =                 0,
   kHMDisposeContent =                 1
};

Constants

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.

Discussion

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.

Help Tag Content Types

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 '
};

Constants

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.

Discussion

These constants are used in the contentType field of the HMHelpContent structure to identify the format of the help content contained in that structure.

Help Tag Display Locations

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
};

Constants

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.

Discussion

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.

Content Provided Types

Indicate whether or not help tag content has been supplied.

typedef SInt16 HMContentProvidedType;
enum {
   kHMContentProvided = 0,
   kHMContentNotProvided = 1,
   kHMContentNotProvidedDontPropagate = 2
};

Constants

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.

Discussion

Your help tag callback function should return one of these constants in its outContentProvided parameter.

Help Tag Content Indexes

Identify an index into the array of help tag content structures in a help tag.

enum {
   kHMMinimumContentIndex = 0,
   kHMMaximumContentIndex = 1
};

Constants

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.

Discussion

These constants are used to access the minimum or maximum content of a help tag, in the content field of the HMHelpContentRec structure.

Obsolete Help Tag Display Locations

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
};

Discussion

These constants have been replaced by the constants described in “Help Tag Display Locations”; you should use those constants instead.

Result Codes

The most common result codes returned by the Carbon Help Manager are listed in the table below.

---