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

NewControl
To create a control, you can use the NewControl function, which accepts in its parameters the information that describes the control. Generally, you should instead use the GetNewControl function to create a control. The GetNewControl function takes information about the control from a control resource, and as a result your application is easier to modify or translate into other languages.
FUNCTION NewControl (theWindow: WindowPtr; boundsRect: Rect;
                     title: Str255; visible: Boolean; 
                     value: Integer; min: Integer; max: Integer;
                     procID: Integer; refCon: LongInt)
                     : ControlHandle;
theWindow
A pointer to the window in which you want to attach the control. All coordinates pertaining to the control are interpreted in this window's local coordinate system.
boundsRect
The rectangle, specified in the given window's local coordinates, that encloses the control and thus determines its size and location.
title
For controls that need a title--such as buttons, checkboxes, radio buttons, and pop-up menus--the string for that title. For controls that don't use titles, pass an empty string.
visible
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 the ShowControl procedure to display the control.
value
The initial setting for the control. For controls--such as buttons--that don't retain a setting, pass 0 in this parameter. For controls--such as checkboxes and radio buttons--that retain an on-or-off setting, pass 0 in this parameter for a control that is off, and pass 1 for a control that is on. For controls--such as scroll bars and sliders--that can take a range of settings, specify whatever value is appropriate within that range.
min
The minimum setting for the control. For controls--such as buttons--that don't retain a setting, pass 0 in this parameter. For controls--such as checkboxes and radio buttons--that retain an on-or-off setting, use 0 (meaning "off") for the minimum value. For controls--such as scroll bars and sliders--that can take a range of settings, specify whatever minimum value is appropriate.
max
The maximum setting for the control. For controls--such as buttons--that don't retain a setting, pass 1 in this parameter. For controls--such as checkboxes and radio buttons--that retain an on-or-off setting, use 1 (meaning "on") for the maximum value. For controls--such as scroll bars and sliders--that can take a range of settings, specify whatever maximum value is appropriate. When you make the maximum setting of a scroll bar equal to its minimum setting, the control definition function automatically makes the scroll bar inactive; when you make the maximum setting exceed the minimum, the control definition function makes the scroll bar active again.
procID
The control definition ID, which leads to the control definition function for this type of control. The control definition function is read into memory if it isn't already in memory. The control definition IDs and their constants for the standard controls are listed here. (You can also define your own control definition function and specify it the procID parameter.)
         CONST
            pushButProc        = 0;     {button}
            checkBoxProc       = 1;     {checkbox}
            radioButProc       = 2;     {radio button}
            useWFont           = 8;     {add to above to display }
                                        { title in window font}
            scrollBarProc      = 16;    {scroll bar}
            popupMenuProc      = 1008;  {pop-up menu}
            popupFixedWidth    = $0001; {add to popupMenuProc to }
                                        { use a fixed-width ctrl}

            popupUseAddResMenu = $0004; {add to popupMenuProc to }
                                        { specify a value of }
                                        { type ResType in the }
                                        { contrlRfCon field of }
                                        { the control record; }
                                        { Menu Manager adds }
                                        { resources of this type }
                                        { to the menu}
            popupUseWFont      = $0008; {add to popupMenuProc to }
                                        { display in window font}
refCon
The control's reference value, which is set and used only by
your application.

DESCRIPTION
The NewControl function creates a control record from the information you specify in its parameters, 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.
The NewControl function creates an auxiliary control record that uses the default control color table if the computer is running in 32-bit mode.
If you need to use colors other than the default colors for the control, create a control color table record and use the SetControlColor procedure.
When specifying the rectangle in the boundsRect parameter, keep the following guidelines in mind:

Buttons are drawn to fit the rectangle exactly. To accommodate the tallest characters in the system font, allow at least a 20-point difference between the top and bottom coordinates of the rectangle.
For checkboxes and radio buttons, there should be at least a 16-point difference between the top and bottom coordinates.
By convention, scroll bars are 16 pixels wide, so there should be a 16-point difference between the left and right (or top and bottom) coordinates. (If there isn't, the scroll bar is scaled to fit the rectangle.) A standard scroll bar should be at least 48 pixels long, to allow room for the scroll arrows and scroll box.

The Control Manager displays control titles in the system font. When specifying a title for the control in the title parameter, make sure the title fits in the control's rectangle; otherwise, NewControl truncates the title. For example, NewControl truncates the titles of checkboxes and radio buttons on the right in Roman scripts, and it centers and truncates both ends of the button titles.
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 $0D (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.
After you use NewControl 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.

SPECIAL CONSIDERATIONS
The title of a button, checkbox, radio button, or pop-up menu normally appears in the system font, which in Roman script systems is 12-point Chicago. Do not use a smaller font; some script systems, such as KanjiTalk, require 12-point fonts. You should generally use the system font in your controls; doing so will simplify localization effort. However, if you absolutely need to display a control title in the font currently associated with the window's graphics port, you can add the popupUseWFont constant to the pop-up menu control definition ID or add the useWFont constant to the other standard control definition IDs.

SEE ALSO
For information about windows' control lists, see the chapter "Window Manager" in
this book. Control definition IDs for other controls are discussed in "Defining Your Own Control Definition Function" beginning on page 5-102.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.