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. See .

If you are using standard system controls, default colors are used and the control color table resource is ignored. To use colors other than the default colors, you must write your own custom control definition function.

VERSION NOTES

Changed with Appearance Manager 1.0 to support embedding hierarchies.

SEE ALSO

NewControl .

NewControl

Creates a control based on parameter data.

pascal ControlHandle NewControl (
                     WindowPtr owningWindow,
                     const Rect *boundsRect,
                     ConstStr255Param controlTitle,
                     Boolean initiallyVisible,
                     SInt16 initialValue,
                     SInt16 minimumValue,
                     SInt16 maximumValue,
                     SInt16 procID,
                     SInt32 controlReference);

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; see Settings Values for Standard Controls .

minimumValue

The minimum setting for the control; see Settings Values for Standard Controls .

maximumValue

The maximum setting for the control; see Settings Values for Standard Controls .

procID

The control definition ID; see Table 1-1 . If the control definition function isn't in memory, it is read in.

controlReference

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

function result

Returns a handle to the control described in its parameters. If NewControl runs out of memory or fails, it returns nil .

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 can 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. see Embedding Controls .

If you are using standard system controls, default colors are used and the control color table resource is ignored. To use colors other than the default colors, write your own custom control definition function.

VERSION NOTES

Changed with Appearance Manager 1.0 to support embedding hierarchies.

SEE ALSO

GetNewControl .

DisposeControl

Removes a control and any of its embedded controls from a window.

pascal void DisposeControl (ControlHandle theControl);

theControl

A handle to the control you wish to remove.

DISCUSSION

The DisposeControl function removes the specified control (and any embedded controls it may possess) from the screen, deletes it from the window's control list, and releases the memory occupied by the control structure and any data structures associated with the control. Passing the root control to this function is the effectively the same as calling KillControls . If an embedding hierarchy is present, DisposeControl disposes of the controls embedded within a control before disposing of the container control.

You should use DisposeControl when you wish to retain the window but dispose of one of its controls. The Window Manager functions CloseWindow and DisposeWindow automatically dispose of all controls associated with the given window.

VERSION NOTES

Changed with Appearance Manager 1.0 to support embedding hierarchies.

SEE ALSO

Embedding Controls .

KillControls

Removes all controls in a specified window.

pascal void KillControls (WindowPtr theWindow);

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 dispose of all controls associated with the given window.

VERSION NOTES

Changed with Appearance Manager 1.0 to support embedding hierarchies.

SEE ALSO

Embedding Controls .