You can use the Control Manager to create and manage controls. An alternative method is to use the Dialog Manager to more easily create and manage controls in dialog boxes and alert boxes. In this latter case, the Dialog Manager works with the Control Manager behind the scenes. The creation and handling of controls in dialog boxes and alert boxes will be addressed at Chapter 8 - Dialogs and Alerts and in the demonstration program associated with Chapter 14 - More on Controls. The creation and handling areas of this chapter are limited to the use of the Control Manager to create and handle controls in document windows.

Every control you create must be associated with a particular window. All the controls for a window are stored in a control list, a handle to which is stored in the controlList field of the window's window structure.

Standard Controls

Available Appearance-Compliant Standard Controls

Definition of the Term "Controls"

Part of the answer to that question has to do with the matter of Appearance-compliance. For example, using the provided separator line "control" to draw separator lines will ensure that those lines are drawn with the correct appearance, in both the activated and deactivated modes, regardless of which Appearance theme has been chosen by the user.

Another part of the answer has to do with the concept of embedding (see below). The window header control, for example, is not just the visual entity it might at first appear to be; it is actually a control in which other controls may be embedded. (As will be seen, the ability to embed other controls is a powerful new feature of some of the new controls.)

Since many of the new controls are not really controls "which the user can manipulate", a more accurate blanket definition might now be "any element of the user interface that is implemented by a control definition function" (see below).

Controls Addressed in This Chapter

The Control Definition Function

Just as a window definition function can describe variations of the same basic window, a CDEF can use a variation code to describe variations of the same control. You specify a particular control with a control definition ID, which is an integer containing the resource ID of the in the upper 12 bits and the variation code in the lower four bits.

The control definition ID is arrived at by multiplying the resource ID by 16 and adding the variation code. The following shows the control definition IDs for the standard controls and variants addressed in this chapter and its associated demonstration programs, together with the derivation of those IDs. (Those variants introduced with Mac OS 8.5 are shown in dark blue.)

Note that the one CDEF caters for both horizontal and vertical scroll bars. The CDEF determines whether a scroll bar is vertical or horizontal from the rectangle you specify when you create the control.

The Basic Controls, Primary Group Boxes (Text Title Variant), and User Panes

SetControlValue may also be used to place a dash in the box to indicate that the control is in the mixed state (see Fig 1). The mixed state is a special state which indicates that a selected range of items has some in the on state and some in the off state. For example, a text formatting checkbox for bold text would be in the mixed state if a text selection contained both bold and non-bold text.

Auto-Toggling Variant

Radio Buttons

A group of radio buttons must comprise at least two radio buttons. Each group must have a label which identifies the kind of choices the group offers and each button must have a title identifying what the radio button does. If you need to display more than seven items, or if the items change as the context changes, you should use a pop-up menu button instead.

Non-Auto-Toggling Variant

• Set that control to the on state and place a black dot in its circle (see Fig 1).

• Set the previously "on" button in the group to the off state and remove the black dot from its circle.

Auto-Toggling Variant

Scroll Bars

As previously stated, the CDEF for scroll bars supports two variants. The only difference between the two variants is that one supports live feedback and the other does not. In the case of scroll bars, live feedback (a generic term) may be used to perform live scrolling of a document in a window. Live scrolling means that, when the user attempts to drag the scroll box, the scroll box moves and the document scrolls as the user moves the mouse. (Without live scrolling, only a ghosted image of the scroll box moves. In addition, the document is only scrolled, and the scroll box proper is only redrawn at its new location, when the user releases the mouse button.)

Scroll Arrows and Gray Area

When the gray area is clicked above the scroll box, your application should move the document up so that the bottom line of the previous view is at the top of the new view, and it should move the scroll box accordingly. A similar, but downward movement, should occur when the user clicks in the gray area below the scroll box.

Scroll Box

Live Feedback Variant Used. When the live feedback variant is being used, and when the user drags the scroll box, the Control Manager continually redraws the scroll box, and continually returns the control's position (that is, its value) as the scroll box moves. Once again, your application uses this value to display the appropriate portion of the document.

Proportional Scroll Boxes

Under Mac OS 8.5 and later, if the user selects Smart Scrolling on in the Options tab in the Appearance control panel, your application's scroll boxes will appear as proportional scroll boxes provided that you pass the size of the view area, in whatever units the scroll bar uses, to the function SetControlViewSize. The system automatically handles resizing the scroll box once your application supplies this information.

The following functions, introduced with Mac OS 8.5, are relevant to proportional scroll boxes:

Pop-Up Menu Buttons

The primary group box is an embedder control (see below), meaning that you can embed other controls, such as radio buttons, checkboxes, and pop-up menu buttons, within it.

User Panes

• Like the primary group box, it can be used as an embedder control, that is, other controls may be embedded within it.

• It provides a way to hook in application-defined functions, known as user pane functions, which perform actions such as drawing, hit testing, etc.

Activating and Deactivating Controls Other Than Scroll Bars

• They are not relevant to the current context.

• The window in which they reside is not the active window.

Activating and Deactivating Scroll Bars

ShowControl may be used to show a control. ShowControl makes the control visible and immediately draws the control within its window without using your window's standard updating mechanism.

SetControlVisibility may be used to both hide and show a control. With regard to showing a control, this function differs from ShowControl in that the option is available to "show" the control without redrawing it immediately.

Your application can ascertain whether a control is currently hidden or visible using IsControlVisible.

Visual Feedback From the Basic Controls

• Displaying push buttons, checkboxes and radio buttons in their pressed mode.

• Displaying and highlighting the items in pop-up menu buttons.

• Highlighting the scroll arrows in scroll bars.

• Moving the scroll box (live feedback variant of the scroll bar CDEF being used) or moving a ghosted image of the scroll box (live feedback variant not being used) when the user drags it.

Embedding Controls

Once you have created a root control, new controls will be automatically embedded in the root control when they are created. One advantage of such embedding is that, when you wish to activate and deactivate all of the window's controls on window activation and deactivation, you can do so by simply activating and deactivating the root control. (If the root control did not exist, you would have to activate and deactivate all of the window's controls individually.) You can also hide and show all of the window's control by simply hiding and showing the root control.

Other Embedders

EmbedControl may be used to embed a control in another (embedder) control. However, where the control to be embedded is visually contained by the embedder, as is the case with the radio buttons in Fig 3, AutoEmbedControl would be more appropriate.

Other Advantages of Embedding

In the example at Fig 3, assume that there is no embedding hierarchy and that the radio buttons are created after the group box. This means that the group box will be drawn after the radio buttons, thus obscuring the radio buttons. An embedding hierarchy, however, enforces drawing order by drawing the embedding control before its embedded controls regardless of which is created first.

Hit Testing

For example, assume that the radio button labelled White at Fig 3 has been separately deactivated by the application. When the primary group box is deactivated, the two remaining radio buttons will also be deactivated. When the primary group box is again enabled, the Control Manager remembers that the radio button labelled white was previously deactivated, and ensures that it remains in that mode.

Getting and Setting Control Data

Each piece of information that a particular CDEF allows access to is referenced by a tag, which is a constant that is meaningful to the CDEF and which represents the data in question. Each tagged piece of data can be of any data type, such as a menu handle or a structure.

Control data tag constants are passed in the third parameter of the getter and setter functions SetControlData and GetControlData. The control data tag constants relevant to the basic controls are as follows:

The Control Structure

     struct ControlRecord 
     {
       ControlHandle     nextControl;   // Next Control.
       WindowPtr         contrlOwner;   // Control's window.
       Rect              contrlRect;    // Rectangle.
       UInt8             contrlVis;     // 255 if visible, else 0.
       UInt8             contrlHilite;  // Highlight state.
       SInt16            contrlValue;   // Current setting.
       SInt16            contrlMin;     // Minimum Setting.
       SInt16            contrlMax;     // Maximum setting.
       Handle            contrlDefProc; // Control definition function.
       Handle            contrlData;    // Data used by contrlDefProc.
       ControlActionUPP  contrlAction;  // Action function.
       SInt32            contrlRfCon;   // Reference constant.
       Str255            contrlTitle;   // Title.
     };
     typedef struct ControlRecord ControlRecord;
     typedef ControlRecord *ControlPtr;
     typedef ControlPtr *ControlHandle;

The following describes the main fields of the 'CNTL' resource:

Values For Controls

Note that the title of each of the three value fields is somewhat of a misnomer in the case of the pop-up menu button.

Creating 'CNTL' Resources Using Resorcerer

Creating Controls

If the 'CNTL' resource specifies that a control is initially visible, the Control Manager uses the CDEF to draw the control. (The Control Manager draws the control immediately and does not wait for the window updating mechanism.) If the 'CNTL' resource specifies that the control is to be initially invisible, ShowControl may be used to draw the control when required.

Note that when you use the Dialog Manager to implement push buttons, radio buttons, checkboxes or pop-up menu buttons in alert boxes or dialog boxes, Dialog Manager functions automatically use Control Manager functions to create the controls for you.

Creating Scroll Bars

After you create the window, use GetNewControl to create the scroll bar. Then use MoveControl, SizeControl, SetControlMaximum and SetControlValue to adjust the size, location and value settings. (For example, for a window displaying a text document, you would typically calculate the number of lines of text and set the vertical scroll bar's maximum value according to the line count and the window's current height. You would set the control's value according to the part of the document to be initially displayed.) Finally, use ShowControl to display the control bar.

Most applications allow the user to change the size of windows, add information to the document and remove information from the document. It is therefore necessary, in your window handling code, to calculate a changing maximum setting based on the document's current size and its window's current size. For new documents which have no content to scroll, assign an initial value of 0 as the maximum setting (which will, as previously stated, make the scroll bars inactive). Thereafter, your window-handling code should set and maintain the maximum setting.

By convention, a scroll bar for a document window is 16 pixels wide; accordingly, there should be a sixteen-pixel difference between the left and right coordinates of a vertical scroll bar's rectangle and between the top and bottom coordinates of a horizontal scroll bar. (If you do not specify a 16-pixel width, the Control Manager scales the scroll bar to fit the width you specify.) A standard scroll bar for a document window should be at least 48 pixels long to allow room for the scroll arrows and scroll box.

The Control Manager draws one-pixel lines for the rectangle enclosing the scroll bar. As shown at Fig 6, the outside lines of the scroll bar should overlap the inside lines of the window frame.

The following calculations determine the rectangle for a vertical scroll bar for a document window:

Do not include the title bar area in these calculations.

The following calculations determine the rectangle for a horizontal scroll bar for a document window.

The top coordinate of a vertical scroll bar and the left coordinate of a horizontal scroll bar is -1 unless your application uses part of the window's typical scroll bar area for displaying information or specifying additional controls.

Just as the maximum settings change when the user resizes a document's window, so too do the scroll bar's coordinate locations change when the user resizes the window. The initial maximum settings and location, as specified in the 'CNTL' resource, must therefore be changed dynamically by the application as required. Typically, this is achieved by storing handles to each scroll bar in an application-defined document structure associated with the window and then using Control Manager functions to change control settings.

Scroll Bars in Utility Windows. You can also use scroll bars in utility windows (see Fig 7). Size boxes in utility windows are 11-by-11 pixels, and the standard Appearance-compliant scroll bar can be made to fit into this space.

Pop-up Menu Buttons

Pop-up Menu Button Title Width

Menu Width Adjustment

To set the font of a control's title, you pass a pointer to a control font style structure in the inStyle parameter of the function SetControlFontStyle.

Control Font Style Structure

     struct ControlFontStyleRec 
     {
       SInt16    flags;
       SInt16    font;
       SInt16    size;
       SInt16    style;
       SInt16    mode;
       SInt16    just;
       RGBColor  foreColor;
       RGBColor  backColor;
     };
     typedef struct ControlFontStyleRec ControlFontStyleRec;
     typedef ControlFontStyleRec *ControlFontStylePtr;

Control Font Style Flag Constants

Meta Font Constants

Another advantage of using these meta font constants is that you can be sure of getting the correct font on a Macintosh using a different script system, such as kanji.

Updating, Moving, and Removing Controls

Note that when you use the Dialog Man