Control Manager Reference

Framework	Carbon/Carbon.h
Declared in	ControlDefinitions.h Controls.h HIButtonViews.h HIClockView.h HIContainerViews.h HIDataBrowser.h HIDisclosureViews.h HIImageViews.h HILittleArrows.h HIObject.h HIPopupButton.h HIProgressViews.h HIRelevanceBar.h HIScrollView.h HISeparator.h HISlider.h HITabbedView.h HITextViews.h HIToolboxDebugging.h

Overview

Your application uses the Control Manager to create and manage controls. Controls are onscreen objects that the user can manipulate with the mouse. By manipulating controls, the user can take an immediate action or change settings to modify a future action. For example, a scroll bar control allows a user to immediately change the portion of the document that your application displays, whereas a pop-up menu control for connection speed might allow the user to change the rate by which your application handles subsequent data transmissions.

Virtually all applications need to implement controls, at least in the form of scroll bars for document windows. Other standard Mac OS controls include buttons, checkboxes, radio buttons, and pop-up menus. You can use the Control Manager to create and manage these controls, too.

In Mac OS X v10.2 and later, Control Manager controls may be implemented as HIViews. View-based controls offer additional flexibility and extensibility for developers. For more information, see the document HIView Programming Guide.

Important: Documentation for the data browser control is available separately in Data Browser Programming Guide.

Carbon supports most Control Manager functions, with the following changes:

The C-style, lowercase versions of Control Manager function names are no longer supported. If your application uses any Control Manager lowercase function names, you must replace them with their uppercase equivalents.
Custom control definition procedures (also known as CDEFs), must be compiled as PowerPC-native code, and can not be stored as resources. See the Carbon Porting Guide for more information.
Your application must use the functions defined by the Control Manager to create and dispose of Control Manager data structures. For example, instead of directly creating and disposing of control records, applications must call the Control Manager functions GetNewControl and DisposeControl.
With the availability of the Appearance Manager, you should not access the PopupPrivateData structure, but rather pass the kControlPopupButtonMenuHandleTag tag to GetControlData to obtain its contents.
Your application must use Control Manager accessor functions to access Control Manager data structures.
You are encouraged to adopt the standard Mac OS control definition procedures in your application. Applications that use the standard control definition procedures inherit the Mac OS human interface appearance. Applications that use custom control definition procedures will work correctly, but because custom definition procedures invoke their own drawing routines, Mac OS X can’t draw these applications with the current appearance.

Functions by Task

Creating and Removing Controls

Embedding Controls

Displaying Controls

Handling Events in Controls

Manipulating Controls

Handling Keyboard Focus

Accessing Control Settings and Data

Manipulating Menus in Controls

The functions described in this section can only be called for pop-up button and pop-up group box controls, which can support pop-up menus that activate when the user presses the control with the mouse.

Manipulating Bevel Buttons

Bevel button controls have additional features that you can or should manipulate to display them properly. This section describes the functions you can use to manipulate these features.

Managing Control UPPs

Obsolete Functions

These functions are outdated and are not recommended.

Functions

ActivateControl

Activates a control and any latent embedded controls.

OSErr ActivateControl (
   ControlRef inControl
);

Parameters

inControl: A handle to the control to activate. If you pass a window’s root control, ActivateControl activates all controls in that window. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The ActivateControl function should be called instead of HiliteControl to activate a specified control and its latent embedded controls.

An embedded control is considered latent when it is deactivated or hidden due to its embedder control being deactivated or hidden. If you activate a latent embedded control whose embedder is deactivated, the embedded control becomes latent until the embedder is activated. However, if you deactivate a latent embedded control, it will not be activated when its embedder is activated.

If a control definition function supports activate events, it will receive a kControlMsgActivate message before redrawing itself in its active state.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

AdvanceKeyboardFocus

Advances the keyboard focus to the next focusable control in a window.

OSErr AdvanceKeyboardFocus (
   WindowRef inWindow
);

Parameters

inWindow: A pointer to the window for which to advance keyboard focus.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The AdvanceKeyboardFocus function skips over deactivated and hidden controls until it finds the next focusable control in the window. If it does not find a focusable item, it simply returns.

When AdvanceKeyboardFocus is called, the Control Manager calls your control definition function and passes kControlMsgFocus in its message parameter and kControlFocusNextPart in its param parameter. In response to this message, your control definition function should change keyboard focus to its next part, the entire control, or remove keyboard focus from the control, depending upon the circumstances. See ControlDefProcPtr for a discussion of possible responses to this message.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

AutoEmbedControl

Automatically embeds a control in the smallest appropriate embedder control.

OSErr AutoEmbedControl (
   ControlRef inControl,
   WindowRef inWindow
);

Parameters

inControl: A handle to the control to be embedded.
inWindow: A pointer to the window in which to embed the control.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The Dialog Manager uses AutoEmbedControl to position dialog items in an embedding hierarchy based on both visual containment and the item list resource order. As items are added to a dialog box during creation, controls that already exist in the window will be containers for new controls if they both visually contain the control and have set the kControlSupportsEmbedding feature bit. For this reason, you should place the largest embedder controls at the beginning of the item list resource. As an example, the Dialog Manager would embed radio buttons in a tab control if they visually “fit” inside the tab control, as long as the tab control was already created in a'DITL' resource and established as an embedder control. For more information on embedding hierarchies in dialog and alert boxes, see the function EmbedControl.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

DialogsToHIViews

Declared In

Controls.h

ChangeControlPropertyAttributes

Changes a property attribute.

OSStatus ChangeControlPropertyAttributes (
   ControlRef control,
   OSType propertyCreator,
   OSType propertyTag,
   OptionBits attributesToSet,
   OptionBits attributesToClear
);

Parameters

control: The control whose property’s attributes you want to change. For a description of this data type, see ControlRef.
propertyCreator: An OSType signature, usually the signature of your application. Do not use all lower case signatures, as these are reserved for use by Apple.
propertyTag: An OSType signature, defined by your application, defining the property whose attributes you want to change.
attributesToSet: A bit field indicating the attributes you want to set for this property.
attributesToClear: A bit field indicating the attributes you want to clear for this property.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

If you have associated control properties with a control (by calling SetControlProperty, you can also assign arbitrary attribute bits to the property. You can use these attributes to indicate information about the property data.

Currently, kControlPropertyPersistent is the only control property attribute that is defined.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

ClearKeyboardFocus

Removes the keyboard focus for the currently focused control in a window.

OSErr ClearKeyboardFocus (
   WindowRef inWindow
);

Parameters

inWindow: A pointer to the window in which to clear keyboard focus.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

When the ClearKeyboardFocus function is called, the Control Manager calls your control definition function and passes kControlMsgFocus in its message parameter and kControlFocusNoPart in its param parameter. See ControlDefProcPtr for a discussion of possible responses to this message.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

CopyControlTitleAsCFString

Makes a copy of the control’s title as a Core Foundation string.

OSStatus CopyControlTitleAsCFString (
   ControlRef inControl,
   CFStringRef *outString
);

Parameters

inControl: The control whose title is to be copied. For a description of this data type, see ControlRef.
outString: A copy of the control’s title.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

CountSubControls

Obtains the number of embedded controls within a control.

OSErr CountSubControls (
   ControlRef inControl,
   UInt16 *outNumChildren
);

Parameters

inControl: The control whose embedded controls are to be counted. For a description of this data type, see ControlRef.
outNumChildren: On input, a pointer to an unsigned 16-bit integer value. On return, the value is set to the number of embedded subcontrols.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The CountSubControls function is useful for iterating over the control hierarchy. You can use the count produced to determine how many subcontrols there are and then call GetIndexedSubControl to get each.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

CreateBevelButtonControl

Creates a bevel button control.

OSStatus CreateBevelButtonControl (
   WindowRef window,
   const Rect *boundsRect,
   CFStringRef title,
   ControlBevelThickness thickness,
   ControlBevelButtonBehavior behavior,
   ControlButtonContentInfoPtr info,
   MenuID menuID,
   ControlBevelButtonMenuBehavior menuBehavior,
   ControlBevelButtonMenuPlacement menuPlacement,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the desired control in the window’s local coordinates.
title: The title of the control.
thickness: The thickness of the button. For possible values, see “Control Bevel Thickness Constants.”
behavior: The behavior the button is to have. For possible values, see “Bevel Button Behavior Constants.”
info: A value of type ControlButtonContentInfoPtr for the content information.
menuID: The menu ID. This parameter may be 0 if you don’t have a menu. Icon suite, picture, color icon, and IconRef are supported on Mac OS X v10.0 through Mac OS X v10.4. Values of type CGImageRef are supported in Mac OS X v10.4.
menuBehavior: The behavior of the menu. For possible values, see “Bevel Button Menu Constant.”
menuPlacement: The placement of the menu. For possible values, see “Control Bevel Button Menu Placement Constants.”
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

CreateChasingArrowsControl

Creates a chasing arrows control.

OSStatus CreateChasingArrowsControl (
   WindowRef window,
   const Rect *boundsRect,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the desired control in the window’s local coordinates.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

This control automatically animates via an event loop timer.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIProgressViews.h

CreateCheckBoxControl

Creates a checkbox control.

OSStatus CreateCheckBoxControl (
   WindowRef window,
   const Rect *boundsRect,
   CFStringRef title,
   SInt32 initialValue,
   Boolean autoToggle,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the checkbox control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the desired checkbox in the window’s local coordinates.
title: The title of the checkbox.
initialValue: The initial setting of the checkbox. Set to a non-zero value to indicate the checked state.
autoToggle: If set to true, clicking the checkbox will automatically toggle its state (checked or unchecked).
outControl: On return, outControl points to the new checkbox. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

TypeServicesForUnicode

Declared In

HIButtonViews.h

CreateCheckGroupBoxControl

Creates a group box control that has a check box as its title.

OSStatus CreateCheckGroupBoxControl (
   WindowRef window,
   const Rect *boundsRect,
   CFStringRef title,
   SInt32 initialValue,
   Boolean primary,
   Boolean autoToggle,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
title: The title of the control. The title is used as the title of the check box.
initialValue: The initial value of the check box.
primary: A Boolean whose value is true to create a primary group box or false to create a secondary group box.
autoToggle: A Boolean whose value is true to create an auto-toggling check box. Auto-toggling check box titles are only supported on Mac OS X; this parameter must be false when used with CarbonLib.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIContainerViews.h

CreateClockControl

Creates a clock control.

OSStatus CreateClockControl (
   WindowRef window,
   const Rect *boundsRect,
   ControlClockType clockType,
   ControlClockFlags clockFlags,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the desired control in the window’s local coordinates.
clockType: The clock type. For possible values, see “Control Clock Type Constants.”
clockFlags: Clock options. For possible values, see “Clock Value Flag Constants.”
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIClockView.h

CreateDisclosureButtonControl

Creates a new instance of the Disclosure Button Control.

OSStatus CreateDisclosureButtonControl (
   WindowRef inWindow,
   const Rect *inBoundsRect,
   SInt32 inValue,
   Boolean inAutoToggles,
   ControlRef *outControl
);

Parameters

inWindow: The WindowRef in which to create the control. This parameter may be NULL in Mac OS X v10.3 and later.
inBoundsRect: The bounding rectangle for the control in the window’s local coordinates. The height of the control is fixed and the control will be centered vertically within the rectangle you specify.
inValue: The initial value; either kControlDisclosureButtonClosed or kControlDisclosureButtonDisclosed.
inAutoToggles: A Boolean value indicating whether its value should change automatically after tracking the mouse.
outControl: On successful exit, this will contain the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

CreateDisclosureButtonControl is preferred over NewControl because it allows you to specify the exact set of parameters required to create the control without overloading parameter semantics. The initial minimum of the Disclosure Button will be kControlDisclosureButtonClosed, and the maximum will be kControlDisclosureButtonDisclosed.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIDisclosureViews.h

CreateDisclosureTriangleControl

Creates a disclosure triangle control.

OSStatus CreateDisclosureTriangleControl (
   WindowRef inWindow,
   const Rect *inBoundsRect,
   ControlDisclosureTriangleOrientation inOrientation,
   CFStringRef inTitle,
   SInt32 inInitialValue,
   Boolean inDrawTitle,
   Boolean inAutoToggles,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
inBoundsRect: The desired position, in the window’s local coordinates, for the disclosure triangle.
inOrientation: The direction the disclosure triangle should point when it is “closed.” Passing kControlDisclosureTrianglePointDefault is only legal as of Mac OS X and CarbonLib 1.5. For other possible values, see “Control Disclosure Triangle Orientation Constants.”
inTitle: The title for the disclosure triangle. The title is displayed only if the value of the inDrawTitle parameter is true. Displaying the title only works on Mac OS X.
inInitialValue: The initial state of the disclosure triangle. A value of 0 causes the disclosure triangle to be drawn initially in the “closed” state, and a value of 1 causes the triangle to be drawn initially in the “open” state.
inDrawTitle: A Boolean whose value is true if the disclosure triangle should draw its title next to the widget. Displaying the title only works on Mac OS X.
inAutoToggles: A Boolean whose value is true to enable auto toggling; otherwise, false. When auto toggling is enabled, the disclosure triangle automatically changes from “open” to “closed” and from “closed” to “open” when it is clicked.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

A disclosure triangle is a small control that gives the user a way to toggle the visibility of information or other user interface. When information is in a hidden state, a disclosure triangle is considered “closed” and should point to the right (or sometimes to the left). When the user clicks it, a disclosure triangle rotates downwards into the “open” state. The application should respond by revealing the appropriate information or interface.

On Mac OS X, a root control is created for the window if one does not already exist. If a root control exists for the window, the disclosure triangle control is embedded in it.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIDisclosureViews.h

CreateEditUnicodeTextControl

Creates a new edit text control.

OSStatus CreateEditUnicodeTextControl (
   WindowRef window,
   const Rect *boundsRect,
   CFStringRef text,
   Boolean isPassword,
   const ControlFontStyleRec *style,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
text: The text of the control. May be NULL.
isPassword: A Boolean indicating whether the field is to be used as a password field. Passing false indicates that text entered in the field is to be displayed normally. Passing true means that the field is to be used as a password field; any text typed into the field is displayed as bullets.
style: The control’s font style, size, color, and so on. May be NULL.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

This function is the preferred way of creating edit text controls. Use it instead of the CreateEditTextControl function. The resulting control handles Unicode text and draws its text using anti-aliasing. Controls created by CreateEditTextControl do not handle Unicode text and are not drawn with anti-aliasing.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HITextViews.h

CreateGroupBoxControl

Creates a group box control.

OSStatus CreateGroupBoxControl (
   WindowRef window,
   const Rect *boundsRect,
   CFStringRef title,
   Boolean primary,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the desired control in the window’s local coordinates.
title: The title of the control. This parameter can be NULL if you don’t want the control to have a title.
primary: A Boolean whose value is true to create a primary group box or false to create a secondary group box. Secondary group boxes are intended to be contained within primary group boxes and have a slightly different appearance.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

TypeServicesForUnicode

Declared In

HIContainerViews.h

CreateIconControl

Creates an icon control.

OSStatus CreateIconControl (
   WindowRef inWindow,
   const Rect *inBoundsRect,
   const ControlButtonContentInfo *inIconContent,
   Boolean inDontTrack,
   ControlRef *outControl
);

Parameters

inWindow: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
inBoundsRect: The bounds of the control in the window’s local coordinates.
inIconContent: The descriptor for the icon you want the control to display. Mac OS X and CarbonLib 1.5 (and beyond) support all of the icon content types. Prior to CarbonLib 1.5, the only content types that are properly respected are kControlContentIconSuiteRes, kControlContentCIconRes, and kControlContentICONRes.
inDontTrack: A Boolean whose value is true to indicate that the control should not be highlighted when it is clicked; false means that the control should be highlighted and the mouse tracked when the control is clicked.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIImageViews.h

CreateImageWellControl

Creates an image well control.

OSStatus CreateImageWellControl (
   WindowRef window,
   const Rect *boundsRect,
   const ControlButtonContentInfo *info,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
info: The image that is to be displayed in the image well. The image can be an icon suite, picture, color icon, or an IconRef in Mac OS X v10.0 and later. It can be also be a CGImageRef in Mac OS X v10.4 and later.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

An image well control is a control that displays an image inside a frame (or “well”). The user can drag other images onto the well.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIImageViews.h

CreateListBoxControl

Creates a list box control.

OSStatus CreateListBoxControl (
   WindowRef window,
   const Rect *boundsRect,
   Boolean autoSize,
   SInt16 numRows,
   SInt16 numColumns,
   Boolean horizScroll,
   Boolean vertScroll,
   SInt16 cellHeight,
   SInt16 cellWidth,
   Boolean hasGrowSpace,
   const ListDefSpec *listDef,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
autoSize: A Boolean whose value is true to enable auto-sizing; otherwise, false. When auto-sizing is enabled, the control automatically resizes itself as necessary to ensure that the height of the control is an exact multiple of the cell height.
numRows: The number of rows the control is to have.
numColumns: The number of columns the control is to have.
horizScroll: A Boolean whose value is true if the control is to have a horizontal scroll bar; otherwise, false.
vertScroll: A Boolean whose value is true if the control is to have a vertical scroll bar; otherwise, false.
cellHeight: The height of cells in the control.
cellWidth: The width of cells in the control.
hasGrowSpace: A Boolean whose value is true to indicate that the control is drawn so that there is room for a size box; otherwise, false.
listDef: A pointer to the list definition function you want to associate with the new control. This parameter may be NULL if you want to use the standard list definition function, which only displays text.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The list is created with default values, and uses the standard LDEF (0) if you don’t specify a custom list definition function in the listDef parameter. You can set the LDEF to use by using kControlListBoxLDEFTag. You can change the list by getting the list handle. To get the list handle, call GetControlData and pass the kControlListBoxListHandletag constant.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ControlDefinitions.h

CreateLittleArrowsControl

Creates a little arrows control.

OSStatus CreateLittleArrowsControl (
   WindowRef window,
   const Rect *boundsRect,
   SInt32 value,
   SInt32 minimum,
   SInt32 maximum,
   SInt32 increment,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
value: The initial value of the control.
minimum: The minimum value the control can have.
maximum: The maximum value the control can have.
increment: The amount to increment each time an arrow is clicked.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

This control implements the little up and down arrows seen in the Date & Time system preferences panel. To change the value of this control, you need to create a control action proc. The following sample code creates the control and sets the action proc:

CreateLittleArrowsControl(&rect, minimum, maximum, increment,  value);

SetControlAction(Arrows, LittleArrowActionProc);

Here is sample code for the action proc:

void LittleArrowActionProc(ControlRef cref, ControlPartCode part)  {

    SInt32 val = GetControl32BitValue(cref);

    SInt32 s = 0;

    GetControlData(cref, 0, kControlLittleArrowsIncrementValueTag, sizeof(SInt32), &s, nil;

    switch (part) {

        case kControlUpButtonPart:

            SetControl32BitValue(cref, val+s);

            break;

        case kControlDownButtonPart:

            SetControl32BitValue(cref, val-s);

            break;

};

};

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

LittleArrowsShowcase

Declared In

HILittleArrows.h

CreatePictureControl

Creates a picture control.

OSStatus CreatePictureControl (
   WindowRef window,
   const Rect *boundsRect,
   const ControlButtonContentInfo *content,
   Boolean dontTrack,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
content: The descriptor for the picture you want the control to display. Only picture content is supported. You can change the picture by calling SetControlData and passing the kControlPictureHandleTag constant.
dontTrack: A Boolean whose value is true to indicate that the control should not be highlighted when it is clicked; false means that the control should be highlighted and the mouse tracked when the control is clicked.
outControl: On return, the new control.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ControlDefinitions.h

CreatePlacardControl

Creates a placard control.

OSStatus CreatePlacardControl (
   WindowRef window,
   const Rect *boundsRect,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounding box of the control in the window’s local coordinates.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIContainerViews.h

CreatePopupArrowControl

Creates a pop-up arrow control.

OSStatus CreatePopupArrowControl (
   WindowRef window,
   const Rect *boundsRect,
   ControlPopupArrowOrientation orientation,
   ControlPopupArrowSize size,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
orientation: The orientation of the control.
size: The size of the control.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIPopupButton.h

CreatePopupButtonControl

Creates a pop-up button control.

OSStatus CreatePopupButtonControl (
   WindowRef window,
   const Rect *boundsRect,
   CFStringRef title,
   MenuID menuID,
   Boolean variableWidth,
   SInt16 titleWidth,
   SInt16 titleJustification,
   Style titleStyle,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
title: The title of the control.
menuID: The ID of a menu that should be used by the control. A menu with this ID should be inserted into the menubar with InsertMenu(menu, kInsertHierarchicalMenu). You can also pass -12345 to have the control delay its acquisition of a menu; in this case, you can build the menu and later provide it to the control with SetControlData and kControlPopupButtonMenuRefTag or kControlPopupButtonOwnedMenuRefTag.
variableWidth: A Boolean whose value indicates whether the width of the control is allowed to vary according to the width of the selected menu item text (true), or should remain fixed to the original control bounds width (false).
titleWidth: The width of the title.
titleJustification: The justification of the title. Use a TextEdit justification constant (teFlushDefault, teCenter, teFlushRight, or teFlushLeft).
titleStyle: A QuickDraw style bitfield indicating the font style of the title.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIPopupButton.h

CreatePopupGroupBoxControl

Creates a group box control that has a pop-up button as its title.

OSStatus CreatePopupGroupBoxControl (
   WindowRef window,
   const Rect *boundsRect,
   CFStringRef title,
   Boolean primary,
   MenuID menuID,
   Boolean variableWidth,
   SInt16 titleWidth,
   SInt16 titleJustification,
   Style titleStyle,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
title: The title of the control. The title is used as the title of the pop-up button.
primary: A Boolean whose value is true to create a primary group box or false to create a secondary group box.
menuID: The menu ID of the menu that is to be displayed by the pop-up button. A menu with this ID should be inserted into the menubar with InsertMenu(menu, kInsertHierarchicalMenu). You can also pass -12345 to have the control delay its acquisition of a menu; in this case, you can build the menu and later provide it to the control with SetControlData and kControlPopupButtonMenuRefTag or kControlPopupButtonOwnedMenuRefTag.
variableWidth: A Boolean whose value is true if the pop-up button is to have a variable-width title or false if the pop-up button is to have a fixed-width title. Fixed-width titles are only supported by Mac OS X; this parameter must be true when used with CarbonLib.
titleWidth: The width in pixels of the pop-up button title.
titleJustification: The justification of the pop-up button title. Use a TextEdit justification constant (teFlushDefault, teCenter, teFlushRight, or teFlushLeft).
titleStyle: The QuickDraw text style of the pop-up button title.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIContainerViews.h

CreateProgressBarControl

Creates a progress bar control.

OSStatus CreateProgressBarControl (
   WindowRef window,
   const Rect *boundsRect,
   SInt32 value,
   SInt32 minimum,
   SInt32 maximum,
   Boolean indeterminate,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
value: The initial value of the control.
minimum: The minimum value of the control.
maximum: The maximum value of the control.
indeterminate: A Boolean whose value is true if you want the control to display a rotating barber pole effect to indicate that something is happening (an indeterminate progress bar) or false if you want to display a determinate progress bar that uses the values of the minimum and maximum parameters to show progress from minimum to maximum.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIProgressViews.h

CreatePushButtonControl

Creates a push button control.

OSStatus CreatePushButtonControl (
   WindowRef window,
   const Rect *boundsRect,
   CFStringRef title,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
title: The control title. May be NULL.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

HIButtonViews.h

CreatePushButtonWithIconControl

Creates a push button control containing an icon or other graphical content.

OSStatus CreatePushButtonWithIconControl (
   WindowRef window,
   const Rect *boundsRect,
   CFStringRef title,
   ControlButtonContentInfo *icon,
   ControlPushButtonIconAlignment iconAlignment,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control, in local coordinates of the window.
title: The control title. May be NULL.
icon: The control graphic content. The value of this parameter can be kControlContentCIconRes in Mac OS X v10.0 and later. It can also be kControlContentCGImageRef in Mac OS X v10.4 and later.
iconAlignment: The alignment of the control graphic content.For possible values, see “Control Push Button Icon Alignment Constants.”
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

CreateRadioButtonControl

Creates a radio button control.

OSStatus CreateRadioButtonControl (
   WindowRef window,
   const Rect *boundsRect,
   CFStringRef title,
   SInt32 initialValue,
   Boolean autoToggle,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
title: The control title. May be NULL.
initialValue: The initial value of the control. Should be 0 (off), 1 (on), or 2 (mixed). The control is automatically given a minimum value of 0 and a maximum value of 2.
autoToggle: A Boolean whose value indicates whether this control should have auto-toggle behavior. If true, the control automatically toggles between on and off states when clicked. This parameter should be false if the control is embedded into a radio group control; in that case, the radio group handles setting the correct control value in response to a click.
outControl: On return, the new control.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

TypeServicesForUnicode

Declared In

HIButtonViews.h

CreateRadioGroupControl

Creates a radio group control.

OSStatus CreateRadioGroupControl (
   WindowRef window,
   const Rect *boundsRect,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

This control implements a radio group. It is an embedding control and can therefore only be used when a control hierarchy is established for its owning window. You should only embed radio buttons within it. As radio buttons are embedded into it, the group sets up its value, min, and max to represent the number of embedded items. The current value of the control is the index of the sub-control that is the current “on” radio button. To get the current radio button control handle, you can use the Control Manager call GetIndexedSubControl, passing in the value of the radio group.

Note that when creating radio buttons for use in a radio group control, you should not use the auto-toggle version of the radio button. The radio group control handles toggling the radio button values itself; auto-toggle radio buttons do not work properly in a radio group control on Mac OS 9.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

TypeServicesForUnicode

Declared In

HIButtonViews.h

CreateRelevanceBarControl

Creates a relevance bar control.

OSStatus CreateRelevanceBarControl (
   WindowRef window,
   const Rect *boundsRect,
   SInt32 value,
   SInt32 minimum,
   SInt32 maximum,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
value: The initial value of the control.
minimum: The minimum value of the control.
maximum: The maximum value of the control.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIRelevanceBar.h

CreateRootControl

Creates the root control for a specified window.

OSErr CreateRootControl (
   WindowRef inWindow,
   ControlRef *outControl
);

Parameters

inWindow: A pointer to the window in which you wish to create a root control.
outControl: On input, a pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the root control.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

Establishing an embedding hierarchy can be accomplished in two steps: creating a root control and embedding controls within it.

To embed controls in a window, you must create a root control for that window. The root control is the container for all other window controls. You create the root control in one of two ways—by calling the CreateRootControl function or by setting the appropriate dialog flag. The root control can be retrieved by calling the function GetRootControl.

The CreateRootControl function creates the root control for a window if no other controls are present. If there are any controls in the window prior to calling CreateRootControl, an error is returned and the root control is not created. Note that the minimum, maximum, and initial settings for a root control are reserved and should not be changed.

The root control is implemented as a user pane control. You can attach any application-defined user pane functions to the root control to perform actions such as hit testing, drawing, handling keyboard focus, erasing to the correct background, and processing idle and keyboard events.

Once you have created a root control, newly created controls will automatically be embedded in the root control when you call NewControl or GetNewControl. You can specify that a specific control be embedded into another by calling EmbedControl.

By acting on an embedder control, you can move, disable, or hide groups of items. For example, you can use a blank user pane control as the embedder control for all items in a particular “page” of a tab control. After creating as many user panes as you have tabs, you can hide one and show the next when a tab is clicked. All the controls embedded in the user pane will be hidden and shown automatically when the user pane is hidden and shown.

In addition to calling CreateRootControl, you can establish an embedding hierarchy in a dialog box by either setting the feature bit kDialogFlagsUseControlHierarchy in the extended dialog resource or passing it in the inFlags parameter of the Dialog Manager function NewFeaturesDialog. An embedding hierarchy can be created in an alert box by setting the kAlertFlagsUseControlHierarchy bit in the extended alert resource. It is important to note that a preexisting alert or dialog item will become a control if it is in an alert or dialog box that now uses an embedding hierarchy.

The embedding hierarchy enforces drawing order by drawing the embedding control before its embedded controls. Using an embedding hierarchy also enforces orderly hit-testing, since it performs an “inside-out” hit test to determine the most deeply nested control that is hit by the mouse. An embedding hierarchy is also necessary for controls to make use of keyboard focus, the default focusing order for which is a linear progression that uses the order the controls were added to the window. For more details on keyboard focus, see “Handling Keyboard Focus”.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

CreateRoundButtonControl

Creates a new instance of the round button control.

OSStatus CreateRoundButtonControl (
   WindowRef inWindow,
   const Rect *inBoundsRect,
   ControlRoundButtonSize inSize,
   ControlButtonContentInfo *inContent,
   ControlRef *outControl
);

Parameters

inWindow: The WindowRef in which to create the control.
inBoundsRect: The bounds of the control in the window’s local coordinates. The height and width of the control are fixed (specified by the ControlRoundButtonSize parameter) and the control will be centered within the rectangle you specify.
inSize: The button size; either kControlRoundButtonNormalSize or kControlRoundButtonLargeSize.
inContent: Any optional content displayed in the button. In Mac OS X v10.0 and later, kControlContentIconRef is supported.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

CreateRoundButtonControl is preferred over NewControl because it allows you to specify the exact set of parameters required to create the control without overloading parameter semantics.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

CreateScrollBarControl

Creates a scroll bar control.

OSStatus CreateScrollBarControl (
   WindowRef window,
   const Rect *boundsRect,
   SInt32 value,
   SInt32 minimum,
   SInt32 maximum,
   SInt32 viewSize,
   Boolean liveTracking,
   ControlActionUPP liveTrackingProc,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
value: The initial value of the control.
minimum: The minimum value of the control.
maximum: The maximum value of the control.
viewSize: The size of the visible area of the scroll bar content. If this parameter is a non-zero value, this function creates a proportional scroll bar thumb; a value of 0 causes a non-proportional scroll bar thumb to be created.
liveTracking: A Boolean indicating whether or not live tracking is enabled for this scroll bar. If set to true and a valid liveTrackingProc is also passed in, the callback is called repeatedly as the thumb is moved during tracking. If set to false, a semi-transparent thumb called a “ghost thumb” draws and no live tracking occurs.
liveTrackingProc: If the value of the liveTracking parameter is true, a ControlActionUPP callback is to be called as the control live tracks. This callback is called repeatedly as the scroll thumb is moved during tracking.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIScrollView.h

CreateScrollingTextBoxControl

Creates a scrolling text box control.

OSStatus CreateScrollingTextBoxControl (
   WindowRef window,
   const Rect *boundsRect,
   SInt16 contentResID,
   Boolean autoScroll,
   UInt32 delayBeforeAutoScroll,
   UInt32 delayBetweenAutoScroll,
   UInt16 autoScrollAmount,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
contentResID: The resource ID of ‘TEXT’ and (optionally) ‘style’ resources whose contents are to be displayed.
autoScroll: A Boolean whose value is true to enable automatic scrolling; otherwise, false.
delayBeforeAutoScroll: The number of ticks to wait before scrolling automatically. This parameter is ignored and can be set to 0 if the value of the autoScroll parameter is false.
delayBetweenAutoScroll: The number of ticks to wait between automatic scrolls. This parameter is ignored and can be set to 0 if the value of the autoScroll parameter is false.
autoScrollAmount: The number of pixels to scroll. This parameter is ignored and can be set to 0 if the value of the autoScroll parameter is false.
outControl: On return, outControl points to the newly-created control.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

This control implements a scrolling box of text that cannot be edited. This is useful for credits in about boxes.

The standard version of this control has a scroll bar, but the autoscrolling variant does not. The autoscrolling variant needs two pieces of information to work: delay (in ticks) before the scrolling starts, and time (in ticks) between scrolls. This control scrolls one pixel at a time if created by NewControl, unless changed by calling SetControlData.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ControlDefinitions.h

CreateSeparatorControl

Creates a separator control.

OSStatus CreateSeparatorControl (
   WindowRef window,
   const Rect *boundsRect,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The horizontal or vertical orientation of a separator line is determined automatically based on the relative height and width of its control bounds.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HISeparator.h

CreateSliderControl

Creates a slider control.

OSStatus CreateSliderControl (
   WindowRef window,
   const Rect *boundsRect,
   SInt32 value,
   SInt32 minimum,
   SInt32 maximum,
   ControlSliderOrientation orientation,
   UInt16 numTickMarks,
   Boolean liveTracking,
   ControlActionUPP liveTrackingProc,
   ControlRef *outControl
);

Parameters

window: The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
value: The initial value of the control.
minimum: The minimum value of the control.
maximum: The maximum value of the control.
orientation: The orientation of the control. For possible values, see “Control Slider Orientation Constants.”
numTickMarks: The number of tick marks the slider control is to have.
liveTracking: A Boolean whose value is true to enable live tracking for the control; otherwise, false.
liveTrackingProc: If the value of the liveTracking parameter is true, a ControlActionUPP callback is to be called as the control live tracks. This callback is called repeatedly as the slider is moved during tracking.
outControl: On return, outControl points to the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

Mac OS X has a “Scroll to here” option in the General pane of System Preferences that allows users to click in the page up or page down regions of a slider and have the indicator jump directly to the clicked position, which alters the value of the slider and moves any associated content appropriately. As long as the mouse button is held down, the click is treated as though the user clicked the indicator.

If you want the sliders in your application to work with the “Scroll to here” option, you must do the following:

Create live-tracking sliders, not sliders that show a “ghost” thumb when you click on it. You can request live-tracking sliders by passing true in the liveTracking parameter to CreateSliderControl. If you create sliders with NewControl, use the kControlSliderLiveFeedback variant.
Write an appropriate ControlActionProc and associate it with your slider by calling SetControlAction. This allows your application to update its content appropriately when the live-tracking slider is clicked.
When callingHandleControlClick or TrackControl TrackControl, pass -1 in the action proc parameter. This is a request for the Control Manager to use the action proc you associated with your control in step 2. If you rely on the standard window event handler to do your control tracking, this step is handled for you automatically.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

HISlider.h

CreateStaticTextControl

Creates a new static text control.

OSStatus CreateStaticTextControl (
   WindowRef window,
   const Rect *boundsRect,
   CFStringRef text,
   const ControlFontStyleRec *style,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
text: The text of the control. May be NULL.
style: The control’s font style, size, color, and so on. May be NULL.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

HITextViews.h

CreateTabsControl

Creates a tabs control.

OSStatus CreateTabsControl (
   WindowRef window,
   const Rect *boundsRect,
   ControlTabSize size,
   ControlTabDirection direction,
   UInt16 numTabs,
   const ControlTabEntry *tabArray,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
size: The control tab size. See “Control Tab Size Constants” for possible values.
direction: The control tab direction. See “Control Tab Direction Constants” for possible values.
numTabs: The initial number of tabs.
tabArray: Information about each tab. There must be the same number of entries as specified by the numTabs parameter.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

If you want to customize the accessibility information provided for individual tabs of a tabs control, such as by handling various kEventClassAccessibility Carbon Events and by calling HIObjectSetAuxiliaryAccessibilityAttribute, you need to know how to build or interpret AXUIElement reference that represent individual tabs. The AXUIElement representing an individual tab must be constructed using the tab control’s ControlRef and the UInt64 identifier of the one-based index of the tab to which the element refers. A UInt64 identifier of 0 represents the tabs control as a whole. You cannot interpret or create tab control elements whose identifiers are greater than the count of tabs in the tabs control.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

TabsShowcase

Declared In

HITabbedView.h

CreateUserPaneControl

Creates a user pane control.

OSStatus CreateUserPaneControl (
   WindowRef window,
   const Rect *boundsRect,
   UInt32 features,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
features: The user pane features with which the user pane is to be created. For possible constants, see “Control Features Constants.”
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

User panes have two primary purposes: to allow easy implementation of a custom control by the developer, and to provide a generic container for embedding other controls.

In Carbon, with the advent of Carbon-event-based controls, you may find it easier to write a new control from scratch than to customize a user pane control. The set of callbacks provided by the user pane will not be extended to support new Control Manager features; instead, you should just write a real control.User panes do not, by default, support embedding. If you try to embed a control into a user pane, you will get the errControlIsNotEmbedder. You can make a user pane support embedding by passing the kControlSupportsEmbedding flag in the features parameter when you create the control.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

HIContainerViews.h

CreateWindowHeaderControl

Creates a window header control.

OSStatus CreateWindowHeaderControl (
   WindowRef window,
   const Rect *boundsRect,
   Boolean isListHeader,
   ControlRef *outControl
);

Parameters

window: The window in which the control is to be placed. This parameter may be NULL in Mac OS X v10.3 and later.
boundsRect: The bounds of the control in the window’s local coordinates.
isListHeader: A Boolean whose value is true if the control should have an appropriate appearance to be the header of a list; otherwise, false.
outControl: On return, the new control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIContainerViews.h

DeactivateControl

Deactivates a control and any latent embedded controls.

OSErr DeactivateControl (
   ControlRef inControl
);

Parameters

inControl: A handle to the control to deactivate. If you pass a window’s root control, DeactivateControl deactivates all controls in that window.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The DeactivateControl function should be called instead of HiliteControl to deactivate a specified control and its latent embedded controls.

If a control definition function supports activate events, it will receive a kControlMsgActivate message before redrawing itself in its inactive state.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

DisableControl

Disables a control.

OSStatus DisableControl (
   ControlRef inControl
);

Parameters

inControl: The control to disable. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

DisposeControl

Decrements a control’s reference count and destroys it if the reference count becomes 0.

void DisposeControl (
   ControlRef theControl
);

Parameters

theControl: The control you want to dispose of. For a description of this data type, see ControlRef.

Discussion

The DisposeControl function reduces the control’s reference count and, if the reference count becomes 0, releases the memory occupied by the control structure and any data structures associated with the control. Before destroying the control, DisposeControl removes the control (and any embedded controls it may possess) from the screen and deletes the control from the window’s control list.

To destroy all of the controls from a window you want to keep, use the function KillControls. If an embedding hierarchy is present, passing the root control to the DisposeControl function is the effectively the same as calling KillControls. In that situation, DisposeControl disposes of the controls embedded within a control before disposing of the container control.

You should use DisposeControl when you want to retain the window but remove one of its controls. The Window Manager functions CloseWindow and DisposeWindow automatically remove all controls associated with the window and release the memory the controls occupy.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

DisposeControlActionUPP

Disposes of a control action UPP.

void DisposeControlActionUPP (
   ControlActionUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Controls.h

DisposeControlCNTLToCollectionUPP

Disposes of a CNLT to collection UPP.

void DisposeControlCNTLToCollectionUPP (
   ControlCNTLToCollectionUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

DisposeControlColorUPP

Not recommended

void DisposeControlColorUPP (
   ControlColorUPP userUPP
);

Carbon Porting Notes

Instead of specifying a callback to redraw your background, you should make the background a control and then embed your other controls within it.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

DisposeControlEditTextValidationUPP

Disposes of an edit text validation UPP.

void DisposeControlEditTextValidationUPP (
   ControlEditTextValidationUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HITextViews.h

DisposeControlKeyFilterUPP

Disposes of a key filter UPP.

void DisposeControlKeyFilterUPP (
   ControlKeyFilterUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Controls.h

DisposeControlUserPaneActivateUPP

Disposes of a user pane activate UPP.

void DisposeControlUserPaneActivateUPP (
   ControlUserPaneActivateUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

DisposeControlUserPaneBackgroundUPP

Disposes of a user pane background UPP.

void DisposeControlUserPaneBackgroundUPP (
   ControlUserPaneBackgroundUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIContainerViews.h

DisposeControlUserPaneDrawUPP

Disposes of a user pane draw UPP.

void DisposeControlUserPaneDrawUPP (
   ControlUserPaneDrawUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

DisposeControlUserPaneFocusUPP

Disposes of a user pane focus UPP.

void DisposeControlUserPaneFocusUPP (
   ControlUserPaneFocusUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

DisposeControlUserPaneHitTestUPP

Disposes of a user pane hit test UPP.

void DisposeControlUserPaneHitTestUPP (
   ControlUserPaneHitTestUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

DisposeControlUserPaneIdleUPP

Disposes of a user pane idle UPP.

void DisposeControlUserPaneIdleUPP (
   ControlUserPaneIdleUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

DisposeControlUserPaneKeyDownUPP

Disposes of a user pane key down UPP.

void DisposeControlUserPaneKeyDownUPP (
   ControlUserPaneKeyDownUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

DisposeControlUserPaneTrackingUPP

Disposes of a user pane tracking UPP.

void DisposeControlUserPaneTrackingUPP (
   ControlUserPaneTrackingUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

DisposeEditUnicodePostUpdateUPP

Disposes of an edit unicode post update UPP.

void DisposeEditUnicodePostUpdateUPP (
   EditUnicodePostUpdateUPP userUPP
);

Parameters

userUPP: The UPP that is to be disposed of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HITextViews.h

DragControl

Draws and moves an outline of a control or its indicator while the user drags it. (Deprecated. Use Drag Manager functions if you want drag-and-drop support for controls. See Drag Manager Reference.)

Not recommended

void DragControl (
   ControlRef theControl,
   Point startPoint,
   const Rect *limitRect,
   const Rect *slopRect,
   DragConstraint axis
);

Parameters

theControl: A handle to the control to drag. For a description of this data type, see ControlRef.
startPoint: The location of the cursor at the time the mouse button was first pressed, in global coordinates. Your application retrieves this point from the where field of the event structure.
limitRect: A pointer to a rectangle—whose coordinates should normally coincide with or be contained in the window’s content region—delimiting the area in which the user can drag the control’s outline.
slopRect: A pointer to a rectangle that allows some extra space for the user to move the mouse while still constraining the control within the rectangle specified in the limitRect parameter.
axis: The axis along which the user may drag the control’s outline. Specify the axis using one of the following values: noConstraint (no constraint), hAxisOnly (drag along horizontal axis only), vAxisOnly (drag along vertical axis only).

Discussion

The DragControl function moves a dotted outline of a control, such as a scroll box, around the screen, following the movements of the cursor until the user releases the mouse button. When the user releases the mouse button, DragControl moves the control to the new location.

The function TrackControl automatically calls the DragControl function as appropriate; when you use TrackControl, you don’t need to call DragControl.

Before tracking the cursor, DragControl calls the control definition function. If you define your own control definition function, you can specify custom dragging behavior.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

Draw1Control

Draws a control and any embedded controls that are currently visible in the specified window.

void Draw1Control (
   ControlRef theControl
);

Parameters

theControl: A handle to the control to draw. For a description of this data type, see ControlRef.

Discussion

Although you should generally use the functionUpdateControls to update controls, you can use the DrawOneControl function to update a single control. If an embedding hierarchy exists and the control passed in has embedded controls, DrawOneControl draws the control and embedded controls. If the root control for a window is passed in, the result is the same as if DrawControls was called.

If you are using compositing mode, you generally do not need to call Draw1Control. If you call Draw1Control in compositing mode, keep in mind that it draws the specified control as well as all other controls that intersect the control.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

DrawControlInCurrentPort

Draws a control in the current graphics port.

void DrawControlInCurrentPort (
   ControlRef inControl
);

Parameters

inControl: A handle to the control to draw. For a description of this data type, see ControlRef.

Discussion

Typically, controls are automatically drawn in their owner’s graphics port with the functions DrawControls, Draw1Control, and UpdateControls. DrawControlInCurrentPort permits easy offscreen control drawing and printing. All standard system controls support this function.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

DrawControls

Draws all controls currently visible in the specified window.

void DrawControls (
   WindowRef theWindow
);

Parameters

theWindow: A pointer to a window whose controls you want to display.

Discussion

Because the UpdateControls function redraws only those controls that need updating, your application should generally use it instead of DrawControls when you receive an update event for a window that contains controls. You should typically call either DrawControls or UpdateControls after calling the Window Manager function BeginUpdate and before calling EndUpdate.

While the Dialog Manager automatically draws and updates controls in alert boxes and dialog boxes, Window Manager functions such as SelectWindow, ShowWindow, and BringToFront do not automatically update the window’s controls.

When the Appearance Manager is not available, the DrawControls function draws all controls currently visible in the specified window in reverse order of creation; thus, in case of overlapping controls, the control created first appears frontmost in the window. If you only wish to draw controls in need of update, call UpdateControls instead.

Note that DrawControls generally should not be called if you are using compositing mode.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

DumpControlHierarchy

Writes a textual representation of the control hierarchy for a specified window into a file.

OSErr DumpControlHierarchy (
   WindowRef inWindow,
   const FSSpec *inDumpFile
);

Parameters

inWindow: A pointer to the window whose control hierarchy you wish to examine.
inDumpFile: A pointer to a file specification in which to place a text description of the window’s control hierarchy.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The DumpControlHierarchy function places a text listing of the current control hierarchy for the window specified into the specified file, overwriting any existing file. If the specified window does not contain a control hierarchy, DumpControlHierarchy notes this in the text file. This function is useful for debugging embedding-related problems.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIToolboxDebugging.h

EmbedControl

Embeds one control inside another.

OSErr EmbedControl (
   ControlRef inControl,
   ControlRef inContainer
);

Parameters

inControl: The control that is to be embedded. For a description of this data type, see ControlRef.
inContainer: The control in which the control specified by inControl is to be is to embedded. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

Establishing an embedding hierarchy can be accomplished in two steps: creating a root control and embedding controls within it.

Note that an embedding hierarchy must be established before your application calls the EmbedControl function. If the specified control does not support embedding or there is no root control in the owning window, an error is returned. Prior to Mac OS X, if the control you wish to embed is in a different window from the embedder control, an error is returned. On Mac OS X, however, you can use EmbedControl to move a control from one window to another. On Mac OS X v.10.0 and v.10.1, you can move all controls except for the edit text and unicode edit text controls. Support for the edit text controls is available in Mac OS X v.10.2 and later.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

EnableControl

Enables a control.

OSStatus EnableControl (
   ControlRef inControl
);

Parameters

theControl: The control that is to be enabled.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

FindControl

Obtains the location of a mouse-down event in a control.

ControlPartCode FindControl (
   Point testPoint,
   WindowRef theWindow,
   ControlRef *theControl
);

Parameters

testPoint: A point, specified in coordinates local to the window, where the mouse-down event occurred. Before calling FindControl, use the GlobalToLocal function to convert the point stored in the where field of the event structure (which describes the location of the mouse-down event) to coordinates local to the window.
theWindow: A pointer to the window in which the mouse-down event occurred. Pass the window pointer returned by the FindWindow function.
theControl: A pointer to a control handle. On output, FindControl returns a handle to the control in which the mouse-down event occurred or NULL if the point was not over a control. For a description of this data type, see ControlRef.

Return Value

The control part code of the control in which the mouse-down event occurred; see “Control Meta Part Code Constants,” “Control Part Code Constants ,” and“ Control State Part Code Constants.” For a description of this data type, see ControlPartCode.

Discussion

The FindControl function is not recommended when the Appearance Manager is available. When the Appearance Manager is available, you should call FindControlUnderMouse to determine the location of a mouse-down event in a control. FindControlUnderMouse will return a handle to the control even if no part was hit and can determine whether a mouse-down event has occurred even if the control is deactivated, while FindControl does not.

If the Appearance Manager is not available, then, when a mouse-down event occurs, your application can call FindControl after using the Window Manager function FindWindow to ascertain that a mouse-down event has occurred in the content region of a window containing controls.

When the user presses the mouse button while the cursor is in a visible, active control, FindControl returns as its function result a part code identifying the control’s part the function also returns a handle to the control in the parameter theControl.

If the mouse-down event occurs in an invisible or inactive control, or if it occurs outside a control, FindControl sets the value referenced through theControl to NULL and returns 0 as its function result.

The FindControl function also returns NULL in the value referenced through the parameter theControl and 0 as its function result if the window is invisible or if it doesn’t contain the given point. (However, FindWindow won’t return a window pointer to an invisible window or to one that doesn’t contain the point where the mouse-down event occurred. As long as you call FindWindow before FindControl, this situation won’t arise.)

After using FindControl to determine that a mouse-down event has occurred in a control, you typically call the function TrackControl to follow and respond to the cursor movements in that control, and then to determine in which part of the control the mouse-up event occurs.

The pop-up control definition function does not define part codes for pop-up menus. Instead, your application should store the handles for your pop-up menus when you create them. Your application should then test the handles you store against the handles returned by FindControl before responding to users’ choices in pop-up menus.

The Dialog Manager automatically calls FindControl and TrackControl for mouse-down events inside controls of alert boxes and dialog boxes.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

FindControlUnderMouse

Obtains the location of a mouse-down event in a control.

ControlRef FindControlUnderMouse (
   Point inWhere,
   WindowRef inWindow,
   ControlPartCode *outPart
);

Parameters

inWhere: A point, specified in coordinates local to the window, where the mouse-down event occurred. Before calling FindControlUnderMouse, use the QuickDraw GlobalToLocal function to convert the point stored in the where field of the event structure (which describes the location of the mouse-down event) to coordinates local to the window.
inWindow: A pointer to the window in which the mouse-down event occurred.
outPart: On input, a pointer to a signed 16-bit integer value. On return, the value is set to the part code of the control part that was selected; see “Control Part Code Constants ,” “Control Part Code Constants ,” and “ Control State Part Code Constants.”

Return Value

A handle to the control that was selected. If the mouse-down event did not occur over a control part, FindControlUnderMouse returns NULL. For a description of this data type, see ControlRef.

Discussion

You should call the FindControlUnderMouse function instead of FindControl to determine whether a mouse-down event occurred in a control, particularly if an embedding hierarchy is present. FindControlUnderMouse will return a handle to the control even if no part was hit and can determine whether a mouse-down event has occurred even if the control is deactivated, while FindControl does not.

When a mouse-down event occurs, your application should call FindControlUnderMouse after using the Window Manager function FindWindow to ascertain that a mouse-down event has occurred in the content region of a window containing controls.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

CarbonSketch

Declared In

Controls.h

GetBestControlRect

Obtains a control’s optimal size and text placement.

OSErr GetBestControlRect (
   ControlRef inControl,
   Rect *outRect,
   SInt16 *outBaseLineOffset
);

Parameters

inControl: A handle to the control to be examined.
outRect: On input, a pointer to an empty rectangle (0, 0, 0, 0). On return, the rectangle is set to the optimal size for the control. If the control doesn’t support getting an optimal size rectangle, the control’s bounding rectangle is passed back.
outBaseLineOffset: On input, a pointer to a signed 16-bit integer value. On return, the value is set to the offset from the bottom of control to the base of the text (usually a negative value). If the control doesn’t support optimal sizing or has no text, 0 is passed back.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

You can call the GetBestControlRect function to automatically position and size controls in accordance with human interface guidelines. This function is particularly helpful in determining the correct placement of control text whose length is not known until run-time. For example, the StandardAlert function uses GetBestControlRect to automatically size and position buttons in a newly created alert box.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

TypeServicesForUnicode

Declared In

Controls.h

GetBevelButtonContentInfo

Gets the content information for a bevel button.

OSErr GetBevelButtonContentInfo (
   ControlRef inButton,
   ControlButtonContentInfoPtr outContent
);

Parameters

inButton: The control reference for the button to query.
outContent: A value of type ControlButtonContentInfoPtr for the bevel button’s content information.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

GetBevelButtonMenuHandle

Gets the menu handle for a bevel button.

OSErr GetBevelButtonMenuHandle (
   ControlRef inButton,
   MenuHandle *outHandle
);

Parameters

inButton: The control reference for the button to query.
outHandle: A pointer to the menu handle.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

GetBevelButtonMenuValue

Gets the value of a bevel button menu.

OSErr GetBevelButtonMenuValue (
   ControlRef inButton,
   MenuItemIndex *outValue
);

Parameters

inButton: The control reference for the button to query.
outValue: A pointer to the value of the bevel button menu.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

GetControl32BitMaximum

Obtains the maximum setting of a control.

SInt32 GetControl32BitMaximum (
   ControlRef theControl
);

Parameters

theControl: A handle to the control whose maximum setting you wish to obtain. For a description of this data type, see ControlRef.

Return Value

The maximum setting of the control.

Discussion

Your application may use the GetControl32BitMaximum function to obtain a 32-bit value previously set with the function SetControl32BitMaximum.

If your application uses a 32-bit control maximum value, it should not attempt to obtain this value by calling the pre–Mac OS 8.5 function GetControlMaximum because the 16-bit value that is returned does not accurately reflect the current 32-bit control value.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControl32BitMinimum

Obtains the minimum setting of a control.

SInt32 GetControl32BitMinimum (
   ControlRef theControl
);

Parameters

theControl: A handle to the control whose minimum setting you wish to obtain. For a description of this data type, see ControlRef.

Return Value

The minimum setting of the control.

Discussion

Your application may use the GetControl32BitMinimum function to obtain a 32-bit value previously set with the function SetControl32BitMinimum.

If your application uses a 32-bit control minimum value, it should not attempt to obtain this value by calling the pre–Mac OS 8.5 function GetControlMinimum because the 16-bit value that is returned does not accurately reflect the current 32-bit control value.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControl32BitValue

Obtains the current setting of a control.

SInt32 GetControl32BitValue (
   ControlRef theControl
);

Parameters

theControl: A handle to the control whose current setting you wish to obtain.

Return Value

The current setting of the control.

Discussion

Your application may use the GetControl32BitValue function to obtain a 32-bit value previously set with the function SetControl32BitValue.

If your application uses a 32-bit control value, it should not attempt to obtain this value by calling the pre–Mac OS 8.5 function GetControlValue because the 16-bit value that is returned does not accurately reflect the current 32-bit control value.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlAction

Returns a pointer to the action function associated with a control structure.

ControlActionUPP GetControlAction (
   ControlRef theControl
);

Parameters

theControl: A handle to a control.

Return Value

The action function associated with the control. The action function is called by the HandleControlClick and TrackControl functions if you set the InAction parameter to (ControlActionUPP)-1. See ControlActionProcPtr for an example of an action function.

Discussion

The action function returned by the GetControlAction function defines an action to take in response to a mouse button being held down while the cursor is in the control. An action function is usually specified in the InAction parameter of the functions HandleControlClick and TrackControl. You can use the function SetControlAction to change the action function.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

GetControlBounds

Gets the bounds of a control.

Rect * GetControlBounds (
   ControlRef control,
   Rect *bounds
);

Parameters

control: The control to query. For a description of this data type, see ControlRef.
bounds: On input, a pointer to a QuickDraw rectangle. On output, the rectangle contains the bounds of the control in local coordinates.

Return Value

A pointer to the rectangle passed in the bounds parameter.

Discussion

When called in a composited window, this function returns the view’s frame, which is equivalent to calling HIViewGetFrame.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlByID

Finds a control in a window by its unique ID.

OSStatus GetControlByID (
   WindowRef inWindow,
   const ControlID *inID,
   ControlRef *outControl
);

Parameters

inWindow: The window to query.
inID: The control ID.
outControl: A pointer to a value of type ControlRef that, on output, is filled in with the control reference for the control specified by inID. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

As of Mac OS X v10.3, this function is superseded by the HIViewFindByID function, which is preferred over the GetControlByID function. The first parameter to the HIViewFindByID function is a view and not a window, so you can start the search at any point in the hierarchy.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlClickActivation

Gets the control’s preferred behavior for responding to particular click.

OSStatus GetControlClickActivation (
   ControlRef inControl,
   Point inWhere,
   EventModifiers inModifiers,
   ClickActivationResult *outResult
);

Parameters

inControl
inWhere: The location at which the control was clicked.
inModifiers: Information from the modifiers field of the event structure specifying the state of the modifier keys and the mouse button at the time the event was posted. .
outResult: A pointer to a value of type ClickActivationResult containing the result. For possible values, see “Click Activation Constants.”

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

Some complex controls, such as Data Browser, require proper sequencing of window activation and click processing. In some cases, the control might want the window to be left inactive yet still handle the click, or vice- versa. This function lets a control client ask the control how it wants to behave for a particular click.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

GetControlCommandID

Gets the command ID for a control.

OSStatus GetControlCommandID (
   ControlRef inControl,
   UInt32 *outCommandID
);

Parameters

inControl
outCommandID: A pointer to the command ID.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

GetControlData

Obtains control-specific data.

OSErr GetControlData (
   ControlRef inControl,
   ControlPartCode inPart,
   ResType inTagName,
   Size inBufferSize,
   void *inBuffer,
   Size *outActualSize
);

Parameters

inControl: A handle to the control to be examined.
inPart: “Control Meta Part Code Constants”The part code of the control part from which data is to be obtained; see , “Control Part Code Constants ,” and “ Control State Part Code Constants.” Passing kControlEntireControl indicates that either the control has no parts or the data is not tied to any specific part of the control. For a description of this data type, see ControlPartCode.
inTagName: A constant representing the control-specific data you wish to obtain see the data tag constants in the “Control Manager Constants” section.
inBufferSize: The size (in bytes) of the data pointed to by the inBuffer parameter. For variable-length control data, pass the value returned in the outMaxSize parameter of GetControlDataSize in the inBufferSize parameter. The number of bytes must match the actual data size.
inBuffer: On input, a pointer to a buffer allocated by your application. On return, the buffer contains a copy of the control-specific data. If you pass NULL on input, it is equivalent to calling GetControlDataSize. The actual size of the control-specific data will be returned in the outActualSize parameter. For variable-length data, the number of bytes must match the actual data size.
outActualSize: On input, a pointer to a Size value. On return, the value is set to the actual size of the data. You can pass NULL if you don’t care about this value.

Return Value

A result code. See “Control Manager Result Codes.” The result code errDataNotSupported indicates that the inTagName parameter is not valid.

Discussion

The GetControlData function will only copy the amount of data specified in the inBufferSize parameter, but will tell you the actual size of the buffer so you will know if the data was truncated.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlDataHandle

Obtains a handle to control-specific data. (Deprecated. Use custom HIViews instead of custom CDEFs. See HIView Programming Guide.)

Handle GetControlDataHandle (
   ControlRef control
);

Return Value

A handle to control-specific data.

Discussion

The control data handle is for control-specific data used by a control’s implementation. The control data handle is set by calling SetControlDataHandle.

In general, you should not attempt to interpret the contents of this handle if you did not implement the control yourself. For controls that are provided by the operating system, the format of the data handle may change from one release of the operating system to the next.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

GetControlDataSize

Obtains the size of a control’s tagged data.

OSErr GetControlDataSize (
   ControlRef inControl,
   ControlPartCode inPart,
   ResType inTagName,
   Size *outMaxSize
);

Parameters

inControl: A handle to the control to be examined.For a description of this data type, see ControlRef.
inPart: The part code of the control part with which the data is associated; see“Control Meta Part Code Constants,” “Control Part Code Constants ,” and “ Control State Part Code Constants.” Passing kControlEntireControl indicates that either the control has no parts or the data is not tied to any specific part of the control.
inTagName: A constant representing the control-specific data whose size is to be obtained see the data tag constants in the “Control Manager Constants” section.
outMaxSize: On input, a pointer to a Size value. On return, the value is set to the size (in bytes) of the control’s tagged data. This value should be passed to SetControlData and GetControlData to allocate a sufficiently large buffer for variable-length data.

Return Value

A result code. See “Control Manager Result Codes.” The result code errDataNotSupported indicates that the inTagName parameter is not valid.

Discussion

Pass the value returned in the outMaxSize parameter of GetControlDataSize in the inBufferSize parameter of SetControlData and GetControlData to allocate an adequate buffer for variable-length data.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

GetControlFeatures

Obtains the features a control supports.

Not recommended

OSErr GetControlFeatures (
   ControlRef inControl,
   UInt32 *outFeatures
);

Parameters

inControl: A handle to the control to be examined. For a description of this data type, see ControlRef.
outFeatures: On input, a pointer to an unsigned 32-bit integer value. On return, the value contains a bit field specifying the features the control supports. For a list of the features a control may support, see ControlDefProcPtr.

Return Value

A result code. See “Control Manager Result Codes.” The result code errMsgNotSupported indicates that the control does not support Appearance-compliant features.

Discussion

The GetControlFeatures function obtains the Appearance-compliant features a control definition function supports, in response to a kControlMsgGetFeatures message.

Carbon Porting Notes

Some feature bits may not be relevant when using Carbon event-based messages.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

ControlBackground

Declared In

Controls.h

GetControlHilite

Gets the highlight status of a control.

UInt16 GetControlHilite (
   ControlRef control
);

Parameters

control: The control to query. For a description of this data type, see ControlRef.

Return Value

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlID

Gets the control ID for a control.

OSStatus GetControlID (
   ControlRef inControl,
   ControlID *outID
);

Parameters

inControl: The control to query. For a description of this data type, see ControlRef.
outID: A pointer to a value of type ControlID that, on return, contains the control ID of the control specified by inControl.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlKind

Returns the kind of the given control.

OSStatus GetControlKind (
   ControlRef inControl,
   ControlKind *outControlKind
);

Parameters

inControl: The control to query. For a description of this data type, see ControlRef.
outControlKind: On successful exit, this will contain the control signature and kind. See ControlDefinitions.h for the kinds of each system control. For a description of this data type, see ControlKind.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

GetControlKind allows you to query the kind of any control.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

TypeServicesForUnicode

Declared In

Controls.h

GetControlMaximum

Obtains a control’s maximum setting. (Deprecated. Use GetControl32BitMaximum instead.)

Not recommended

SInt16 GetControlMaximum (
   ControlRef theControl
);

Parameters

theControl: A handle to the control whose maximum value you wish to determine. For a description of this data type, see ControlRef.

Return Value

The specified control’s maximum setting.

Discussion

When you create a control, you specify an initial maximum setting either in the control resource or in the max parameter of the function NewControl. You can change the maximum setting by using the function SetControlMaximum.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlMinimum

Obtains a control’s minimum setting. (Deprecated. Use GetControl32BitMinimum instead.)

Not recommended

SInt16 GetControlMinimum (
   ControlRef theControl
);

Parameters

theControl: A handle to the control whose minimum value you wish to determine.

Return Value

The specified control’s minimum setting.

Discussion

When you create a control, you specify an initial minimum setting either in the control resource or in the min parameter of the function NewControl. You can change the minimum setting by using the function SetControlMinimum.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlOwner

Returns the window to which a control is bound.

WindowRef GetControlOwner (
   ControlRef control
);

Parameters

control: The control to query. For a description of this data type, see ControlRef.

Return Value

The window reference to which the control is bound, or NULL if the control is not bound to a window.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlPopupMenuHandle

Gets the menu handle for a pop-up control.

MenuRef GetControlPopupMenuHandle (
   ControlRef control
);

Parameters

control: The pop-up control to query.

Return Value

See the Menu Manager documentation for a description of the MenuRef data type.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlPopupMenuID

Gets the menu ID of a pop-up menu.

short GetControlPopupMenuID (
   ControlRef control
);

Parameters

control: The pop-up control to query.

Return Value

The menu ID.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

GetControlProperty

Obtains a piece of data that has been previously associated with a control.

OSStatus GetControlProperty (
   ControlRef control,
   OSType propertyCreator,
   OSType propertyTag,
   ByteCount bufferSize,
   ByteCount *actualSize,
   void *propertyBuffer
);

Parameters

control: A handle to the control whose associated data you wish to obtain.
propertyCreator: Your program’s signature, as registered through Apple Developer Technical Support. If your program is of a type that would not normally have a signature (for example, a plug-in), you should still register and use a signature in this case, even though your program’s file may not have the same creator code as the signature that you register. The ‘macs' property signature is reserved for the system and should not be used.
propertyTag: The application-defined code identifying the data.
bufferSize: A value specifying the size of the data to be obtained. If the size of the data is unknown, use the function GetControlPropertySize to get the data’s size. If the size specified in the bufferSize parameter does not match the actual size of the property, GetControlProperty only retrieves data up to the size specified or up to the actual size of the property, whichever is smaller, and an error is returned.
actualSize: On input, a pointer to an unsigned 32-bit integer. On return, this value is set to the actual size of the associated data. You may pass NULL for the actualSize parameter if you are not interested in this information.
propertyBuffer: On input, a pointer to a buffer. On return, this buffer contains a copy of the data that is associated with the specified control.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

You may use the function GetControlProperty to obtain a copy of data previously set by your application with the function SetControlProperty.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlPropertyAttributes

Gets the property attributes for a control.

OSStatus GetControlPropertyAttributes (
   ControlRef control,
   OSType propertyCreator,
   OSType propertyTag,
   OptionBits *attributes
);

Parameters

control: The control to query. For a description of this data type, see ControlRef.
propertyCreator: The OSType signature, usually the signature of your application, for the property creator of the attributes that are to be obtained.
propertyTag: The OSType signature for the property tag for the attributes that are to be obtained.
attributes: A pointer to a value of type UInt32 that, on return, contains the attributes of the control specified by control.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

GetControlPropertySize

Obtains the size of a piece of data that has previously been associated with a control.

OSStatus GetControlPropertySize (
   ControlRef control,
   OSType propertyCreator,
   OSType propertyTag,
   ByteCount *size
);

Parameters

control: A handle to the control whose associated data you wish to examine. For a description of this data type, see ControlRef.
propertyCreator: Your program’s signature, as registered through Apple Developer Technical Support. If your program is of a type that would not normally have a signature (for example, a plug-in), you should still register and use a signature in this case, even though your program’s file may not have the same creator code as the signature that you register. The ‘macs' property signature is reserved for the system and should not be used.
propertyTag: The application-defined code identifying the data.
size: On input, a pointer to an unsigned 32-bit integer. On return, this value is set to the actual size of the data.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

If you want to retrieve a piece of associated data with the function GetControlProperty, you will typically need to use the GetControlPropertySize function beforehand to determine the size of the associated data.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

GetControlReference

Obtains a control’s current reference value.

SRefCon GetControlReference (
   ControlRef theControl
);

Parameters

theControl: A handle to the control whose current reference value you wish to determine.

Return Value

The current reference value for the specified control.

Discussion

When you create a control, you specify an initial reference value, either in the control resource or in the refCon parameter of the function NewControl. The reference value is stored in the contrlRfCon field of the control structure. You can use this field for any purpose, and you can use the function SetControlReference to change this value.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlRegion

Obtains the region corresponding to a given control part.

OSStatus GetControlRegion (
   ControlRef inControl,
   ControlPartCode inPart,
   RgnHandle outRegion
);

Parameters

inControl: A handle to the control whose part region you want to obtain.
inPart: A constant identifying the control part for which a region is to be obtained. You may specify the kControlStructureMetaPart and kControlContentMetaPart control part codes, as well as the standard control part codes. See “Control Meta Part Code Constants,” “Control Part Code Constants ,” and “ Control State Part Code Constants” for descriptions of possible values.
outRegion: On input, a value of type RgnHandle. On return, GetControlRegion sets the region to contain the actual dimensions and position of the control part, in local coordinates.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

GetControlValue

Obtains a control’s current setting. (Deprecated. Use GetControl32BitValue instead.)

Not recommended

SInt16 GetControlValue (
   ControlRef theControl
);

Parameters

theControl: On input, a handle to a control.

Return Value

The current setting of the control.

Discussion

When you create a control, you specify an initial setting either in the control resource or in the value parameter of the function NewControl. You can change the setting by calling SetControlValue.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetControlVariant

Returns the variation code specified in the control definition function for a particular control. (Deprecated. Use custom HIViews instead of custom CDEFs. See HIView Programming Guide.)

Not recommended

ControlVariant GetControlVariant (
   ControlRef theControl
);

Parameters

theControl: A handle to the control whose variation code you wish to determine.

Return Value

The variation code for the specified control see the control definition IDs in the “Control Manager Constants” section for descriptions of control variation codes. For a description of this data type, see ControlVariant.

Discussion

A control definition function can use a variation code to describe variations of the same basic control. For example, all pop-up arrows share the same basic control definition function, which is stored in a resource of type 'CDEF' and has a resource ID of 12. The standard pop-up arrow is large and points to the right; it has a control definition ID of 192. A variation of this is a large, left-pointing arrow, which has a control definition ID of 193. Still another variation, in which the arrow points up, has a control definition ID of 194.

Carbon Porting Notes

Use only if you are using message-based custom controls (CDEFs).

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

GetControlViewSize

Obtains the size of the content to which a control’s size is proportioned.

SInt32 GetControlViewSize (
   ControlRef theControl
);

Parameters

theControl: A value of type ControlHandle. Pass a handle to the control whose view size you wish to obtain.

Return Value

A value equal to the current size of the content being displayed, expressed in terms of the same units of measurement as are used for the minimum, maximum, and current settings of the control.

Discussion

Your application should call the GetControlViewSize function to obtain the current view size of a control. This value is used by the scrollbar control to support proportional scroll boxes.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

GetImageWellContentInfo

Gets information about the content of an image well.

OSErr GetImageWellContentInfo (
   ControlRef inButton,
   ControlButtonContentInfoPtr outContent
);

Parameters

inButton: The control reference to query.
outContent: On return, the value type ControlButtonContentInfoPtr for the control specified by inButton.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIImageViews.h

GetIndexedSubControl

Obtains a handle to a specified embedded control.

OSErr GetIndexedSubControl (
   ControlRef inControl,
   UInt16 inIndex,
   ControlRef *outSubControl
);

Parameters

inControl: The control from which an embedded control handle is to be obtained. For a description of this data type, see ControlRef.
inIndex: A one-based index—an integer between 1 and the value returned in the outNumChildren parameter of CountSubControls—specifying the control you wish to access.
outSubControl: On input, a pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the embedded control.

Return Value

A result code. See “Control Manager Result Codes.” If the index passed in is invalid, the paramErr result code is returned.

Discussion

The GetIndexedSubControl function is useful for iterating over the control hierarchy. Also, the value of a radio group control is the index of its currently selected embedded radio button control. So, passing the current value of a radio group control into GetIndexedSubControl will give you a handle to the currently selected radio button control.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Carbon Porting Tutorial

Declared In

Controls.h

GetKeyboardFocus

Obtains a handle to the control with the current keyboard focus for a specified window.

OSErr GetKeyboardFocus (
   WindowRef inWindow,
   ControlRef *outControl
);

Parameters

inWindow: A pointer to the window for which to obtain keyboard focus.
outControl: On input, a pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the control that currently has keyboard focus. Produces NULL if no control has focus.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The GetKeyboardFocus function returns the handle of the control with current keyboard focus within a specified window.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetNewControl

Creates a control from a control resource.

ControlRef GetNewControl (
   SInt16 resourceID,
   WindowRef owningWindow
);

Parameters

resourceID: The resource ID of the control you wish to create.
owningWindow: A pointer to the window in which to place the control.

Return Value

A handle to the control created from the specified control resource. If GetNewControl can’t read the control resource from the resource file, it returns NULL. For a description of this data type, see ControlRef.

Discussion

The GetNewControl function creates a control structure from the information in the specified control resource, adds the control structure to the control list for the specified window, and returns as its function result a handle to the control. You use this handle when referring to the control in most other Control Manager functions. After making a copy of the control resource, GetNewControl releases the memory occupied by the original control resource before returning.

The control resource specifies the rectangle for the control, its initial setting, its visibility state, its maximum and minimum settings, its control definition ID, a reference value, and its title (if any). After you use GetNewControl to create the control, you can change the control characteristics with other Control Manager functions.

If the control resource specifies that the control should be visible, the Control Manager draws the control. If the control resource specifies that the control should initially be invisible, you can use the function ShowControl to make the control visible.

When an embedding hierarchy is established within a window, GetNewControl automatically embeds the newly created control in the root control of the owning window.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetRootControl

Obtains a handle to a window’s root control.

OSErr GetRootControl (
   WindowRef inWindow,
   ControlRef *outControl
);

Parameters

inWindow: A pointer to the window to be examined.
outControl: Pass a pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the root control.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

You can call GetRootControl to determine whether or not a root control (and therefore an embedding hierarchy) exists within a specified window. Once you have the root control’s handle, you can pass it to functions such as DisposeControl, ActivateControl,and DeactivateControl to apply specified actions to the entire embedding hierarchy.

Note that the minimum, maximum, and initial settings for a root control are reserved and should not be changed.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetSuperControl

Obtains a handle to an embedder control.

OSErr GetSuperControl (
   ControlRef inControl,
   ControlRef *outParent
);

Parameters

inControl: A handle to an embedded control. For a description of this data type, see ControlRef.
outParent: A pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the embedder control. For a description of this data type, see ControlRef.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The GetSuperControl function gets a handle to the parent control of the control passed in.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

GetTabContentRect

Gets the content rectangle for a tab.

OSErr GetTabContentRect (
   ControlRef inTabControl,
   Rect *outContentRect
);

Parameters

inTabControl: The tab control reference to query.
outContentRect: On return, the value of this parameter is a pointer to the content rectangle for the tab specified by inTabControl.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HITabbedView.h

HandleControlClick

Responds to cursor movements in a control while the mouse button is down and returns the location of the next mouse-up event.

ControlPartCode HandleControlClick (
   ControlRef inControl,
   Point inWhere,
   EventModifiers inModifiers,
   ControlActionUPP inAction
);

Parameters

inControl: A handle to the control in which the mouse-down event occurred. Pass the control handle returned by FindControl or FindControlUnderMouse.
inWhere: A point, specified in local coordinates, where the mouse-down event occurred. Supply the same point you passed to FindControl or FindControlUnderMouse.
inModifiers: Information from the modifiers field of the event structure specifying the state of the modifier keys and the mouse button at the time the event was posted.
inAction: A universal procedure pointer to an action function defining what action your application takes while the user holds down the mouse button. See ControlActionProcPtr for a description of such an action function. The value of the inAction parameter can be a valid procPtr, NULL, or -1. A value of -1 indicates that the control should either perform auto tracking, or if it is incapable of doing so, do nothing (like NULL). For custom controls, what you pass in this parameter depends on how you define the control. If the part index is greater than 128, the pointer must be of type DragGrayRegionUPP unless the control supports live feedback, in which case it should be a ControlActionUPP.

Return Value

Returns a value of type ControlPartCode identifying the control’s part see “Control Meta Part Code Constants,” “Control Part Code Constants ,” and“ Control State Part Code Constants.” For a description of this data type, see ControlPartCode.

Discussion

Call the HandleControlClick function after a call to FindControl or FindControlUnderMouse. The HandleControlClick function should be called instead of TrackControl to follow the user’s cursor movements in a control and provide visual feedback until the user releases the mouse button. Unlike TrackControl, HandleControlClick allows modifier keys to be passed in so that the control may use these if the control (such as a list box or editable text field) is set up to handle its own tracking.

The visual feedback given by HandleControlClick depends on the control part in which the mouse-down event occurs. When highlighting is appropriate, for example, HandleControlClick highlights the control part (and removes the highlighting when the user releases the mouse button). When the user holds down the mouse button while the cursor is in an indicator (such as the scroll box of a scroll bar) and moves the mouse, HandleControlClick responds by dragging a dotted outline or a ghost image of the indicator. If the user releases the mouse button when the cursor is in an indicator such as the scroll box, HandleControlClick calls the control definition function to reposition the indicator.

While the user holds down the mouse button with the cursor in one of the standard controls, HandleControlClick performs the following actions, depending on the value you pass in the parameter inAction.

If you pass NULL in the inAction parameter, HandleControlClick uses no action function and therefore performs no additional actions beyond highlighting the control or dragging the indicator. This is appropriate for push buttons, checkboxes, radio buttons, and the scroll box of a scroll bar.
If you pass a pointer to an action function in the inAction parameter, it must define some action that your application repeats as long as the user holds down the mouse button. This is appropriate for the scroll arrows and gray areas of a scroll bar.
If you pass (ControlActionUPP)-1L in the inAction parameter, HandleControlClick calls the control action function associated with the control. This is appropriate when you are tracking the cursor in a pop-up menu. You can call GetControlAction to get a pointer to the control action function that is associated with the control, and you can call SetControlAction to set the control action function that is associated with the control.

For 'CDEF' resources that implement custom dragging, you usually call HandleControlClick, which returns 0 regardless of the user’s changes of the control setting. To avoid this, you should use another method to determine whether the user has changed the control setting, for instance, comparing the control’s value before and after your call to HandleControlClick.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

HandleControlContextualMenuClick

Allows a control to display a contextual menu.

OSStatus HandleControlContextualMenuClick (
   ControlRef inControl,
   Point inWhere,
   Boolean *menuDisplayed
);

Parameters

inControl
inWhere: The location that was clicked.
menuDisplayed: Pointer to a Boolean whose value is true if the control displayed a contextual menu; otherwise, false.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

HandleControlDragReceive

Tells a control to accept the data from a drag.

OSStatus HandleControlDragReceive (
   ControlRef inControl,
   DragReference inDrag
);

Parameters

inControl
inDrag: The drag reference that was dropped on the control.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

Call this function when the user drops a drag on a control in your window to give the control an opportunity to take any interesting data from the drag. Before calling this function, you must call SetControlDragTrackingEnabled to enable drag and drop support for the control.Note that this function should not be called in a composited window. Instead, the SetAutomaticControlDragTrackingEnabledForWindow API should be used to enable automatic control drag tracking.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

HandleControlDragTracking

Tells a control to respond visually to a drag.

OSStatus HandleControlDragTracking (
   ControlRef inControl,
   DragTrackingMessage inMessage,
   DragReference inDrag,
   Boolean *outLikesDrag
);

Parameters

inControl
inMessage: A drag message indicating the state of the drag above the control. The meaning of the value you pass in must be relative to the control, not the whole window. For when the drag first enters the control, you should pass kDragTrackingEnterControl. While the drag stays within the control, pass kDragTrackingInControl. When the drag leaves the control, pass kDragTrackingLeaveControl.
inDrag: The drag reference that is over the control.
outLikesDrag: On output, a pointer to a Boolean whose value is true if the control can accept the data in the drag reference or false if the control cannot accept the data. If the value is false,there is no need to call HandleControlDragReceive when the user drops the dragged object onto the control because the control cannot accept the data.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

Call this function when a drag is above a control in your window and you want to give that control a chance to draw appropriately in response to the drag. Before calling this function, you must call SetControlDragTrackingEnabled to enable drag and drop support for the control.Note that this function should not be called in a composited window. Instead, the SetAutomaticControlDragTrackingEnabledForWindow API should be used to enable automatic control drag tracking.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

HandleControlSetCursor

Requests that a control set the cursor based on the mouse location.

OSStatus HandleControlSetCursor (
   ControlRef control,
   Point localPoint,
   EventModifiers modifiers,
   Boolean *cursorWasSet
);

Parameters

inControl: .
localPoint: The location of the mouse.
modifiers: Information from the modifiers field of the event structure specifying the state of the modifier keys and the mouse button at the time the event was posted.
cursorWasSet: Out output, a pointer to a Boolean whose value is true if the cursor was set; otherwise, false.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

HideControl

Makes a control, and any latent embedded controls, invisible.

void HideControl (
   ControlRef theControl
);

Parameters

theControl: A handle to the control to hide.

Discussion

The HideControl function makes the specified control invisible. This can be useful, for example, before adjusting a control’s size and location. It also adds the control’s rectangle to the window’s update region, so that anything else that was previously obscured by the control will reappear on the screen. If the control is already invisible, HideControl has no effect.

When hiding groups of controls, the state of an embedded control that is hidden or deactivated is preserved so that when the embedder control is shown or activated, the embedded control appears in the same state as the embedder. If the specified control has embedded controls, HideControl makes the embedded controls invisible as well.

An embedded control is considered latent when it is deactivated or hidden due to its embedder control being deactivated or hidden. If you call HideControl on a latent embedded control, it would not be displayed the next time ShowControl was called on its embedder control.

To make the control visible again, call ShowControl.

You can also call SetControlVisibility to hide or show a control without causing it to redraw.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

HiliteControl

Changes the highlighting of a control.

Not recommended

void HiliteControl (
   ControlRef theControl,
   ControlPartCode hiliteState
);

Parameters

theControl: A handle to the control. For a description of this data type, see ControlRef.
hiliteState: A value from 0 to 255 that specifies the highlighting state of the control. The value of 0 signifies an active control with no highlighting. A value from 1 through 253 signifies a part code designating the part of the (active) control to highlight. Values 254 and 255 signify that the control is to be made disabled or inactive, respectively, and drawn accordingly. For a description of part code constants, see “Control Part Code Constants ,” “Control Part Code Constants ,” and “ Control State Part Code Constants.”

Discussion

If the Appearance Manager is available, you should call the functions ActivateControl and DeactivateControl instead of HiliteControl to activate or deactivate a control. This is important if the control is in an embedding hierarchy, since calling these functions will ensure that any latent embedded controls will be activated and deactivated correctly.

If the Appearance Manager is not available, then when you need to make a control inactive (such as when its window is not frontmost) or in any other way change the highlighting of a control, you can use the HiliteControl function.

The HiliteControl function calls the control definition function to redraw the control with the highlighting specified in the hiliteState parameter. The HiliteControl function uses the value in this parameter to change the value of the contrlHilite field of the control structure.

Except for scroll bars, which you should hide using HideControl, you should use HiliteControl to make all controls inactive when their windows are not frontmost. The function TrackControl automatically uses the HiliteControl function as appropriate; when you use TrackControl, you don’t need to call HiliteControl.

Carbon Porting Notes

If you are activating or deactivating a control, you should use ActivateControl or DeactivateControl instead. Otherwise okay to use.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

InvokeControlActionUPP

Invokes a control action UPP.

void InvokeControlActionUPP (
   ControlRef theControl,
   ControlPartCode partCode,
   ControlActionUPP userUPP
);

Parameters

theControl: The control for which the control action UPP is to be invoked. For a description of this data type, see ControlRef.
partCode: The part code for which the control action UPP is to be invoked. For possible values, see “Control Meta Part Code Constants,” “Control Part Code Constants ,” and “ Control State Part Code Constants.”
userUPP: The UPP that is to be invoked.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Controls.h

InvokeControlCNTLToCollectionUPP

Invokes a control-to-collection UPP.

OSStatus InvokeControlCNTLToCollectionUPP (
   const Rect *bounds,
   SInt16 value,
   Boolean visible,
   SInt16 max,
   SInt16 min,
   SInt16 procID,
   SRefCon refCon,
   ConstStr255Param title,
   Collection collection,
   ControlCNTLToCollectionUPP userUPP
);

Parameters

bounds: The bounds of the control.
value: The value of the control.
visible: A Boolean whose value is true if the control is visible; otherwise, false.
max: The maximum value of the control.
min: The minimum value of the control.
procID: The proc ID.
refCon: The refcon.
title: The title of the control.
collection: The collection.
userUPP: The UPP that is to be invoked.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

InvokeControlColorUPP

Not recommended

OSStatus InvokeControlColorUPP (
   ControlRef inControl,
   SInt16 inMessage,
   SInt16 inDrawDepth,
   Boolean inDrawInColor,
   ControlColorUPP userUPP
);

Return Value

A result code. See “Control Manager Result Codes.”

Carbon Porting Notes

Instead of specifying a callback to redraw your background, you should make the background a control and then embed your other controls within it.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

InvokeControlEditTextValidationUPP

Invokes a control edit text validation UPP.

void InvokeControlEditTextValidationUPP (
   ControlRef control,
   ControlEditTextValidationUPP userUPP
);

Parameters

theControl: The control. For a description of this data type, see ControlRef.
userUPP: The UPP that is to be invoked.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HITextViews.h

InvokeControlKeyFilterUPP

Invokes a control key filter UPP.

ControlKeyFilterResult InvokeControlKeyFilterUPP (
   ControlRef theControl,
   SInt16 *keyCode,
   SInt16 *charCode,
   EventModifiers *modifiers,
   ControlKeyFilterUPP userUPP
);

Parameters

theControl: The control. For a description of this data type, see ControlRef.
keyCode: The key code.
charCode: The character code.
modifiers: Information from the modifiers field of the event structure specifying the state of the modifier keys and the mouse button at the time the event was posted. .
userUPP: The UPP that is to be invoked.

Return Value

For a description of this data type, see ControlKeyFilterResult.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Controls.h

InvokeControlUserPaneActivateUPP

Invokes a control user pane activate UPP.

void InvokeControlUserPaneActivateUPP (
   ControlRef control,
   Boolean activating,
   ControlUserPaneActivateUPP userUPP
);

Parameters

control: The control.
activating: A Boolean whose value is true if the user pane is being activated; otherwise, false.
userUPP: The UPP that is to be invoked.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

InvokeControlUserPaneBackgroundUPP

Invokes a user pane background UPP.

void InvokeControlUserPaneBackgroundUPP (
   ControlRef control,
   ControlBackgroundPtr info,
   ControlUserPaneBackgroundUPP userUPP
);

Parameters

control: The control.
info: A pointer to information such as the depth and type of the drawing device. For a description of the ControlBackgroundPtr data type, see ControlBackgroundRec.
userUPP: The UPP that is to be activated.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIContainerViews.h

InvokeControlUserPaneDrawUPP

Invokes a user pane draw UPP.

void InvokeControlUserPaneDrawUPP (
   ControlRef control,
   ControlPartCode part,
   ControlUserPaneDrawUPP userUPP
);

Parameters

control: The control.
userUPP: The part.
userUPP: The UPP that is to be activated.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

InvokeControlUserPaneFocusUPP

Invokes a user pane focus UPP.

ControlPartCode InvokeControlUserPaneFocusUPP (
   ControlRef control,
   ControlFocusPart action,
   ControlUserPaneFocusUPP userUPP
);

Parameters

control: The control.
action: The action.
userUPP: The UPP that is to be activated.

Return Value

For a description of this data type, see ControlPartCode.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

InvokeControlUserPaneHitTestUPP

Invokes a user pane hit test UPP.

ControlPartCode InvokeControlUserPaneHitTestUPP (
   ControlRef control,
   Point where,
   ControlUserPaneHitTestUPP userUPP
);

Parameters

control: The control.
where: The location.
userUPP: The UPP that is to be activated.

Return Value

See ControlPartCode for a description of the ControlPartCode data type.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

InvokeControlUserPaneIdleUPP

Invokes a user pane idle UPP.

void InvokeControlUserPaneIdleUPP (
   ControlRef control,
   ControlUserPaneIdleUPP userUPP
);

Parameters

control: The control.
userUPP: The UPP that is to be activated.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

InvokeControlUserPaneKeyDownUPP

Invokes a user pane key down UPP.

ControlPartCode InvokeControlUserPaneKeyDownUPP (
   ControlRef control,
   SInt16 keyCode,
   SInt16 charCode,
   SInt16 modifiers,
   ControlUserPaneKeyDownUPP userUPP
);

Parameters

control: The control.
keyCode: The key code.
charCode: The character code.
modifiers: The modifiers.
userUPP: The UPP that is to be activated.

Return Value

For a description of this data type, see ControlPartCode.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

InvokeControlUserPaneTrackingUPP

Invokes a user pane tracking UPP.

ControlPartCode InvokeControlUserPaneTrackingUPP (
   ControlRef control,
   Point startPt,
   ControlActionUPP actionProc,
   ControlUserPaneTrackingUPP userUPP
);

Parameters

control: The control.
startPt: The starting point.
actionProc: The action proc.
userUPP: The UPP that is to be activated.

Return Value

For a description of this data type, see ControlPartCode.

Availability

Available in Mac OS X v10.0 and later.

Declared In

HIContainerViews.h

InvokeEditUnicodePostUpdateUPP

Invokes a Unicode post update UPP.

Boolean InvokeEditUnicodePostUpdateUPP (
   UniCharArrayHandle uniText,
   UniCharCount uniTextLength,
   UniCharArrayOffset iStartOffset,
   UniCharArrayOffset iEndOffset,
   void *refcon,
   EditUnicodePostUpdateUPP userUPP
);

Parameters

uniText: The UPP that is to be activated.
uniTextLength: The length of text in Unitext parameter.
iStartOffset: The starting offset.
iEndOffset: The ending offset.
refcon: The refcon.
userUPP: The UPP that is to be activated.

Return Value

Availability

Available in Mac OS X v10.0 and later.

Declared In

HITextViews.h

IsAutomaticControlDragTrackingEnabledForWindow

Indicates whether automatic drag tracking is enabled for the specified window.

OSStatus IsAutomaticControlDragTrackingEnabledForWindow (
   WindowRef inWindow,
   Boolean *outTracks
);

Parameters

inWindow
outTracks: On output, a pointer to a Boolean whose value is true if the Control Manager’s automatic drag tracking is enabled for the window; otherwise, false.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

For more information on automatic drag tracking, see SetAutomaticControlDragTrackingEnabledForWindow.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

IsControlActive

Returns whether a control is active.

Boolean IsControlActive (
   ControlRef inControl
);

Parameters

inControl: A handle to the control to be examined.

Return Value

A Boolean whose value is true if the control is active; otherwise, false.

Discussion

If you wish to determine whether a control is active, you should call IsControlActive instead of testing the contrlHilite field of the control structure.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

IsControlDragTrackingEnabled

Indicates whether a control’s drag track and receive support is enabled.

OSStatus IsControlDragTrackingEnabled (
   ControlRef inControl,
   Boolean *outTracks
);

Parameters

inControl: .
outTracks: On output, a pointer to a Boolean whose value is true if automatic drag tracking and receive support is enabled for the control; otherwise, false.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

Call this function to determine whether drag and drop support is enabled for a control. Some controls don’t support drag and drop; these controls don’t track or receive drags even if the outTracks parameter indicates a value of true.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

IsControlEnabled

Indicates whether a control is enabled.

Boolean IsControlEnabled (
   ControlRef inControl
);

Parameters

inControl: The control that is to be queried.

Return Value

A Boolean whose value is true if the control is enabled; otherwise, false.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Custom_HIView_Tutorial

Declared In

Controls.h

IsControlHilited

Indicates whether or not the control is highlighted.

Boolean IsControlHilited (
   ControlRef control
);

Parameters

control: The control that is to be queried.

Return Value

A Boolean whose value is true if the control is highlighted; otherwise, false.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

IsControlVisible

Determines whether a control is visible.

Boolean IsControlVisible (
   ControlRef inControl
);

Parameters

inControl: A handle to the control to be examined.

Return Value

If true, the control is visible. If false, the control is hidden.

Discussion

If you want to determine whether a control is visible, call IsControlVisible. Note that this function indicates the actual user visibility; if the control is marked visible, but its owning window or view is hidden, isControlVisible returns false. (In compositing mode, if a window is hidden, its root view is also marked as hidden. Similarly, any subviews of a hidden view are considered hidden.) A control’s latent visibility (its visibility ignoring the visibility of its parents) can be determined by calling the HIView function HIViewIsLatentlyVisible.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

IsValidControlHandle

Reports whether a given handle is a control handle.

Boolean IsValidControlHandle (
   ControlRef theControl
);

Parameters

theControl: A value of type ControlHandle. Pass the handle to be examined.

Return Value

true if the specified handle is a valid control handle; otherwise, false.

Discussion

The IsValidControlHandle function confirms whether a given handle is a valid control handle, but it does not check the validity of the data contained in the control itself.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

MLTE_CustomScrolling

Declared In

Controls.h

KillControls

Removes all of the controls from a window that you wish to keep.

void KillControls (
   WindowRef theWindow
);

Parameters

theWindow: A pointer to the window whose controls you wish to remove.

Discussion

The KillControls function disposes of all controls associated with the specified window. To remove just one control, use DisposeControl. If an embedding hierarchy is present, KillControls disposes of the controls embedded within a control before disposing of the container control.

You should use KillControls when you wish to retain the window but dispose of its controls. The Window Manager functions CloseWindow and DisposeWindow automatically remove all controls associated with the window and release the memory the controls occupy.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

MoveControl

Moves a control within its window.

void MoveControl (
   ControlRef theControl,
   SInt16 h,
   SInt16 v
);

Parameters

theControl: A handle to the control you wish to move.
h: The horizontal coordinate (local to the control’s window) of the new location of the upper-left corner of the control’s rectangle.
v: The vertical coordinate (local to the control’s window) of the new location of the upper-left corner of the control’s rectangle.

Discussion

The MoveControl function moves the control to the new location specified by the h and v parameters, using them to change the rectangle specified in the contrlRect field of the control structure. When the control is visible, MoveControl first hides it and then redraws it at its new location.

For example, if the user resizes a document window that contains a scroll bar, your application can use MoveControl to move the scroll bar to its new location.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

NewControlActionUPP

Creates a UPP for a control action callback function.

ControlActionUPP NewControlActionUPP (
   ControlActionProcPtr userRoutine
);

Parameters

userRoutine: A pointer to your control action callback function. See ControlActionProcPtr for information about defining this function.

Return Value

A UPP to your control action callback function.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

Controls.h

NewControlCNTLToCollectionUPP

Creates a UPP for a control-to-collection callback function.

ControlCNTLToCollectionUPP NewControlCNTLToCollectionUPP (
   ControlCNTLToCollectionProcPtr userRoutine
);

Return Value

A UPP to your control-to-collection callback function.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

NewControlColorUPP

Not recommended

ControlColorUPP NewControlColorUPP (
   ControlColorProcPtr userRoutine
);

Carbon Porting Notes

Instead of specifying a callback to redraw your background, you should make the background a control and then embed your other controls within it.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

NewControlEditTextValidationUPP

Creates a UPP for a control edit text validation callback function.

ControlEditTextValidationUPP NewControlEditTextValidationUPP (
   ControlEditTextValidationProcPtr userRoutine
);

Return Value

Availability

Available in Mac OS X v10.0 and later.

Declared In

HITextViews.h

NewControlKeyFilterUPP

ControlKeyFilterUPP NewControlKeyFilterUPP (
   ControlKeyFilterProcPtr userRoutine
);

Return Value

Availability

Available in Mac OS X v10.0 and later.

Declared In

Controls.h

NewControlUserPaneActivateUPP

ControlUserPaneActivateUPP NewControlUserPaneActivateUPP (
   ControlUserPaneActivateProcPtr userRoutine
);

Return Value

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

HTMLUserPane

Declared In

HIContainerViews.h

NewControlUserPaneBackgroundUPP

ControlUserPaneBackgroundUPP NewControlUserPaneBackgroundUPP (
   ControlUserPaneBackgroundProcPtr userRoutine
);

Return Value

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIContainerViews.h

NewControlUserPaneDrawUPP

ControlUserPaneDrawUPP NewControlUserPaneDrawUPP (
   ControlUserPaneDrawProcPtr userRoutine
);

Return Value

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

HTMLUserPane

Declared In

HIContainerViews.h

NewControlUserPaneFocusUPP

ControlUserPaneFocusUPP NewControlUserPaneFocusUPP (
   ControlUserPaneFocusProcPtr userRoutine
);

Return Value

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

HTMLUserPane

Declared In

HIContainerViews.h

NewControlUserPaneHitTestUPP

ControlUserPaneHitTestUPP NewControlUserPaneHitTestUPP (
   ControlUserPaneHitTestProcPtr userRoutine
);

Return Value

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

HTMLUserPane

Declared In

HIContainerViews.h

NewControlUserPaneIdleUPP

ControlUserPaneIdleUPP NewControlUserPaneIdleUPP (
   ControlUserPaneIdleProcPtr userRoutine
);

Return Value

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

HTMLUserPane

Declared In

HIContainerViews.h

NewControlUserPaneKeyDownUPP

ControlUserPaneKeyDownUPP NewControlUserPaneKeyDownUPP (
   ControlUserPaneKeyDownProcPtr userRoutine
);

Return Value

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

HTMLUserPane

Declared In

HIContainerViews.h

NewControlUserPaneTrackingUPP

ControlUserPaneTrackingUPP NewControlUserPaneTrackingUPP (
   ControlUserPaneTrackingProcPtr userRoutine
);

Return Value

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

HTMLUserPane

Declared In

HIContainerViews.h

NewEditUnicodePostUpdateUPP

EditUnicodePostUpdateUPP NewEditUnicodePostUpdateUPP (
   EditUnicodePostUpdateProcPtr userRoutine
);

Return Value

Availability

Available in Mac OS X v10.0 and later.

Declared In

HITextViews.h

RegisterControlDefinition

Registers an old-style control definition.

OSStatus RegisterControlDefinition (
   SInt16 inCDEFResID,
   const ControlDefSpec *inControlDef,
   ControlCNTLToCollectionUPP inConversionProc
);

Parameters

CDEFResID: The virtual resource ID you want to assign to the control definition.
def: A pointer to the control definition function you want to register. Pass NULL if you want to unregister a given CDEF proc ID.
conversionProc: A UPP to a callback function to place initialization data (such as the bounds, min and max values, and so on) into a collection.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

Mac OS X does not allow you to store custom control definitions in resources. However, some older functions such as GetNewControl expect a resource ID when creating controls. To work around this, you can use RegisterControlDefinition to register “virtual” resource IDs for your control definition functions.

Since custom control definitions receive initialization data as a collection in the param parameter, you must provide a callback to properly package this information. See “Control Collection Tag Constants” for a list of tags you can apply to the collection. If you do not supply a conversion callback, the Control Manager sends an empty collection to your control definition.

To unregister a control definition, pass NULL in the inDefSpec parameter for a given CDEF proc ID.

In Mac OS X v10.2 and later, you should consider reimplementing your custom control code using custom HIViews. See Introducing HIView for more information.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

RemoveControlProperty

Removes a piece of data that has been previously associated with a control.

OSStatus RemoveControlProperty (
   ControlRef control,
   OSType propertyCreator,
   OSType propertyTag
);

Parameters

control: A handle to the control whose associated data you wish to remove.
propertyCreator: Your program’s signature, as registered through Apple Developer Technical Support. If your program is of a type that would not normally have a signature (for example, a plug-in), you should still register and use a signature in this case, even though your program’s file may not have the same creator code as the signature that you register. The ’macs' property signature is reserved for the system and should not be used.
propertyTag: The application-defined code identifying the associated data.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

Your application may dissociate data it has previously set with the SetControlProperty function by calling the RemoveControlProperty function.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

ReverseKeyboardFocus

Returns keyboard focus to the prior focusable control in a window.

OSErr ReverseKeyboardFocus (
   WindowRef inWindow
);

Parameters

inWindow: A pointer to the window for which to reverse keyboard focus.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The ReverseKeyboardFocus function reverses the progression of keyboard focus, skipping over deactivated and hidden controls until it finds the previous control to receive keyboard focus in the window.

When ReverseKeyboardFocus is called, the Control Manager calls your control definition function and passes kControlMsgFocus in its message parameter and kControlFocusPrevPart in its param parameter. In response to this message, your control definition function should change keyboard focus to its previous part, the entire control, or remove keyboard focus from the control, depending upon the circumstances. See ControlDefProcPtr for a discussion of possible responses to this message.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

SendControlMessage

Sends a message to a control definition function. (Deprecated. For custom controls, use a custom HIView instead of a control definition function. See HIView Programming Guide.)

Not recommended

SInt32 SendControlMessage (
   ControlRef inControl,
   SInt16 inMessage,
   void *inParam
);

Parameters

inControl: A handle to the control that is to receive a low-level message. For a description of this data type, see ControlRef.
inMessage: A bit field representing the message(s) you wish to send; see ControlDefProcPtr.
inParam: The message-dependent data passed in the param parameter of the control definition function.

Return Value

Varying data, depending upon the message sent in the inMessage parameter.

Discussion

Your application does not normally need to call the SendControlMessage function. If you have a special need to call a control definition function directly, call SendControlMessage to access and manipulate the control’s attributes.

Before calling SendControlMessage, you should determine whether the control supports the specific message you wish to send by calling GetControlFeatures and examining the feature bit field returned. If there are no feature bits returned that correspond to the message you wish to send (for messages 0 through 12), you can assume that all system controls support that message.

Carbon Porting Notes

Don’t send messages to standard system control definitions.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

SetAutomaticControlDragTrackingEnabledForWindow

Enables or disables automatic drag tracking for a window.

OSStatus SetAutomaticControlDragTrackingEnabledForWindow (
   WindowRef inWindow,
   Boolean inTracks
);

Parameters

inWindow
inTracks: A Boolean whose value is true to enable the Control Manager’s automatic drag tracking support or false to disable automatic drag tracking support.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

By default, your application is responsible for installing drag tracking and receive handlers on a given window. The Control Manager, however, has support for automatically tracking and receiving drags over controls that you can enable by calling this function with the inTracks parameter set to true.

The Control Manager automatic drag tracking detects the control the drag is over and calls HandleControlDragTracking and HandleControlDragReceive appropriately. By default, the Control Manager’s automatic drag tracking is disabled.

Earlier versions of system software enabled automatic drag tracking by default, but as of Mac OS X v10.1.3, Mac OS 9.2, and CarbonLib 1.4, you must call this function to enable automatic drag tracking.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

SetBevelButtonContentInfo

Sets the content information for a bevel button.

OSErr SetBevelButtonContentInfo (
   ControlRef inButton,
   ControlButtonContentInfoPtr inContent
);

Parameters

inButton: The control reference for the bevel button whose content information is to be set.
inContent: A value of type ControlButtonContentInfoPtr for the content information that is to be set.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

SetBevelButtonGraphicAlignment

Sets the alignment for a bevel button.

OSErr SetBevelButtonGraphicAlignment (
   ControlRef inButton,
   ControlButtonGraphicAlignment inAlign,
   SInt16 inHOffset,
   SInt16 inVOffset
);

Parameters

inButton: The control reference for the bevel button that is to be aligned.
inAlign: The alignment that is to be set. For possible values, see “Bevel Button Graphic Alignment Constants.”
inHOffset: The horizontal offset, in pixels, that is to be applied to the alignment specified by the inAlign parameter.
inVOffset: The vertical offset, in pixels, that is to be applied to the alignment specified by the inAlign parameter.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

SetBevelButtonMenuValue

Sets the value of a bevel button menu.

OSErr SetBevelButtonMenuValue (
   ControlRef inButton,
   MenuItemIndex inValue
);

Parameters

inButton: The control reference for the bevel button whose menu value is to be set.
inValue: The value that is to be set.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

SetBevelButtonTextAlignment

Sets the alignment of the text for a bevel button.

OSErr SetBevelButtonTextAlignment (
   ControlRef inButton,
   ControlButtonTextAlignment inAlign,
   SInt16 inHOffset
);

Parameters

inButton: The control reference for the bevel button whose text is to be aligned.
inAlign: The alignment that is to be set. For possible values, see“Bevel Button Text Alignment Constants .”
inHOffset: The horizontal offset, in pixels, that is to be applied to the alignment specified by the inAlign parameter.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

SetBevelButtonTextPlacement

Sets the placement for bevel button text.

OSErr SetBevelButtonTextPlacement (
   ControlRef inButton,
   ControlButtonTextPlacement inWhere
);

Parameters

inButton: The control reference for the bevel button whose text is to be placed.
inWhere: The placement that is to be set. For possible values, see “Bevel Button Text Placement Constants .”

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

SetBevelButtonTransform

Sets the transform for a bevel button.

OSErr SetBevelButtonTransform (
   ControlRef inButton,
   IconTransformType transform
);

Parameters

inButton: The control reference for the bevel button whose text is to be placed.
transform: The transform that is to be set. For possible values, see the IconTransformType enumeration described in the Icon Services and Utilities Reference.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

HIButtonViews.h

SetControl32BitMaximum

Changes the maximum setting of a control and, if appropriate, redraws it accordingly.

void SetControl32BitMaximum (
   ControlRef theControl,
   SInt32 newMaximum
);

Parameters

theControl: A handle to the control whose maximum setting you wish to change. For a description of this data type, see ControlRef.
newMaximum: The new maximum setting of the control. In general, to avoid unpredictable behavior, do not set the maximum control value lower than the current minimum value.

Discussion

Your application may use the SetControl32BitMaximum function to set a 32-bit value as the maximum setting for a control.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

SetControl32BitMinimum

Changes the minimum setting of a control and, if appropriate, redraws it accordingly.

void SetControl32BitMinimum (
   ControlRef theControl,
   SInt32 newMinimum
);

Parameters

theControl: A handle to the control whose minimum setting you wish to change. For a description of this data type, see ControlRef.
newMinimum: A value specifying the new minimum setting of the control. In general, to avoid unpredictable behavior, do not set the minimum control value higher than the current maximum value.

Discussion

Your application may use the SetControl32BitMinimum function to set a 32-bit value as the minimum setting for a control.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Custom_HIView_Tutorial

Declared In

Controls.h

SetControl32BitValue

Changes the current setting of a control and redraws it accordingly.

void SetControl32BitValue (
   ControlRef theControl,
   SInt32 newValue
);

Parameters

theControl: A handle to the control whose current setting you wish to change. For a description of this data type, see ControlRef.
newValue: A value specifying the new setting of the control. If the specified value is less than the minimum setting for the control, SetControl32BitValue sets the current setting of the control to its minimum setting. If the specified value is greater than the maximum setting, SetControl32BitValue sets the control to its maximum.

Discussion

Your application may use the SetControl32BitValue function to set a 32-bit value as the current setting for a control.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

SetControlAction

Sets the action function for a control.

void SetControlAction (
   ControlRef theControl,
   ControlActionUPP actionProc
);

Parameters

theControl: A handle to the control whose action function is to be changed.
actionProc: A universal procedure pointer to an action function defining what action your application takes while the user holds down the mouse button. See ControlActionProcPtr for a description of an action function.

Discussion

The SetControlAction function associates the action function specified by actionProc with the control specified by theControl. If the cursor is in the specified control, the HandleControlClick and TrackControl functions call the specified action function when the user holds down the mouse button. You must provide the action function, and it must define some action to perform repeatedly as long as the user holds down the mouse button. HandleControlUnderClick and TrackControl always highlight and drag the control as appropriate.

SetControlAction should be used to set the application-defined action function for providing live feedback for standard system scroll bar controls.

Note that the action function associated with a control is used by TrackControl only if you set the action function to TrackControl to Pointer(–1). Also, an action function can be specified in the actionProc parameter to TrackControl, so you don’t have to call SetControlAction to change it.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

SetControlBounds

Sets the bounds of a control.

void SetControlBounds (
   ControlRef control,
   const Rect *bounds
);

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

SetControlColorProc

Associates a ControlColorUPP with a given Control, thereby allowing you to bypass the embedding hierarchy-based color setup of SetUpControlBackground/SetUpControlTextColor and replace it with your own.

Not recommended

OSStatus SetControlColorProc (
   ControlRef inControl,
   ControlColorUPP inProc
);

Parameters

inControl: The ControlRef with whom the color proc should be associated. For a description of this data type, see ControlRef.
inProc: The color proc to associate with the ControlRef. If you pass NULL, the ControlRef will be dissociated from any previously installed color proc. For a description of the ControlColorUPP data type,

Return Value

A result code. See “Control Manager Result Codes.” An OSStatus code indicating success or failure. The most likely error is a controlHandleInvalidErr resulting from a bad ControlRef.

Discussion

Before an embedded Control can erase, it calls SetUpControlBackground to have its background color set up by any parent controls. Similarly, any Control that draws text calls SetUpControlTextColor to have the appropriate text color set up. This allows certain controls (such as tabs and placards) to offer special backgrounds and text colors for any child controls. By default, the set up functions only move up the Control Manager embedding hierarchy looking for a parent which has a special background.

This is fine in a plain vanilla embedding case, but many application frameworks find it troublesome; if there are interesting views between two controls in the embedding hierarchy, the framework needs to be in charge of the background and text colors, otherwise drawing defects will occur.

You can only associate a single color proc with a given ControlRef.

Carbon Porting Notes

Instead of specifying a callback to redraw your background, you should make the background a control and then embed your other controls within it.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

SetControlCommandID

Sets the command ID for a control.

OSStatus SetControlCommandID (
   ControlRef inControl,
   UInt32 inCommandID
);

Parameters

inControl: The control to set.
inCommandID: The command ID that is to be set.

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

SetControlData

Sets control-specific data.

OSErr SetControlData (
   ControlRef inControl,
   ControlPartCode inPart,
   ResType inTagName,
   Size inSize,
   const void *inData
);

Parameters

inControl: A handle to the control for which data is to be set.
inPart: The part code of the control part for which data is to be set; see “Control Meta Part Code Constants,” “Control Part Code Constants ,” and “ Control State Part Code Constants.” Passing kControlEntireControl indicates that either the control has no parts or the data is not tied to any specific part of the control.
inTagName: A constant representing the control-specific data you wish to set see the data tag constants in the “Control Manager Constants” section.
inSize: The size (in bytes) of the data pointed to by the inData parameter. For variable-length control data, pass the value returned in the outMaxSize parameter of GetControlDataSize in the inSize parameter. The number of bytes must match the actual data size.
inData: A pointer to a buffer allocated by your application. This buffer contains the data that you are sending to the control. After calling SetControlData, your application is responsible for disposing of this buffer, if necessary, as information is copied by control.

Return Value

A result code. See “Control Manager Result Codes.” The result code errDataNotSupported indicates that the inTagName parameter is not valid.

Discussion

The SetControlData function sets control-specific data represented by the value in the inTagName parameter to the data pointed to by the inData parameter. SetControlData could be used, for example, to switch a progress indicator from a determinate to indeterminate state. For a list of the control attributes that can be set, see the data tag constants in the “Control Manager Constants” section.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

SetControlDataHandle

(Deprecated. Use custom HIViews instead of custom CDEFs. See HIView Programming Guide.)

Not recommended

void SetControlDataHandle (
   ControlRef control,
   Handle dataHandle
);

Carbon Porting Notes

Only useful for message-based custom controls (CDEFs).

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

SetControlDragTrackingEnabled

Sets the drag tracking state for a control.

OSStatus SetControlDragTrackingEnabled (
   ControlRef inControl,
   Boolean inTracks
);

Parameters

inControl: The control for which the drag tracking state is to be set.
inTracks: A Boolean whose value is true if you want the control to track and receive drags or false if want to disable support for drag and drop.

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

Call this function to enable a control’s support for drag and drop. If you don’t enable drag and drop support, the control won’t track drags.

Some controls don’t support drag and drop; these controls won’t track or receive drags even if you call this function with the inTracks parameter set to true.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

SetControlFontStyle

Sets the font style for a control.

OSErr SetControlFontStyle (
   ControlRef inControl,
   const ControlFontStyleRec *inStyle
);

Parameters

inControl: A handle to the control whose font style is to be set. For a description of this data type, see ControlRef.
inStyle: A pointer to a ControlFontStyleRec structure. If the flags field is cleared, the control uses the system font unless the control variant kControlUsesOwningWindowsFontVariant has been specified (control uses window font).

Return Value

A result code. See “Control Manager Result Codes.”

Discussion

The SetControlFontStyle function sets the font style for a given control. To specify the font for controls in a dialog box, it is generally easier to use the dialog font table resource. SetControlFontStyle allows you to override a control’s default font (system or window font, depending upon whether the control variant kControlUsesOwningWindowsFontVariant has been specified). Once you have set a control’s font with this function, you can cause the control to revert to its default font by passing a control font style structure with a cleared flags field in the inStyle parameter.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

NSLMiniBrowser

Declared In

Controls.h

SetControlID

Sets a control’s ID.

OSStatus SetControlID (
   ControlRef inControl,
   const ControlID *inID
);

Return Value

A result code. See “Control Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

SetControlMaximum

Changes the maximum setting of a control and redraws its indicator or scroll box accordingly. (Deprecated. Use SetControl32BitMaximum instead.)

Not recommended

void SetControlMaximum (
   ControlRef theControl,
   SInt16 newMaximum
);

Parameters

theControl: A handle to the control whose maximum setting you wish to change.
newMaximum: The new maximum setting.

Discussion

The SetControlMaximum function changes the maximum value of a control to the value specified by the newMaximum parameter and redraws its indicator or scroll box to reflect its new range.

When you set the maximum setting of a scroll bar equal to its minimum setting, the control definition function makes the scroll bar inactive. When you make the maximum setting exceed the minimum, the control definition function makes the scroll bar active again.

When you create a control, you specify an initial maximum setting either in the control resource or in the max parameter of the function NewControl. To determine a control’s current maximum setting, use the function GetControlMaximum.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

SetControlMinimum

Changes the minimum setting of a control and redraws its indicator or scroll box accordingly. (Deprecated. Use SetControl32BitMinimum instead.)

Not recommended

void SetControlMinimum (
   ControlRef theControl,
   SInt16 newMinimum
);

Parameters

theControl: A handle to the control whose minimum setting you wish to change. For a description of this data type, see ControlRef.
newMinimum: The new minimum setting.

Discussion

The SetControlMinimum function changes the control’s minimum value to the value specified by the newMinimum parameter and redraws its indicator or scroll box to reflect its new range.

When you create a control, you specify an initial minimum setting either in the control resource or in the min parameter of the NewControl function. To obtain a control’s current minimum setting, use the function GetControlMinimum.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

Controls.h

SetControlPopupMenuHandle

Sets the menu handle for a pop-up control.

void SetControlPopupMenuHandle (
   ControlRef control,
   MenuRef popupMenu
);

Parameters

control: The pop-up control.
popupMenu: The menu handle to set.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

SetControlPopupMenuID

Sets the menu ID for a pop-up control

void SetControlPopupMenuID (
   ControlRef control,
   short menuID
);

Parameters

control: The pop-up control.
menuID: The menu ID to set.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Controls.h

SetControlProperty

Associates data with a control.

OSStatus SetControlProperty (
   ControlRef control,
   OSType propertyCreator,
   OSType propertyTag,
   ByteCount propertySize,
   const void *propertyData
);

Parameters

control: A handle to the control with which you wish to associate data. For a description of this data type, see ControlRef.
propertyCreator</