ADC Home > Reference Library > Reference > Carbon > User Experience > Control Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Control Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

CreateEditTextControl

Creates a new edit text control. (Deprecated in Mac OS X v10.4. Use CreateEditUnicodeTextControl instead.)

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

Parameters
window

The window in which the control is to be placed. 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 the field is to display entered text 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.

useInlineInput

A Boolean indicating whether the control is to accept inline input. Pass true to accept inline input; otherwise pass false.

style

The control’s font style, size, color, and so on. May be NULL.

outControl

On return, the new control.

Return Value

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

Availability
Declared In
ControlDefinitions.h

IdleControls

Performs idle event processing. (Deprecated in Mac OS X v10.4. You should remove all calls to IdleControls because it uses unnecessary processor time. System-supplied controls do not respond to IdleControls in Mac OS X.)

Not recommended

void IdleControls (
   WindowRef inWindow
);

Parameters
inWindow

A pointer to a window containing controls that support idle events.

Discussion

Your application should call the IdleControls function to give idle time to any controls that want the kControlMsgIdle message. IdleControls calls the control with an idle event so the control can do idle-time processing. You should call IdleControls at least once in your event loop. See ControlDefProcPtr for more details on how a control definition function should handle idle processing.

Special Considerations

Idle events are not recommended. If you have a custom control that needs time to perform tasks (such as animation), use Carbon Event timers instead. See Carbon Event Manager Programming Guide for more details.

Availability
Declared In
Controls.h

Deprecated in Mac OS X v10.5

CreateCustomControl

Creates a custom control. (Deprecated in Mac OS X v10.5. Register your custom subclass of the HIView class and create an instance of your class using HIObjectCreate.)

OSStatus CreateCustomControl (
   WindowRef owningWindow,
   const Rect *contBounds,
   const ControlDefSpec *def,
   Collection initData,
   ControlRef *outControl
);

Parameters
owningWindow

The window that is to contain the control. This parameter may be NULL in Mac OS X v10.3 and later.

contBounds

The bounds of the new control in the window’s local coordinates.

def

A pointer to the control definition function you want to associate with the new control.

initData

The initial state of the control. For additional information, see “Control Collection Tag Constants.”

outControl

On return, outControl points to the new control.

Return Value

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

Availability
Declared In
Controls.h

DisposeControlDefUPP

Disposes of a control definition UPP. (Deprecated in Mac OS X v10.5. Use a custom HIView to draw a custom control.)

void DisposeControlDefUPP (
   ControlDefUPP userUPP
);

Parameters
userUPP

The UPP that is to be disposed of.

Availability
Declared In
Controls.h

GetControlTitle

Obtains the title of a control. (Deprecated in Mac OS X v10.5. Use HIViewCopyText or CopyControlTitleAsCFString instead.)

void GetControlTitle (
   ControlRef theControl,
   Str255 title
);

Parameters
theControl

A handle to the control whose title you want to determine.

title

On input, a pascal string. On output, the title of the control.

Discussion

The GetControlTitle function produces the title of the specified control, which is stored in the contrlTitle field of the control structure.

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

Availability
Declared In
Controls.h

HandleControlKey

Sends a keyboard event to a control with keyboard focus. (Deprecated in Mac OS X v10.5. For HIView-based controls, send the view a kEventTextInputUnicodeForKeyEvent event.)

ControlPartCode HandleControlKey (
   ControlRef inControl,
   SInt16 inKeyCode,
   SInt16 inCharCode,
   EventModifiers inModifiers
);

Parameters
inControl

A handle to the control that currently has keyboard focus.

inKeyCode

The virtual key code, derived from the event structure. This value represents the key pressed or released by the user. It is always the same for a specific physical key on a particular keyboard regardless of which modifier keys were also pressed.

inCharCode

A character, derived from the event structure. The value that is generated depends on the virtual key code, the state of the modifier keys, and the current'KCHR' resource.

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.

Return Value

The part code that was hit during the keyboard event; 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

If you have determined that a keyboard event has occurred in a given window, before calling the HandleControlKey function, call GetKeyboardFocus to get the handle to the control that currently has keyboard focus. The HandleControlKey function passes the values specified in its inKeyCode, inCharCode, and inModifiers parameters to control definition functions that set the kControlSupportsFocus feature bit.

Availability
Declared In
Controls.h

InvokeControlDefUPP

Invokes a control definition UPP. (Deprecated in Mac OS X v10.5. Use a custom HIView to draw a custom control.)

SInt32 InvokeControlDefUPP (
   SInt16 varCode,
   ControlRef theControl,
   ControlDefProcMessage message,
   SInt32 param,
   ControlDefUPP userUPP
);

Parameters
varCode

The variation code.

theControl

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

message

The message.

param

The maximum value of the control.

userUPP

The UPP that is to be invoked.

Return Value
Availability
Declared In
Controls.h

NewControl

Creates a control based on parameter data. (Deprecated in Mac OS X v10.5. Use the specific control creation function instead (for example, CreateCheckBoxControl).)

ControlRef NewControl (
   WindowRef owningWindow,
   const Rect *boundsRect,
   ConstStr255Param controlTitle,
   Boolean initiallyVisible,
   SInt16 initialValue,
   SInt16 minimumValue,
   SInt16 maximumValue,
   SInt16 procID,
   SRefCon controlReference
);

Parameters
owningWindow

A pointer to the window in which you want to place the control. All coordinates pertaining to the control are interpreted in this window’s local coordinate system.

boundsRect

A pointer to a rectangle, specified in the given window’s local coordinates, that encloses the control and thus determines its size and location. When specifying this rectangle, you should follow the guidelines presented in “Dialog Box Layout”, in Mac OS 8 Human Interface Guidelines, for control placement and alignment.

controlTitle

The title string, used for push buttons, checkboxes, radio buttons, and pop-up menus. When specifying a multiple-line title, separate the lines with the ASCII character code 0x0D (carriage return). For controls that don’t use titles, pass an empty string.

initiallyVisible

A Boolean value specifying the visible/invisible state for the control. If you pass true in this parameter, NewControl draws the control immediately, without using your window’s standard updating mechanism. If you pass false, you must later use ShowControl to display the control.

initialValue

The initial setting for the control. For sliders and scrollbars, pass the appropriate integer value. For checkboxes and radio buttons, pass the constant indicating the current setting (as defined in “Checkbox Value Constants” and “Radio Button Value Constants.” For plain buttons that do not retain a setting, pass 0.

minimumValue

The minimum setting for the control. For sliders and scrollbars, pass the appropriate minimum integer value. For checkboxes and radio buttons, pass 0 (or the equivalent constant from “Checkbox Value Constants” or “Radio Button Value Constants”). For plain buttons that do not retain a setting, pass 0.

maximumValue

The maximum setting for the control. For sliders and scrollbars, pass the appropriate maximum integer value. For scroll bars, if the maximum value is equal to the minimum value, the control definition function automatically disables the scroll bar. For checkboxes and radio buttons, pass 1 (or the equivalent constant defined in “Checkbox Value Constants” or “Radio Button Value Constants”). For plain buttons that do not retain a setting, pass 0.

procID

The control definition ID. If the control definition function isn’t in memory, it is read in. On Mac OS X, if you do not pass a valid procID (that is, if it does not correspond to a CDEF resource), NewControl will not create a control and will simply return NULL. On Mac OS 9 and earlier, passing an invalid procID will cause NewControl to create a pushbutton control.

controlReference

The control’s reference value, which is set and used only by your application.

Return Value

A handle to the control described in its parameters. If NewControl runs out of memory or fails, it returns NULL. For a description of this data type, see ControlRef.

Discussion

The NewControl function creates a control structure from the information you specify in its parameters, 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. Generally, you should use the function GetNewControl instead of NewControl, because GetNewControl is a resource-based control-creation function that allows you to localize your application without recompiling.

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

Carbon Porting Notes

Carbon does not support custom control definitions stored in'CDEF' resources. If you want to specify a custom control definition for NewControl, you must compile your definition function directly in your application and then register the function by calling RegisterControlDefinition. When NewControl gets a procID value that doesn’t recognize, it checks a special mapping table to find the pointer that is registered for the resource ID embedded in the procID parameter. It then calls that function to implement your control.

Availability
Declared In
Controls.h

NewControlDefUPP

Creates a UPP for a control definition callback function. (Deprecated in Mac OS X v10.5. Use a custom HIView to draw a custom control.)

ControlDefUPP NewControlDefUPP (
   ControlDefProcPtr userRoutine
);

Return Value

A UPP to your control definition callback function.

Availability
Declared In
Controls.h

SetControlTitle

Changes the title of a control and redraws the control accordingly. (Deprecated in Mac OS X v10.5. Use HIViewSetText or SetControlTitleWithCFString instead.)

Not recommended

void SetControlTitle (
   ControlRef theControl,
   ConstStr255Param title
);

Parameters
theControl

A handle to a control, the title of which you want to change.

title

The new title for the control.

Discussion

The SetControlTitle function changes the contrlTitle field of the control structure to the given string and redraws the control, using the system font for the control title.

The Control Manager allows multiple lines of text in the titles of buttons, checkboxes, and radio buttons. When specifying a multiple-line title, separate the lines with the ASCII character code 0x0D (carriage return). If the control is a button, each line is horizontally centered, and the font leading is inserted between lines. (The height of each line is equal to the distance from the ascent line to the descent line plus the leading of the font used. Be sure to make the total height of the rectangle greater than the number of lines times this height.) If the control is a checkbox or a radio button, the text is justified as appropriate for the user’s current script system, and the checkbox or button is vertically centered within its rectangle.

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

Availability
Related Sample Code
Declared In
Controls.h

< Previous PageNext Page > Hide TOC

© 2002, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-03-26)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.