Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 5 - Control Manager / Control Manager Reference

Data Structures

The Control Record

When you create a control, the Control Manager incorporates the information you specify (either in the control resource or in the parameters of the NewControl function) into a control record, which is a data structure of type ControlRecord. The Control Manager functions you use for creating a control, GetNewControl and NewControl, return a handle to a newly allocated control record. Thereafter, your application normally refers to the control by this handle, because most other Control Manager routines expect a control handle as their first parameter.

You can use Control Manager routines to determine and change several of the values in the control record, or you can access and change its fields yourself.

TYPE ControlRecord =
PACKED RECORD
   nextControl:   ControlHandle; {next control}
   contrlOwner:   WindowPtr;     {control's window}
   contrlRect:    Rect;          {rectangle}
   contrlVis:     Byte;          {255 if visible}
   contrlHilite:  Byte;          {highlight state}
   contrlValue:   Integer;       {control's current setting}
   contrlMin:     Integer;       {control's minimum setting}
   contrlMax:     Integer;       {control's maximum setting}
   contrlDefProc: Handle;        {control definition function}
   contrlData:    Handle;        {data used by contrlDefProc}
   contrlAction:  ProcPtr;       {action procedure}
   contrlRfCon:   LongInt;       {control's reference value}
   contrlTitle:   Str255;        {control's title}
END;

Field Description

nextControl

A handle to the next control associated with this control's window. All the controls belonging to a given window are kept in a linked list, beginning in the controlList field of the window record and chained together through the nextControl fields of the individual control records. The end of the list is marked by a NIL value; as new controls are created, they're added to the beginning of the list.

contrlOwner

A pointer to the window to which this control belongs.

contrlRect

The rectangle that completely encloses the control, in the local coordinates of the control's window. You can use the MoveControl and SizeControl procedures to change the rectangle stored in this field.

contrlVis

The invisible/visible state for the control. When the value of this field is 0, the Control Manager does not draw the control (its state is invisible); when the value of this field is 255, the Control Manager draws the control (its state is visible). Note that even when a control is visible, it might still be obscured from sight by an overlapping window or some other object. You can use the HideControl procedure to change this field from visible to invisible, and you can use the ShowControl procedure to change this field from invisible to visible.

contrlHilite

Specifies whether and how the control is to be displayed, indicating whether it's active or inactive and, if active, whether it's selected. The value of 0 signifies an active control that is not selected. A value from 1 through 253 signifies a part code designating the part of
the (active) control to highlight, indicating that the user is pressing the mouse button while the cursor is in that part. The value
255 signifies that the control is to be made inactive and drawn accordingly. The HiliteControl procedure lets you change the value of this field.

contrlValue

The control's current setting. For buttons, checkboxes, and radio buttons, 0 means the control is off and 1 means it's on. For scroll bars and other sliders, contrlValue may take any value within the range specified in the contrlMin and contrlMax fields. For pop-up menus, this value is the item number of the menu item chosen by the user; if the user hasn't chosen a menu item, it is the item number of the first menu item. For other controls, you can use this field as you wish. You can use the GetControlValue function to determine the value of this field, and you can use the SetControlValue procedure to change the value of this field.

contrlMin

The control's minimum possible setting. For on-and-off controls--like checkboxes and radio buttons--this value should be 0 (meaning that the control is off). For scroll bars and other sliders, this can be any appropriate minimum value. For controls--like buttons--
that don't retain a setting, this value should be 0. For pop-up menus, the Control Manager sets this field to 1. For other
controls, you can use this field as you wish. You can use the GetControlMinimum function to determine the value of this field, and you can use the SetControlMinimum procedure to change the value of this field.

contrlMax

The control's maximum possible setting. For on-and-off controls like checkboxes and radio buttons, this value should be 1 (meaning that the control is on). For scroll bars and other sliders, this can be any appropriate maximum value. 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. For controls--like buttons--that don't retain a setting, this value should be 1. For pop-up menus, the Control Manager sets this value to the number of items in the menu. For other controls, you can use this field as you wish. You can use the GetControlMaximum function to determine the value of this field, and you can use the SetControlMaximum procedure to change the value of this field.

contrlDefProc

A handle to the control definition function for this type of
control. When you create a control, you identify its type with
a control definition ID, which is converted into a handle to the control definition function and stored in this field. Thereafter,
the Control Manager uses this handle to access the definition function; you should never need to refer to this field directly.

Note

In systems running in 24-bit mode, the high-order byte of the contrlDefProc field contains the variant, which the Control Manager gets from the control definition ID.

contrlData

Reserved for use by the control definition function, typically to hold additional information specific to a particular control type. For example, the control definition function for scroll bars uses this field for a handle to the region containing the scroll box. (If no more than 4 bytes of additional information are needed, the definition function may store the information directly in the contrlData field rather than using a handle.) The control definition function for pop-up menus uses this field to store a pop-up private data record, which is described on page 5-70.

contrlAction

A pointer to the control's action procedure, if any. The TrackControl function may call this procedure to respond to
the user's dragging of the control, and this procedure responds
by repeatedly performing some action as long as the user holds down the mouse button. See the description of TrackControl
on page 5-84 for more information about the action procedure.
You can use the GetControlAction function to determine the current value of this field and the SetControlAction procedure to change it.

contrlRfCon

The control's reference value, which your application may use
for any purpose. You can use the GetControlReference
function to determine the current value of this field and the SetControlReference procedure to change it.

contrlTitle

The control title, if any. You can use the GetControlTitle procedure to determine the current value of this field and the SetControlTitle procedure to change it.