MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
© 2001 K. J. Bricknell

CHAPTER 14

MORE ON CONTROLS

Introduction

Chapter 7 - Introduction to Controls introduced the subject of controls and addressed the basic controls (push buttons, checkboxes, radio buttons, scroll bars, and pop-up menu buttons), primary group boxes (text title variant) and user panes. This chapter revisits group boxes and user panes and addresses the many remaining controls.

The controls addressed in this chapter are as follows:

The data browser control is not addressed in this book. The one remaining control (the list box) is addressed at Chapter 22.

The progress bar will be described in this chapter and the indeterminate variant demonstrated in the associated demonstration program. However, because the use of the determinate variant is ordinarily associated with the matter of scanning for a Command-period event, the demonstration of that particular variant has been held over to the demonstration program associated with Chapter 25.

Preamble - Review of Control Basics

Recall from Chapter 7 that:

• Control definition functions (CDEFs) determine the appearance and behaviour of controls.

• Two new features introduced with Mac OS 8 were embedding and latency. Embedding hierarchies have implications for drawing order and hit testing.

• Another feature introduced with Mac OS 8 was read and write access to the various attributes of a control. Each piece of information that a particular CDEF allows access to is referenced by a control data tag. Control data tag constants are passed in the inTagName parameter of the getter and setter functions SetControlData and GetControlData.

• FindControl is used to determine whether a mouse-down event occurred in a control and, if so, which control. FindControl returns a control part code identifying the part of the control in which the mouse-down occurred. kControlNoPart (0) is returned if the mouse-down occurred where no enabled control exists. TrackControl or HandleControlClick are used to handle user interaction with a control as long as the user holds the mouse button down. These two functions return kControlNoPart if the cursor is outside the control or control part when the mouse button is released or the relevant control part code if the user releases the mouse button while the cursor is still inside the control or control part.

• The font for any control can be set independently of the system or window font.

• The pop-up menu button differs from the other basic controls in that the control's initial, minimum, and maximum values do not actually represent initial, minimum and maximum values as such. For example, the minimum value field of the 'CNTL' resource for a pop-up button is used to specify the resource ID of the 'MENU' resource utilised by the control.

The use of the initial, minimum, and maximum fields for purposes other than control values as such also applies to most of the controls addressed in this chapter.

More on Embedding

As stated at Chapter 8, if the kDialogFlagsUseControlHierarchy feature bit is set in a dialog's 'dlgx' resource, the Dialog Manager creates a root control in the dialog box and establishes an embedding hierarchy.

The Dialog Manager uses AutoEmbedControl to position dialog items in an embedding hierarchy based on both visual containment and the order of the items in the item list. As items are added to a dialog box during creation, controls that already exist in the window will be containers for new controls if they both visually contain the control and are themselves embedder controls. For this reason, you should place the largest embedder controls at the beginning of the item list. As an example, the Dialog Manager will automatically embed radio buttons in a group box if, firstly, the radio buttons visually "fit" inside the group box and, secondly, the group box precedes the radio buttons in the item list.

Control Descriptions

Bevel Buttons

A bevel button is a rectangular control with a bevelled edge that can include text, an icon, a picture, or a combination of text and an icon or picture. Bevel buttons can be made to behave in a number of different ways: they can behave like push buttons; in sets, they can behave like radio buttons or checkboxes; if a menu is attached, they behave like pop-up menu buttons. Typical bevel buttons are shown at Fig 1.

Note that, on Mac OS X, bevel button have square corners by default but can be made rounded using the function SetControlData with the kControlBevelButtonKindTag tag (see Other Control Data Tag Constants, below).

Note also that, while three bevel sizes are available on Mac OS 8/9, only one bevel size is available on Mac OS X.

Variants and Control Definition IDs

The bevel button CDEF resource ID is 2. The six available variants and their control definition IDs are as follows:

Note that, while three bevel sizes are available on Mac OS 8/9, bevel button will always be displayed with one bevel size on Mac OS X regardless of which of the first three variants is used.

For bevel buttons containing text, if the constant kControlUsesOwningWindowsFontVariant is added to the variation code, the text will appear in the window's font.

Control Values

The following lists the initial, minimum, and maximum value settings for bevel buttons:

Note that bevel buttons have two values: the value of the bevel button and, if a menu has been attached, the value of the menu.

Bevel Button Behaviour Constants

The following bevel button behaviour constants apply to the high byte of a bevel button's minimum value:

Bevel Button Behaviour Constants (Menus)

The following bevel button behaviour constants (menus) apply to the high byte of a bevel button's minimum value:

Button and Image Well Content Type Constants

The following button and image well content type constants apply to the low byte of a bevel button's minimum value:

You can also use these constants in the contentType field of the bevel button and image well content structure (see below). You can then pass a pointer to this structure in the inBuffer parameter of GetControlData and SetControlData to get and set the resource ID (for resource-based content), handle (for handle-based content), or reference (for reference-based content) of a colour icon, icon suite, picture, or icon reference in a bevel button.

Note that resource-based content is owned by the control, while handle-based content is owned by you. The control definition function will not dispose of handle-based content. If you replace handle-based content with resource-based content on the ßy, you must dispose of the handle properly to avoid a memory leak.

Control Data Tag Constant - Content Type

The control data tag constant relevant to content type in bevel buttons is as follows:

Bevel Button Alignment and Placement Constants, and Associated Control Data Tag Constants

By calling SetControlData with certain control data tag constants, and with certain constants passed in the inData parameter, you can specify the alignment of icons, pictures, and text in a bevel button, and you can specify the placement of text in relation to an icon or picture. By calling GetControlData with these constants you can also ascertain alignment and placement.

Bevel Button Graphic Alignment Constants

The following constants are used to specify the alignment of icon suites, colour icons, and pictures:

Bevel Button Text Alignment Constants

The following constants are used to specify the alignment of text:

Bevel Button Text Placement Constants

The following constants are used to specify the placement of text in relation to an icon suite, colour icon, or picture:

Control Data Tag Constants - Alignment and Placement

The control data tag constants relevant to the alignment and placement of graphics and text in bevel buttons are as follows:

The Button Content Info Structure

As previously stated, you can use bevel button and image well content type constants in the contentType field of the button content info structure and you can then pass a pointer to this structure in the inBuffer parameter of GetControlData and SetControlData. The button content info structure is as follows:

     struct ControlButtonContentInfo 
     {
       ControlContentType  contentType;
       union {
         SInt16      resID;
         CIconHandle cIconHandle;
         Handle      iconSuite;
         IconRef     iconRef;
         PicHandle   picture;
         Handle      ICONHandle;
       } u;
     };
     typedef struct ControlButtonContentInfo ControlButtonContentInfo;
     typedef ControlButtonContentInfo *ControlButtonContentInfoPtr;
     typedef ControlButtonContentInfo ControlImageContentInfo;
     typedef ControlButtonContentInfo *ControlImageContentInfoPtr;

Field Descriptions

contentType	Specifies the content type (see Bevel Button and Image Well Content Type Constants, above.) and determines which of the following fields are used.
resID	If the content type specified in the contentType field is kControlContentIconSuiteRes, kControlContentCIconRes, or kControlContentPictRes, this field should contain the resource ID of a picture, colour icon, or icon suite resource.
cIconHandle	If the content type specified in the contentType field is kControlContentCIconHandle, this field should contain a handle to a colour icon.
iconSuite	If the content type specified in the contentType field is kControlContentIconSuiteHandle, this field should contain a handle to an icon suite.
iconRef	If the content type specified in the contentType field is kControlContentIconRef, this field should contain an icon reference.
picture	If the content type specified in the contentType field is kControlContentPictHandle, this field should contain a handle to a picture.

Other Control Data Tag Constants

The remaining control data tag constants relevant to bevel buttons are as follows:

With regard to the kControlBevelButtonMenuDelayTag constant, setting a delay before the menu is displayed in a bevel button with sticky behaviour is useful for providing option sets in tool palettes. You can set up the bevel button so that:

• If the user clicks it once, it simply turns on the function represented by the button.

• If the user presses it for longer than the user-set double-click time, it displays a pop-up menu which offers further options for that function.

Helper Functions

The following helper functions may be used in lieu of SetControlData and GetControlData with the relevant control data tags:

     GetBevelButtonMenuValue
     SetBevelButtonMenuValue
     GetBevelButtonMenuHandle
     GetBevelButtonContentInfo
     SetBevelButtonContentInfo
     SetBevelButtonTransform
     SetBevelButtonGraphicAlignment
     SetBevelButtonTextAlignment
     SetBevelButtonTextPlacement

Control Part Codes

Bevel Button States

Bevel buttons can exist in five active states and two disabled states. The active states are off, pressed (was off), on, pressed (was on), and mixed. The mixed state is used, where appropriate, when the bevel button is behaving as a checkbox or radio button. Disabled bevel buttons can be shown as off or on.

Programmatic Creation

Bevel button controls may be created programmatically using the function CreateBevelButtonControl:

     OSStatus CreateBevelButtonControl(WindowRef window,const Rect *boundsRect,
                                       CFStringRef title,ControlBevelThickness thickness,
                                       ControlBevelButtonBehavior behavior,
                                       ControlButtonContentInfoPtr info,SInt16 menuID,
                                       ControlBevelButtonMenuBehavior menuBehavior,
                                       ControlBevelButtonMenuPlacement menuPlacement,
                                       ControlRef *outControl);

Relevant constants are:

Image Wells

Image wells can be used to display icons or pictures. They are controlled in much the same way as bevel buttons, but with fewer options and states. They should not be used in place of push buttons or bevel buttons. Typical image wells are shown at Fig 2.

Variants and Control Definition IDs

The image well CDEF resource ID is 11. The one available variant and its control definition IDs is as follows:

Control Values

Bevel Button and Image Well Content Type Constants and The Button Content Info Structure

The bevel button and image well content type constants (see Bevel Buttons, above) apply to an image well's minimum value.

You can also use these constants in the contentType field of the button content info structure (see Bevel Buttons, above). You can then pass a pointer to this structure in the inBuffer parameter of GetControlData and SetControlData to get and set the resource ID (for resource-based content) or handle (for handle-based content) of a colour icon, icon suite, or picture in an image well.

Helper Functions

The following helper functions may be used in lieu of SetControlData and GetControlData with the relevant control data tag constants:

     GetImageWellContentInfo
     SetImageWellContentInfo
     SetImageWellTransform

Control Part Codes

Programmatic Creation

Image well controls may be created programmatically using the function CreateImageWellControl: OSStatus CreateImageWellControl(WindowRef window,const Rect *boundsRect, const ControlButtonContentInfo *info, ControlRef *outControl);

Relevant constants are:

Tab Control (Embedding Control)

The tab control is an embedding control which provides a means of presenting information on multiple "pages". The user selects the desired "page" by clicking the appropriate tab.

A typical tab control is shown at Fig 3.

The content area of a tab is known as a pane. Controls which are embedded within an individual pane should only affect the settings displayed in that pane. Controls whose effect is intended to be global (that is, their setting are intended to affect all the panes in a set of tabs) should be located outside the tab control.

The tab information ('tab#') resource may be used to provide the tab names and icon suite IDs.

Variants and Control Definition IDs

The tab control CDEF resource ID is 8. The eight available variants and their control definition ID are follows:

Control Values

Control Data Tag Constants

Helper Functions

The following helper functions may be used in lieu of SetControlData and GetControlData with the relevant control data tags:

     GetTabContentRect
     SetTabEnabled

The Tab Information Structure

If you are not creating a tab control with a 'tab#' resource, you can call SetControlMaximum to set the number of tabs in a tab control and then call SetControlData with the kControlTabInfoTag to set the information for an individual tab in a tab control. The tab information structure passed in the SetControlData call should be one of the following:

     struct ControlTabInfoRec
    {
      SInt16 version;      // Set to 0.
      SInt16 iconSuiteID;  // Set to 0 for no icon.
      Str255 name;         // Title for tab label.
    };
    typedef struct ControlTabInfoRec ControlTabInfoRec;

    struct ControlTabInfoRecV1 
    {
      SInt16      version;     // Set to kControlTabInfoVersionOne.
      SInt16      iconSuiteID; // Set to 0 for no icon.
      CFStringRef name;        // Title for tab label.  (Should always be released)
    };
    typedef struct ControlTabInfoRecV1 ControlTabInfoRecV1;

An alternative tab information structure takes a CFString object in the name parameter:

     struct ControlTabInfoRecV1
     {
       SInt16      version;
       SInt16      iconSuiteID;
       CFstringRef name;
     };
     typedef struct ControlTabInfoRecV1 ControlTabInfoRecV1;

If this variant is used, kControlTabInfoVersionOne should be assigned to the version field.

The Tab Information Resource

You can use a tab information resource to specify the icon suite ID and name of each tab in a tab control. A tab information resource is a resource of type 'tab#'. All tab information resources must have resource ID numbers greater than 127. The Control Manager uses the information you specify to provide additional information to the corresponding tab control. Fig 4 shows the structure of a compiled 'tab#' resource.

The following describes the fields of a compiled 'tab#' resource and one of its tab information entries:

Programmatic Creation

Tab controls may be created programmatically using the function CreateTabsControl:

     OSStatus  CreateTabsControl(WindowRef window,const Rect *boundsRect,ControlTabSize size,
                                 ControlTabDirection direction,UInt16 numTabs,
                                 const ControlTabEntry *tabArray,
                                 ControlRef *outControl);

Relevant constants are:

The tabArray parameter of takes a pointer to an array of tab entry structures:

     struct ControlTabEntry 
     {
       ControlButtonContentInfo *icon;
       CFStringRef               name;
       Boolean                   enabled;
     };
     typedef struct ControlTabEntry ControlTabEntry;

Edit Text

Edit text controls are rectangular areas in which the user enters text. Edit text controls supports keyboard focus, and a password entry variant is available. Fig 5 shows a typical edit text control.

Edit text controls can have an application-defined key filter function attached to filter key strokes or modify them on return.

Variants and Control Definition IDs

The edit text control CDEF resource ID is 17. The three available variants and their control definition IDs are as follows:

Control Values

Control Data Tag Constants

Control Part Codes

The Edit Text Selection Structure

You can pass a pointer to the edit text selection structure to GetControlData and SetControlData to access and set the current selection range in an edit text control. An edit text selection structure is of type ControlEditTextSelectionRec:

     struct ControlEditTextSelectionRec 
     {
       SInt16  selStart;
       SInt16  selEnd;
     };
     typedef struct ControlEditTextSelectionRec ControlEditTextSelectionRec;
     typedef ControlEditTextSelectionRec *ControlEditTextSelectionPtr;

Field Descriptions

selStart	Beginning of the edit text selection.
selEnd	End of the edit text selection.

Programmatic Creation

Edit text controls may be created programmatically using the function CreateEditTextControl:

     OSStatus  CreateEditTextControl(WindowRef window,const Rect *boundsRect,CFStringRef text,
                                     Boolean isPassword,Boolean useInlineInput,
                                     const ControlFontStyleRec *style,ControlRef *outControl);

Sliders

A slider control consists of a slider bar and an indicator. The user can drag the indicator to set a new value within the range represented by the slider bar.

Sliders can be oriented horizontally or vertically, and the indicator can point in any direction. The indicator can also be nondirectional if required. Typical sliders are shown at Fig 6.

A slider can, optionally, display tick marks, and you can specify the number of tick marks required. If you specify tick marks, you should ensure that they are labelled.

A live feedback variant is available. This variant continually updates the value of the control as the indicator is dragged, as opposed to the standard behaviour of updating the value only when the mouse button is released.

Variants and Control Definition IDs

The slider CDEF resource ID is 3. The ten available variants and their control definition IDs are as follows:

Control Values

Control Part Codes

Programmatic Creation

Slider controls may be created programmatically using the function CreateSliderControl:

     OSStatus  CreateSliderControl(WindowRef window,const Rect *boundsRect,SInt32 value,
                                   SInt32 minimum,SInt32 maximum,
                                   ControlSliderOrientation orientation,UInt16 numTickMarks,
                                   Boolean liveTracking,ControlActionUPP liveTrackingProc,
                                   ControlRef *outControl);

Relevant constants are:

Group Boxes (Embedding Control)

Group boxes are embedding controls used to group a number of related items. They may be either primary or secondary.

A group box can be untitled or it can have a text title, a pop-up menu title, or a checkbox title. Group boxes with a pop-up menu title are useful for displaying a variety of related settings in a limited space. Group boxes with a checkbox title are useful for indicating that a group of settings may be deactivated by the user.

Secondary group boxes are generally used for grouping subsidiary information.

Typical group boxes are shown at Fig 7.

Variants and Control Definition IDs

The group box CDEF resource ID is 10. The six available variants and their control definition IDs are as follows:

Control Values

Control Data Tag Constant

Control Part Codes

Programmatic Creation

Group box controls may be created programmatically using the functions CreateGroupBoxControl, CreateCheckGroupBoxControl, and CreatePopupGroupBoxControl:

     OSStatus  CreateGroupBoxControl(WindowRef window,const Rect *boundsRect,
                                     CFStringRef title,Boolean primary,
                                     ControlRef *outControl);

     OSStatus  CreateCheckGroupBoxControl(WindowRef window,const Rect *boundsRect,
                                          CFStringRef title,SInt32 initialValue,
                                          Boolean primary,Boolean autoToggle,
                                          ControlRef *outControl);

     OSStatus  CreatePopupGroupBoxControl(WindowRef window,const Rect *boundsRect,
                                          CFStringRef title,Boolean primary,SInt16 menuID,
                                          Boolean variableWidth,SInt16 titleWidth,
                                          SInt16 titleJustification,Style titleStyle,
                                          ControlRef *outControl);

Clock

Clock controls are a combination of an edit text control and little arrows (see below) which display date or time. The displayed date and time may be changed using the little arrows or by typing in the edit text control. Fig 8 shows a clock control displaying a date.

The clock control supports keyboard navigation and keyboard focus. If the control is made inactive, the user will be unable to change the displayed date or time values; however the correct date and time will continue to be displayed.

Variants and Control Definition IDs

The clock control CDEF resource ID is 15. The four available variants and their control definition ID are follows:

Control Values

Clock Value Flag Constants

Control Data Tag Constant

Control Part Codes

Programmatic Creation

Clock controls may be created programmatically using the function CreateClockControl:

     OSStatus  CreateClockControl(WindowRef window,const Rect *boundsRect,
                                  ControlClockType clockType,ControlClockFlags clockFlags,
                                  ControlRef *outControl);

Relevant constants are:

Progress and Relevance Bars

Progress bars are used to indicate capacity or the current status of a lengthy operation. Two types of progress bars can be used: an indeterminate progress bar, which shows that an operation is occurring