Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 5 - Control Manager / Control Manager Reference

Control Manager Routines / Creating Controls

GetNewControl
To create a control from a description in a control resource ('CNTL'), use the GetNewControl function.
FUNCTION GetNewControl (controlID: Integer; owner: WindowPtr)
                        : ControlHandle;
controlID
The resource ID of a control resource.
owner
A pointer to the window in which you want to attach the control.

DESCRIPTION
The GetNewControl function creates a control record from the information in the specified control resource, adds the control record 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 routines. After making a copy of the control resource, GetNewControl releases the memory occupied by the original control resource before returning.
If you provide a control color table resource with the same resource ID as the control resource, GetNewControl creates an auxiliary control record that uses the colors you specify in your control color table resource. If you don't provide a control color table, GetNewControl creates an auxiliary control record that uses the default control color table if the computer is running in 32-bit mode.
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 current setting, the maximum setting, the minimum setting, the reference value, and the title by using, respectively, the SetControlValue, SetControlMaximum, SetControlMinimum, SetControlReference, and SetControlTitle procedures. You can use the MoveControl and SizeControl procedures to change the control's rectangle. You can use the GetControlValue, GetControlMaximum, GetControlMinimum, GetControlReference, and GetControlTitle functions to determine the control values.
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 ShowControl procedure to make the control visible.
If GetNewControl can't read the control resource from the resource file, GetNewControl returns NIL.

SEE ALSO
See Listing 5-1 on page 5-15 and Listing 5-5 on page 5-21 for examples of how to use GetNewControl to create, respectively, a button and a scroll bar. For information about windows' control lists, see the chapter "Window Manager" in this book.