Next Page >

Hide TOC

Carbon Help Manager Reference

Framework	Carbon/Carbon.h
Declared in	MacHelp.h

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

Attaching Help Tag Content Directly to an Object

Installing and Retrieving Help Tag Callbacks

Displaying and Hiding Help Tags

Enabling and Disabling Help Tags

Getting and Setting Help Tag Delay Time

Working With Universal Procedure Pointers to Help Tag Callback Functions

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

HMAreHelpTagsDisplayed

Determines whether help tags are currently enabled.

Boolean HMAreHelpTagsDisplayed (
   void
);

Return Value

true if help tags are currently enabled; otherwise, false.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

Discussion

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

Availability

Available in CarbonLib 1.5 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

Discussion

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

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

Discussion

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

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

Discussion

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

Availability

Available in CarbonLib 1.1 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

Discussion

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

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

Discussion

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

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

Discussion

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

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

Discussion

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

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

Discussion

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

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

HMHideTag

Hides the most recently displayed help tag.

OSStatus HMHideTag (
   void
);

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.5 and later.
Available in Mac OS X 10.1 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

HMSetHelpTagsDisplayed

Enables or disables help tags.

OSStatus HMSetHelpTagsDisplayed (
   Boolean inDisplayTags
);

Parameters

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

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

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.

Return Value

On return, a UPP to the help tag callback. See HMControlContentUPP data type for 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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

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.

Return Value

On return, a UPP to the help tag callback. See the HMMenuItemContentUPP data type for a description.

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

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.

Return Value

On return, a UPP to the help tag callback. See the HMMenuTitleContentUPP data type for a description

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

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.

Return Value

On return, a UPP to the help tag callback function. See the HMWindowContentUPP data type for a description.

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.

Availability

Available in CarbonLib 1.0.2 and later.
Available in Mac OS X 10.0 and later.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

MacHelp.h

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.

Return Value

A result code. See “Result Codes.”

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.

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

MacHelp.h

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

MacHelp.h

HMHelpContentPtr

A pointer to a help tag structure.

typedef HMHelpContentRec* HMHelpContentPtr;

Discussion

See HMHelpContentRec for more information.

Availability

Available in Mac OS X v10.0 and later.

Declared In

MacHelp.h

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

MacHelp.h

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

MacHelp.h

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

MacHelp.h

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

MacHelp.h

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