Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

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:

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
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
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
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
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
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
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
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
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
Declared In
HIProgressViews.h