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

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

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 but does not indicate its current status; a determinate progress bar, which shows how much of the operation has been completed. The two types are shown at Fig 9.

On Mac OS 8/9, the progress bar control is often used as a relevance bar. On Mac OS X, a separate relevance bar control, which can only be created programmatically, is available.

Variants and Control Definition IDs

The progress bar CDEF resource ID is 5. The two available variants and their control definition IDs are follows:

Progress Bar Control Values

Control Data Tag Constant

Programmatic Creation

Progress bars may be created programmatically using the function CreateProgessBarControl:

OSStatus  CreateProgressBarControl(WindowRef window,const Rect *boundsRect,SInt32 value,
                                   SInt32 minimum,SInt32 maximum,Boolean indeterminate,
                                   ControlRef *outControl);

On Mac OS X only, relevance bars may be created programmatically using the function CreateRelevanceBarControl:

OSStatus  CreateRelevanceBarControl(WindowRef window,const Rect *boundsRect,SInt32 value,
                                    SInt32 minimum,SInt32 maximum,
                                    ControlRef *outControl);

Little Arrows

The little arrows control (see Fig 10), which consists of two opposing arrows, provide a means of increasing or decreasing values. They should always be accompanied by a label that identifies the content to which the control relates.

The displayed value is incremented or decremented by one unit of change when the user clicks the up or down arrow. If the user clicks an arrow and holds the mouse button down, the value increases or decreases until the user releases the button. The unit of change should depend on the content.

Variant and Control Definition ID

The little arrows CDEF resource ID is 6. The one available variant and its control definition ID is as follows:

Control Values

Control Part Codes

Programmatic Creation

Little arrows controls may be created programmatically using the function CreateLittleArrowsControl:

     OSStatus  CreateLittleArrowsControl(WindowRef window,const Rect *boundsRect,SInt32 value,
                                         SInt32 minimum,SInt32 maximum,SInt32 increment,
                                         ControlRef *outControl);

Disclosure Triangles

Disclosure triangles (see Fig 11) are used to display and hide additional information in a window and also to reveal the contents of folders in list views. They have two possible values: 0 for collapsed and 1 for expanded. The first click on the control rotates the triangle downwards. The second click rotates the triangle back to the original orientation.

Variants and Control Definition IDs

The disclosure triangle CDEF resource ID is 4. The four available variants and their control definition ID is as follows:

Control Values

Control Data Tag Constant

Helper Function

The helper function SetDisclosureTriangleLastValue may be used in lieu of SetControlData with the kControlTriangleLastValueTag control data tag.

Control Part Codes

Programmatic Creation

Disclosure triangle controls may be created programmatically using the functionCreateDisclosureTriangleControl:

     OSStatus  CreateDisclosureTriangleControl(WindowRef window,const Rect *boundsRect,
                                             ControlDisclosureTriangleOrientation orientation,
                                             CFStringRef title,SInt32 initialValue,
                                             Boolean drawTitle,Boolean autoToggles,
                                             ControlRef *outControl);

Relevant constants are:

Picture

Picture controls display pictures.

Variants and Control Definition IDs

The picture control CDEF resource ID is 19. The two available variants and their control definition IDs are as follows:

Control Values

Control Data Tag Constant

Control Part Codes

Programmatic Creation

Picture controls may be created programmatically using the function CreatePictureControl:

     OSStatus  CreatePictureControl(WindowRef window,const Rect *boundsRect,
                                    const ControlButtonContentInfo *content,Boolean dontTrack,
                                    ControlRef *outControl);

Icon

Icon controls display colour icons and icons from an icon suite.

A non-tracking variant is available for use in dialogs which have an embedding hierarchy and want an icon. This variant just returns the part hit immediately; it does not actually track the mouse.

Variants and Control Definition IDs

The icon CDEF resource ID is 20. The four available variants and their control definition IDs are as follows:

Control Values

Control Data Tag Constants

Control Part Codes

Programmatic Creation

Icon controls may be created programmatically using the function CreateIconControl:

     OSStatus  CreateIconControl(WindowRef window,const Rect *boundsRect,
                                 const ControlButtonContentInfo *icon,Boolean dontTrack,
                                 ControlRef *outControl);

Window Headers (Embedding Control)

Window headers are rectangular embedding controls which should be located at the top of a window's content region and used to provide information about the window's contents.

The list view header variant is similar to the main variant, but removes the line that separates a standard window header from the content area.

Variants and Control Definition IDs

The window header CDEF resource ID is 21. The two available variants and their control definition IDs are as follows:

Control Values

Programmatic Creation

Window header controls may be created programmatically using the function CreateWindowHeaderControl:

     OSStatus  CreateWindowHeaderControl(WindowRef window,const Rect *boundsRect,
                                         Boolean isListHeader,ControlRef *outControl);

Placard (Embedding Control)

Placards are rectangular embedding controls used to display information. They can also be used simply as background fill for a control area. Typically, placards are used as a small information panel placed at the bottom of a window.

Variants and Control Definition IDs

The placard CDEF resource ID is 14. The one available variant and its control definition ID is as follows:

Future versions will provide a push button variant.

Control Values

Programmatic Creation

Placard controls may be created programmatically using the function CreatePlacardControl.

Static Text

Static text controls display static text, that is, text that cannot be changed by the user.

Variant and Control Definition ID

The static text control CDEF resource ID is 18. The one available variant and its control definition ID is as follows:

Control Values

Control Data Tag Constants

Programmatic Creation

Static text controls may be created programmatically using the function CreateStaticTextControl:

     OSStatus  CreateStaticTextControl(WindowRef window,const Rect *boundsRect,
                                       CFStringRef text,const ControlFontStyleRec *style,
                                       ControlRef * outControl);

Separator Lines

Separator lines are vertical or horizontal lines used to visually separate groups of controls. The orientation of the bounding rectangle determines the orientation of the line.

Variants and Control Definition IDs

The separator line CDEF resource ID is 9. The one available variant and its control definition ID is as follows:

Control Values

Programmatic Creation

Separator line controls may be created programmatically using the function CreateSeparatorControl:

     OSStatus  CreateSeparatorControl(WindowRef window,const Rect *boundsRect,
                                      ControlRef *outControl);

Pop-up Arrows

The pop-up arrow control simply draws the pop-up glyph.

Variants and Control Definition IDs

The pop-up arrow CDEF resource ID is 12. The eight available variants and their control definition IDs are as follows:

Control Values

Programmatic Creation

Pop-up arrow controls may be created programmatically using the function CreatePopupArrowControl:

     OSStatus  CreatePopupArrowControl(WindowRef window,const Rect *boundsRect,
                                       ControlPopupArrowOrientation orientation,
                                       ControlPopupArrowSize size,ControlRef *outControl);

Relevant constants are:

Radio Groups (Embedding Control)

Radio groups are embedding controls which relieve your application of much of the work involved in managing a group of radio buttons (or bevel buttons which are intended to operate like radio buttons). For example, if a group of radio buttons are embedded in a radio group control, the radio group control handles the checking and unchecking of the radio buttons when the user clicks on one of them. The current value of the radio group control represents the radio button currently selected.

Variant and Control Definition ID

The radio group CDEF resource ID is 26. The one available variant and its control definition ID is as follows:

Control Values

Control Part Codes

Programmatic Creation

Radio group controls may be created programmatically using the function CreateRadioGroupControl:

     OSStatus  CreateRadioGroupControl(WindowRef window,const Rect *boundsRect,
                                       ControlRef *outControl);

Chasing arrows

Chasing arrows (see Fig 12) are a simple animation used to indicate that an asynchronous background process is occurring, in other words a process which does not display a dialog containing a progress bar.

Variant and Control Definition ID

The chasing arrows CDEF resource ID is 7. The one available variant and its control definition ID is as follows:

Control Values

Control Data Tag Constants

Programmatic Creation

Asynchronous arrow controls may be created programmatically using the function CreateChasingArrowsControl:

     OSStatus  CreateChasingArrowsControl(WindowRef window,const Rect *boundsRect,
                                          ControlRef *outControl);

User Panes (Embedding Control)

The user pane has two main uses:

• It can be used as an embedding control, that is, other controls may be embedded within it. It is thus particularly useful for grouping together the controls belonging to an individual pane of a tab control or pop-up button group box.

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

Variants and Control Definition IDs

The user pane CDEF resource ID is 16. The one available variant and its control definition ID is as follows:

Control Values

Control Data Tag Constants

The control data tag constants relevant to user panes all relate to user pane functions. See Defining Your Own User Pane Function, below.

Programmatic Creation

User Pane controls may be created programmatically using the function CreateUserPaneControl:

     OSStatus  CreateUserPaneControl(WindowRef window,const Rect *boundsRect,
                                     UInt32 features,ControlRef *outControl);

Scrolling Text Box (Embedding Control)

The scrolling text box implements a scrolling box of non-editable text. There are two variants:

• The standard variant, which has a scroll bar.

• The auto-scrolling variant, which does not have a scroll bar. This variant needs two pieces of information to work: the delay (in ticks) before the scrolling starts; the time (in ticks) between scrolls. By default, the text will scroll one pixel at a time, although this may be changed via SetControlData.

Variants and Control Definition IDs

The scrolling text box CDEF resource ID is 27. The two available variants and their control definition IDs are as follows:

Control Values

Programmatic Creation

Scrolling text box controls may be created programmatically using the function CreateScrollingTextBoxControl:

     OSStatus  CreateScrollingTextBoxControl(WindowRef window,const Rect *boundsRect,
                                             SInt16 contentResID,Boolean autoScroll,
                                             UInt32 delayBeforeAutoScroll,
                                             UInt32 delayBetweenAutoScroll,
                                             UInt16 autoScrollAmount,ControlRef *outControl);

Disclosure Button

The disclosure button (see Fig 13) is available only on Mac OS X, and can only be created programmatically using the function CreateDisclosureButtonControl:

     OSStatus  CreateDisclosureButtonControl(WindowRef inWindow,const Rect *inBoundsRect,
                                             SInt32 inValue,Boolean inAutoToggles,
                                             ControlRef *  outControl);

The height of the button is fixed, and the button will be centred in the specified rectangle. Relevant constants are:

Edit Unicode Text

The edit Unicode text control is available only on Mac OS X, and can only be created programmatically using the function CreateEditUnicodeTextControl:

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

The control data tags applicable to the edit text control also apply to the edit Unicode text control, except that the kControlEditTextTEHandleTag tag must not be used.

Round Button

The round button is available only on Mac OS X, and can only be created programmatically using the function CreateRoundButtonControl:

     OSStatus  CreateRoundButtonControl(WindowRef nWindow,const Rect *inBoundsRect,
                                        ControlRoundButtonSize inSize,
                                        ControlButtonContentInfo *inContent,
                                        ControlRef *outControl);

Relevant constants are:

Control Data Tag Constants

Small Versions of Controls

Human Interface Guidelines permit the use of small versions of certain controls, which should only be used when space is at a premium. Full size and small controls should not be mixed in the same window.

The following lists those controls described in this chapter that are available in small versions, and describes how to create them.

Idle Processing

The following four controls need to perform idle processing for the reasons indicated:

When these controls are displayed in a document window, your application may need to call IdleControls at the appropriate interval in your event loop, otherwise the animations, etc., will not occur. IdleControls sends a particular message to the CDEF, which responds appropriately.

The call to IdleControls is not necessary on Mac OS X because Mac OS X controls idle themselves automatically using their own internal timers. However, as of the time of writing, the call is necessary on Mac OS 8/9 because controls on Mac OS 8/9 do not yet have internal timers.

When these controls are displayed in a dialog on Mac OS 8/9, ModalDialog calls IdleControls for you.

You can determine whether a control has an internal timer by calling GetControlFeatures and testing for the kControlIdlesWithTimer bit.

Defining Your Own Key Filter Function

You can attach a key filter function to edit text controls to filter key strokes or modify them on return. . Your key filter function can change the keystroke, leave it alone, or block the CDEF from receiving it. For example, an edit text control could use a key filter function to allow only numeric values to be input in its field.

You would declare your key filter function as follows:

     ControlKeyFilterResult  myKeyFilterFunction(ControlRef controlRef,SInt16* keyCode,
                                                 SInt16 *charCode,EventModifiers *modifiers);

The Control Manager defines the data type ControlKeyFilterUPP to identify the universal procedure pointer for this application-defined (callback) function:

     typedef STACK_UPP_TYPE(ControlKeyFilterProcPtr) ControlKeyFilterUPP; 

As stated at Edit Text, above, the control data tag constant for getting and setting a key filter function is kControlKeyFilterTag and the data type returned or set is ControlKeyFilterUPP.

Example

The following example relates to an edit text control and assumes an application-defined key filter function named numericFilter.

     #define kLeftArrow   0x1C
     #define kRightArrow  0x1D
     #define kUpArrow     0x1E
     #define kDownArrow   0x1F
     #define kBackspace   0x08
     ...

     ControlKeyFilterUPP  numericFilterUPP;
     ControlRef           controlHdl;
     ...

     // ................................................. get universal procedure pointer

     numericFilterUPP = NewControlKeyFilterProc(numericFilter);

     // ....................................... attach key filter function to the control

     GetDialogItemAsControl(dialogPtr,itemNumber,&controlHdl);
     SetControlData(controlHdl,kControlNoPart,kControlEditTextKeyFilterTag,
                    sizeof(numericFilterUPP),(Ptr) &numericFilterUPP);

     ...

     // ××××××××××××××××××××××××××××××××××××××××××××××××××××××××××××××××××× numericFilter
     //
     // This function will be called each time the edit text control receives a keystroke.
     // Keystrokes that are to be accepted must return kControlKeyFilterPassKey.  
     // Keystrokes that are to be blocked must return kControlKeyFilterBlockKey.  This 
     // function blocks all but the numeric keys, the "dash" key, and the arrow keys.

     pascal ControlKeyFilterResult numericFilter(ControlRef control,SInt16* keyCode,
                                                 SInt16 *charCode,SInt16 *modifiers)
     {
       if(((char) *charCode >= '0') && ((char) *charCode <= '9'))
         return kControlKeyFilterPassKey;
  
       switch(*charCode)
       {
         case '-':
         case kLeftArrow:
         case kRightArrow:
         case kUpArrow:
         case kDownArrow:
         case kBackspace:
           return kControlKeyFilterPassKey;
           break;

         default:
           SysBeep(10);
           return kControlKeyFilterBlockKey;
           break;
       }
     }

Defining Your Own Edit Text Validation Function

A key filter function, however, does not cater for the case of pasting text to an edit text item. Accordingly, you will ordinarily want to combine an edit text validation function with the key filter function for a specific edit text control.

You would declare your edit text validation function as follows:

     void  myEditTextValidationFunction(ControlRef controlHdl);

The following example ensures that, if a user supplied filename pasted to the edit text item contains one or more colons, those colons will be replaced with dashes.

     ControlEditTextValidationUPP editTextValidatorUPP;
     ControlRef                   controlHdl;
     ...

     // ................................................. get universal procedure pointer

     editTextValidatorUPP = NewControlEditTextValidationProc(editTextValidator); 

     // ............................. attach edit text validation function to the control

     GetDialogItemAsControl(dialogPtr,iEditText1,&controlHdl);
     SetControlData(controlHdl,kControlNoPart,kControlEditTextValidationProcTag,
                    sizeof(editTextValidatorUPP),&editTextValidatorUPP);
     ...

     pascal void  editTextValidator(ControlRef controlHdl)
     {
       Str31  theText;
       Size   actualSize;
       UInt8  a;

       // ................................. Get the text to be examined from the control

       GetControlData(controlHdl,kControlNoPart,kControlEditTextTextTag,
                      sizeof(theText) -1,(Ptr) &theText[1],&actualSize);

       // ............................................ Set the length byte to the number
       // ...... of characters in the text, limited to the current maximum for filenames

       if(actualSize <= 31)
         theText[0] = actualSize;
       else
         theText[0] = 31;

       // ............................................... Replace any colons with dashes

       for(a=1;a<=theText[0];a++)
       {
         if(theText[a] == ':')
           theText[a] = '-';
       }

       // .............................................. You might want to add code here
       //  here to check whether any characters were replaced before bothering to redraw

       // ................ Put the replaced text into the control and redraw the control

       SetControlData(controlHdl,kControlNoPart,kControlEditTextTextTag,theText[0],
                      (Ptr) &theText[1]);

       Draw1Control(controlHdl);
     }

Defining Your Own User Pane Functions

As previously stated, one of the functions of a user pane is to provide a way to hook in application-defined (callback) functions which perform actions such as drawing, hit testing, tracking, etc. Such application-defined (callback) functions are called user pane functions. User pane functions provide you with the ability to create a custom control without writing your own control definition function.

User Pane Functions

User pane functions are categorised as follows:

Control Data Tag Constants and Universal Procedure Pointers

Once you have provided a user pane function, you call SetControlData with the control data tag constant representing the user pane function you wish to set passed in the inTagName parameter and a universal procedure pointer to the user pane function passed in the inData parameter.

Control Data Tag Constants

The control data tag constants relating to user pane functions are as follows:

Creating and Disposing of Universal Procedure Pointers

The following functions create and dispose of universal procedure pointers for user pane functions:

     NewControlUserPaneDrawUPP         DisposeControlUserPaneDrawUPP
     NewControlUserPaneHitTestUPP      DisposeControlUserPaneHitTestUPP
     NewControlUserPaneTrackingUPP     DisposeControlUserPaneTrackingUPP
     NewControlUserPaneIdleUPP         DisposeControlUserPaneIdleUPP
     NewControlUserPaneKeyDownUPP      DisposeControlUserPaneKeyDownUPP
     NewControlUserPaneActivateUPP     DisposeControlUserPaneActivateUPP
     NewControlUserPaneFocusUPP        DisposeControlUserPaneFocusUPP
     NewControlUserPaneBackgroundUPP   DisposeControlUserPaneBackgroundUPP

Main Constants, Data Types and Functions

Constants

Control Definition IDs

KControlBevelButtonSmallBevelProc         = 32
KControlBevelButtonNormalBevelProc        = 33
KControlBevelButtonLargeBevelProc         = 34
kControlSliderProc                        = 48
kControlSliderLiveFeedback                = (1 << 0)
kControlSliderHasTickMarks                = (1 << 1)
kControlSliderReverseDirection            = (1 << 2)
kControlSliderNonDirectional              = (1 << 3)
kControlTriangleProc                      = 64
kControlTriangleLeftFacingProc            = 65
kControlTriangleAutoToggleProc            = 66
kControlTriangleLeftFacingAutoToggleProc  = 67
kControlProgressBarProc                   = 80
kControlLittleArrowsProc                  = 96
kControlChasingArrowsProc                 = 112
kControlTabLargeNorthProc                 = 128
kControlTabSmallNorthProc                 = 129
kControlTabLargeSouthProc                 = 130
kControlTabSmallSouthProc                 = 131
kControlTabLargeEastProc                  = 132
kControlTabSmallEastProc                  = 133
kControlTabLargeWestProc                  = 134
kControlTabSmallWestProc                  = 135
kControlSeparatorLineProc                 = 144
kControlGroupBoxTextTitleProc             = 160
kControlGroupBoxCheckBoxProc              = 161
kControlGroupBoxPopupButtonProc           = 162
kControlGroupBoxSecondaryTextTitleProc    = 164
kControlGroupBoxSecondaryCheckBoxProc     = 165
kControlGroupBoxSecondaryPopupButtonProc  = 166
kControlImageWellProc                     = 176
kControlPopupArrowEastProc                = 192
kControlPopupArrowWestProc                = 193
kControlPopupArrowNorthProc               = 194
kControlPopupArrowSouthProc               = 195
kControlPopupArrowSmallEastProc           = 196
kControlPopupArrowSmallWestProc           = 197
kControlPopupArrowSmallNorthProc          = 198
kControlPopupArrowSmallSouthProc          = 199
kControlPlacardProc                       = 224
kControlClockTimeProc                     = 240
kControlClockTimeSecondsProc              = 241
kControlClockDateProc                     = 242
kControlClockMonthYearProc                = 243
kControlUserPaneProc                      = 256
kControlEditTextProc                      = 272
kControlEditTextDialogProc                = 273
kControlEditTextPasswordProc              = 274
kControlEditTextInlineInputProc           = 276
kControlStaticTextProc                    = 288
kControlPictureProc                       = 304
kControlPictureNoTrackProc                = 305
kControlIconProc                          = 320
kControlIconNoTrackProc                   = 321
kControlIconSuiteProc                     = 322
kControlIconSuiteNoTrackProc              = 323
kControlIconRefProc                       = 324
kControlIconRefNoTrackProc                = 325
kControlWindowHeaderProc                  = 336
kControlWindowListViewHeaderProc          = 337
kControlListBoxProc                       = 352
kControlListBoxAutoSizeProc               = 353
kControlRadioGroupProc                    = 416
kControlScrollTextBoxProc                 = 432
kControlScrollTextBoxAutoScrollProc       = 433

Control Variants

kControlNoVariant                         = 0
kControlUsesOwningWindowsFontVariant      = 1 << 3

Control Part Codes

kControlNoPart                  = 0
kControlLabelPart               = 1
kControlMenuPart                = 2
kControlTrianglePart            = 4
kControlEditTextPart            = 5
kControlPicturePart             = 6
kControlIconPart                = 7
kControlClockPart               = 8
kControlClockHourDayPart        = 9,
kControlClockMinuteMonthPart    = 10
kControlClockSecondYearPart     = 11
kControlClockAMPMPart           = 12
kControlListBoxPart             = 24
kControlListBoxDoubleClickPart  = 25
kControlImageWellPart           = 26
kControlRadioGroupPart          = 27
kControlButtonPart              = 10
kControlCheckBoxPart            = 11
kControlRadioButtonPart         = 11
kControlUpButtonPart            = 20
kControlDownButtonPart          = 21
kControlPageUpPart              = 22
kControlPageDownPart            = 23
kControlIndicatorPart           = 129
kControlDisabledPart            = 254
kControlInactivePart            = 255

Bevel Button Graphic Alignment

KControlBevelButtonAlignSysDirection  = -1
KControlBevelButtonAlignCenter        = 0
KControlBevelButtonAlignLeft          = 1
KControlBevelButtonAlignRight         = 2
KControlBevelButtonAlignTop           = 3
kControlBevelButtonAlignBottom        = 4
kControlBevelButtonAlignTopLeft       = 5
kControlBevelButtonAlignBottomLeft    = 6
kControlBevelButtonAlignTopRight      = 7
kControlBevelButtonAlignBottomRight   = 8

Bevel Button Text Alignment values

KControlBevelButtonAlignTextSysDirection  = teFlushDefault
KControlBevelButtonAlignTextCenter        = teCenter
KControlBevelButtonAlignTextFlushRight    = teFlushRight
KControlBevelButtonAlignTextFlushLeft     = teFlushLeft

Bevel Button Text Placement

KControlBevelButtonPlaceSysDirection      = -1
KControlBevelButtonPlaceNormally          = 0
KControlBevelButtonPlaceToRightOfGraphic  = 1
KControlBevelButtonPlaceToLeftOfGraphic   = 2
KControlBevelButtonPlaceBelowGraphic      = 3
KControlBevelButtonPlaceAboveGraphic      = 4

Bevel Button Behaviour

kControlBehaviorPushbutton      = 0
kControlBehaviorToggles         = 0x0100
kControlBehaviorSticky          = 0x0200
kControlBehaviorSingleValueMenu = 0 
kControlBehaviorMultiValueMenu  = 0x4000
kControlBehaviorOffsetContents  = 0x8000
kControlBehaviorCommandMenu     = 0x2000

Bevel Button Content Type

kControlContentTextOnly         = 0
kControlContentIconSuiteRes     = 1
kControlContentCIconRes         = 2
kControlContentPictRes          = 3
kControlContentIconSuiteHandle  = 129
kControlContentCIconHandle      = 130
kControlContentPictHandle       = 131
kControlContentIconRef          = 132

Bevel Button Thickness

kControlBevelButtonSmallBevel   = 0
kControlBevelButtonNormalBevel  = 1
kControlBevelButtonLargeBevel   = 2

Bevel Button Menu Placement

kControlBevelButtonMenuOnBottom = 0
kControlBevelButtonMenuOnRight  = (1 << 2)

Tab Size

Tab Direction

Clock Value Flag Constants

kControlClockNoFlags        = 0
kControlClockIsDisplayOnly  = 1
kControlClockIsLive         = 2

Control Data Tags

kControlFontStyleTag                            = FOUR_CHAR_CODE('font')
kControlKeyFilterTag                            = FOUR_CHAR_CODE('fltr')
kControlBevelButtonContentTag                   = FOUR_CHAR_CODE('cont')
kControlBevelButtonTransformTag                 = FOUR_CHAR_CODE('tran')
kControlBevelButtonTextAlignTag                 = FOUR_CHAR_CODE('tali')
kControlBevelButtonTextOffsetTag                = FOUR_CHAR_CODE('toff')
kControlBevelButtonGraphicAlignTag              = FOUR_CHAR_CODE('gali')
kControlBevelButtonGraphicOffsetTag             = FOUR_CHAR_CODE('goff')
kControlBevelButtonTextPlaceTag                 = FOUR_CHAR_CODE('tplc')
kControlBevelButtonMenuValueTag                 = FOUR_CHAR_CODE('mval')
kControlBevelButtonMenuRefTag                   = FOUR_CHAR_CODE('mhnd')
kControlBevelButtonMenuRefTag                   = FOUR_CHAR_CODE('mhnd')
kControlBevelButtonOwnedMenuRefTag              = FOUR_CHAR_CODE('omrf')
kControlBevelButtonKindTag                      = FOUR_CHAR_CODE('bebk')
kControlBevelButtonCenterPopupGlyphTag          = FOUR_CHAR_CODE('pglc')
kControlBevelButtonLastMenuTag                  = FOUR_CHAR_CODE('lmnu')
kControlBevelButtonMenuDelayTag                 = FOUR_CHAR_CODE('mdly')
kControlBevelButtonScaleIconTag                 = FOUR_CHAR_CODE('scal')
kControlTriangleLastValueTag                    = FOUR_CHAR_CODE('last')
kControlProgressBarIndeterminateTag             = FOUR_CHAR_CODE('inde')
kControlTabContentRectTag                       = FOUR_CHAR_CODE('rect')
kControlTabEnabledFlagTag                       = FOUR_CHAR_CODE('enab')
kControlTabFontStyleTag                         = kControlFontStyleTag
kControlTabInfoTag                              = FOUR_CHAR_CODE('tabi')
kControlGroupBoxMenuHandleTag                   = FOUR_CHAR_CODE('mhan')
kControlGroupBoxFontStyleTag                    = kControlFontStyleTag
kControlGroupBoxTitleRectTag                    = FOUR_CHAR_CODE('trec')
kControlImageWellContentTag                     = FOUR_CHAR_CODE('cont')
kControlImageWellTransformTag                   = FOUR_CHAR_CODE('tran')
kControlClockLongDateTag                        = FOUR_CHAR_CODE('date')
kControlClockFontStyleTag                       = kControlFontStyleTag
kControlClockAnimatingTag                       = FOUR_CHAR_CODE('anim')
kControlUserItemDrawProcTag                     = FOUR_CHAR_CODE('uidp')
kControlUserPaneDrawProcTag                     = FOUR_CHAR_CODE('draw')
kControlUserPaneHitTestProcTag                  = FOUR_CHAR_CODE('hitt')
kControlUserPaneTrackingProcTag                 = FOUR_CHAR_CODE('trak')
kControlUserPaneIdleProcTag                     = FOUR_CHAR_CODE('idle')
kControlUserPaneKeyDownProcTag                  = FOUR_CHAR_CODE('keyd')
kControlUserPaneActivateProcTag                 = FOUR_CHAR_CODE('acti')
kControlUserPaneFocusProcTag                    = FOUR_CHAR_CODE('foci')
kControlUserPaneBackgroundProcTag               = FOUR_CHAR_CODE('back')
kControlEditTextStyleTag                        = kControlFontStyleTag
kControlEditTextTextTag                         = FOUR_CHAR_CODE('text')
kControlEditTextTEHandleTag                     = FOUR_CHAR_CODE('than')
kControlEditTextKeyFilterTag                    = kControlKeyFilterTag,
kControlEditTextSelectionTag                    = FOUR_CHAR_CODE('sele')
kControlEditTextPasswordTag                     = FOUR_CHAR_CODE('pass')
kControlEditTextLockedTag                       = FOUR_CHAR_CODE('lock')
kControlEditTextValidationProcTag               = FOUR_CHAR_CODE('vali')
kControlEditTextCFStringTag                     = FOUR_CHAR_CODE('cfst')
kControlStaticTextStyleTag                      = kControlFontStyleTag
kControlStaticTextTextTag                       = FOUR_CHAR_CODE('text')
kControlStaticTextTextHeightTag                 = FOUR_CHAR_CODE('thei')
kControlStaticTextTruncTag                      = FOUR_CHAR_CODE('trun')
kControlIconTransformTag                        = FOUR_CHAR_CODE('trfm')
kControlIconAlignmentTag                        = FOUR_CHAR_CODE('algn')
kControlIconResourceIDTag                       = FOUR_CHAR_CODE('ires')
kControlIconContentTag                          = FOUR_CHAR_CODE('cont')
kControlListBoxListHandleTag                    = FOUR_CHAR_CODE('lhan')
kControlListBoxKeyFilterTag                     = kControlKeyFilterTag
kControlListBoxFontStyleTag                     = kControlFontStyleTag
kControlListBoxDoubleClickTag                   = FOUR_CHAR_CODE('dblc')
kControlScrollTextBoxDelayBeforeAutoScrollTag   = FOUR_CHAR_CODE('stdl')
kControlScrollTextBoxDelayBetweenAutoScrollTag  = FOUR_CHAR_CODE('scdl')
kControlScrollTextBoxAutoScrollAmountTag        = FOUR_CHAR_CODE('samt')
kControlScrollTextBoxContentsTag                = FOUR_CHAR_CODE('tres')
kControlRoundButtonContentTag                   = FOUR_CHAR_CODE('cont'
kControlRoundButtonSizeTag                      = FOUR_CHAR_CODE('size'

Slider Orientation

kControlSliderPointsDownOrRight                = 0
kControlSliderPointsUpOrLeft                   = 1
kControlSliderDoesNotPoint                     = 2

Clock Control Type

kControlClockTypeHourMinute                    = 0
kControlClockTypeHourMinuteSecond              = 1
kControlClockTypeMonthDayYear                  = 2
kControlClockTypeMonthYear                     = 3

Disclosure Triangle Orientation

kControlDisclosureTrianglePointDefault         = 0
kControlDisclosureTrianglePointRight           = 1
kControlDisclosureTrianglePointLeft            = 2

Popup Arrow Orientation

kControlPopupArrowOrientationEast              = 0
kControlPopupArrowOrientationWest              = 1
kControlPopupArrowOrientationNorth             = 2
kControlPopupArrowOrientationSouth             = 3

Key Filter Result Codes

kControlKeyFilterBlockKey  = 0
kControlKeyFilterPassKey   = 1

Control Feature Bits

kControlSupportsGhosting      = 1 << 0
kControlSupportsEmbedding     = 1 << 1
kControlSupportsFocus         = 1 << 2
kControlWantsIdle             = 1 << 3
kControlWantsActivate         = 1 << 4
kControlHandlesTracking       = 1 << 5
kControlSupportsDataAccess    = 1 << 6
kControlHasSpecialBackground  = 1 << 7
kControlGetsFocusOnClick      = 1 << 8
kControlSupportsCalcBestRect  = 1 << 9
kControlSupportsLiveFeedback  = 1 << 10
kControlHasRadioBehavior      = 1 << 11

Focusing Part Codes

KcontrolFocusNoPart    = 0
KControlFocusNextPart  = -1
kControlFocusPrevPart  = -2

Disclosure Button State

kControlDisclosureButtonClosed                 = 0
kControlDisclosureButtonDisclosed              = 1

Round Button Size

kControlRoundButtonNormalSize                  = 0
kControlRoundButtonLargeSize                   = 2

Control Feature Bit Ð Internal Timer

kControlIdlesWithTimer                         = 1 << 23

Control Kind (Mac OS X Only)

kControlKindBevelButton                        = FOUR_CHAR_CODE('bevl')
kControlKindImageWell                          = FOUR_CHAR_CODE('well')
kControlKindTabs                               = FOUR_CHAR_CODE('tabs')
kControlKindEditText                           = FOUR_CHAR_CODE('etxt')
kControlKindSlider                             = FOUR_CHAR_CODE('sldr')
kControlKindCheckGroupBox                      = FOUR_CHAR_CODE('cgrp')
kControlKindPopupGroupBox                      = FOUR_CHAR_CODE('pgrp')
kControlKindClock                              = FOUR_CHAR_CODE('clck')
kControlKindProgressBar                        = FOUR_CHAR_CODE('prgb')
kControlKindRelevanceBar                       = FOUR_CHAR_CODE('relb')
kControlKindLittleArrows                       = FOUR_CHAR_CODE('larr')
kControlKindDisclosureTriangle                 = FOUR_CHAR_CODE('dist')
kControlKindPicture                            = FOUR_CHAR_CODE('pict')
kControlKindIcon                               = FOUR_CHAR_CODE('icon')
kControlKindWindowHeader                       = FOUR_CHAR_CODE('whed')
kControlKindPlacard                            = FOUR_CHAR_CODE('plac')
kControlKindStaticText                         = FOUR_CHAR_CODE('stxt')
kControlKindSeparator                          = FOUR_CHAR_CODE('sepa')
kControlKindPopupArrow                         = FOUR_CHAR_CODE('parr')
kControlKindRadioGroup                         = FOUR_CHAR_CODE('rgrp')
kControlKindChasingArrows                      = FOUR_CHAR_CODE('carr')
kControlKindScrollingTextBox                   = FOUR_CHAR_CODE('stbx')
kControlKindDisclosureButton                   = FOUR_CHAR_CODE('disb')
kControlKindRoundButton                        = FOUR_CHAR_CODE('rndb')

Data Types

typedef SInt16 ControlFocusPart;
typedef SInt16 ControlKeyFilterResult;
typedef SInt16 ControlButtonGraphicAlignment;
typedef SInt16 ControlButtonTextAlignment;
typedef SInt16 ControlButtonTextPlacement;
typedef SInt16 ControlContentType;
typedef SInt16 ControlVariant;
typedef UInt16 ControlSliderOrientation;
typedef UInt16 ControlClockType;
typedef UInt16 ControlDisclosureTriangleOrientation;
typedef SInt16 ControlRoundButtonSize;

Button Content Info Structure

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;

Tab Information Structures

struct ControlTabInfoRec
{
  SInt16 version;
  SInt16 iconSuiteID;
  Str255 name;
};
typedef struct ControlTabInfoRec ControlTabInfoRec;

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

Tab Entry Structures

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

Edit Text Selection Structure

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

Functions

Give Idle Time To Controls

void  IdleControls(WindowPtr inWindow);

Send Keyboard Event to Control With keyboard Focus

Sint16  HandleControlKey(ControlRef inControl,SInt16 inKeyCode,SInt16 inCharCode,
        SInt16 inModifiers);

Set the Background For a Control

OSErr  SetUpControlBackground (ControlRef inControl,SInt16 inDepth,
       Boolean inIsColorDevice);

KeyBoard Focus

OSErr  GetKeyboardFocus(WindowPtr inWindow,ControlRef *outControl);
OSErr  SetKeyboardFocus(WindowPtr inWindow,ControlRef inControl,ControlFocusPart   inPart); 
OSErr  AdvanceKeyboardFocus(WindowPtr inWindow);
OSErr  ReverseKeyboardFocus(WindowPtr inWindow);
OSErr  ClearKeyboardFocus(WindowPtr inWindow);

Control Features

OSErr  GetControlFeatures(ControlRef inControl,UInt32 *outFeatures);

Validating Controls

Boolean  IsValidControlhandle(ControlRef theControl);

Creating Controls Programmatically

OSStatus  CreateBevelButtonControl(WindowRef window,const Rect *boundsRect,
          CFStringRef title,ControlBevelThickness thickness,
          ControlBevelButtonBehavior behavior,ControlButtonContentInfoPtr info, SInt16 menuID,
          ControlBevelButtonMenuBehavior menuBehavior,
          ControlBevelButtonMenuPlacement menuPlacement,ControlRef *outControl);
OSStatus  CreateImageWellControl(WindowRef window,const Rect *boundsRect,
          const ControlButtonContentInfo *info,ControlRef *outControl);
OSStatus  CreateTabsControl(WindowRef window,const Rect *boundsRect,ControlTabSize size,
          ControlTabDirection direction,UInt16 numTabs,const ControlTabEntry *tabArray,
          ControlRef *outControl);
OSStatus  CreateEditTextControl(WindowRef window,const Rect *boundsRect, CFStringRef text,
          Boolean isPassword,Boolean useInlineInput,const ControlFontStyleRec *style,
          ControlRef *outControl);
OSStatus  CreateSliderControl(WindowRef window,const Rect *boundsRect,SInt32 value,
          SInt32 minimum,SInt32 maximum,ControlSliderOrientation  orientation,
          UInt16 numTickMarks,Boolean liveTracking,ControlActionUPP liveTrackingProc,
          ControlRef *outControl);
OSStatus  CreateGroupBoxControl(WindowRef window,const Rect *boundsRect, CFStringRef title,
          Boolean primary,ControlRef *outControl);
OSStatus  CreateCheckGroupBoxControl(WindowRef window,const Rect *boundsRect,
          CFStringRef title,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);
OSStatus  CreateClockControl(WindowRef window,const Rect *boundsRect,
          ControlClockType clockType,
          ControlClockFlags clockFlags,ControlRef *outControl);
OSStatus  CreateProgressBarControl(WindowRef window,const Rect *boundsRect,SInt32 value,
          SInt32 minimum,SInt32 maximum,Boolean indeterminate,ControlRef *outControl);
OSStatus  CreateLittleArrowsControl(WindowRef window,const Rect *boundsRect,SInt32 value,
          SInt32 minimum,SInt32 maximum,SInt32 increment,ControlRef *outControl);
OSStatus  CreateDisclosureTriangleControl(WindowRef window,const Rect *boundsRect,
          ControlDisclosureTriangleOrientation orientation, CFStringRef title,
          Boolean drawTitle,Boolean autoToggles,ControlRef *outControl);
OSStatus  CreatePictureControl(WindowRef window,const Rect *boundsRect,
          const ControlButtonContentInfo *content,Boolean dontTrack,ControlRef *outControl);
OSStatus  CreateIconControl(WindowRef window,const Rect *boundsRect,
          const ControlButtonContentInfo *icon,Boolean dontTrack,ControlRef *outControl);
OSStatus  CreateWindowHeaderControl(WindowRef window,const Rect *boundsRect,
          Boolean isListHeader,ControlRef *outControl);
OSStatus  CreatePlacardControl(WindowRef window,const Rect *boundsRect,ControlRef *outControl);
OSStatus  CreateStaticTextControl(WindowRef window,const Rect *boundsRect,
          CFStringRef text,const ControlFontStyleRec *style,ControlRef *outControl);
OSStatus  CreateSeparatorControl(WindowRef window,const Rect *boundsRect,
          ControlRef *outControl);
OSStatus  CreatePopupArrowControl(WindowRef window,const Rect *boundsRect,
          ControlPopupArrowOrientation orientation,ControlPopupArrowSize size,
          ControlRef *outControl);
OSStatus  CreateRadioGroupControl(WindowRef window,const Rect *boundsRect,
          ControlRef *outControl);
OSStatus  CreateChasingArrowsControl(WindowRef window,const Rect *boundsRect,
          ControlRef *outControl);
OSStatus  CreateUserPaneControl(WindowRef window,const Rect *boundsRect,UInt32 features,
          ControlRef *outControl);
OSStatus  CreateScrollingTextBoxControl(WindowRef window,const Rect *boundsRect,
          SInt16 contentResID, Boolean autoScroll,UInt32 delayBeforeAutoScroll,
          UInt32 delayBetweenAutoScroll, UInt16 autoScrollAmount,ControlRef *outControl);

Creating Controls Programmatically (Controls Available on Mac OS X Only)

OSStatus  CreateRelevanceBarControl(WindowRef window,const Rect *boundsRect,SInt32 value,
          SInt32 minimum,SInt32 maximum,ControlRef *outControl);
OSStatus  CreateDisclosureButtonControl(WindowRef inWindow,const Rect *inBoundsRect,
          SInt32 inValue,Boolean inAutoToggles,ControlRef *  outControl);
OSStatus  CreateEditUnicodeTextControl(WindowRef window,const Rect *boundsRect,
          CFStringRef text,Boolean isPassword,const ControlFontStyleRec *style,
          ControlRef *outControl);
OSStatus  CreateRoundButtonControl(WindowRef nWindow,const Rect *inBoundsRect,
          ControlRoundButtonSize inSize,ControlButtonContentInfo *inContent,
          ControlRef *outControl);

Helper Functions

OSErr     GetBevelButtonMenuValue ControlRef inButton,SInt16 * outValue);
OSErr     SetBevelButtonMenuValue ControlRef inButton,SInt16 inValue);
OSErr     GetBevelButtonMenuHandle ControlRef inButton,MenuHandle * outHandle);
OSErr     GetBevelButtonContentInfo ControlRef inButton,
          ControlButtonContentInfoPtr outContent);
OSErr     SetBevelButtonContentInfo ControlRef inButton,ControlButtonContentInfoPtr inContent);
OSErr     SetBevelButtonTransform ControlRef inButton,IconTransformType transform);
OSErr     SetBevelButtonGraphicAlignment ControlRef inButton,
          ControlButtonGraphicAlignment inAlign,SInt16 inHOffset,SInt16 inVOffset);
OSErr     SetBevelButtonTextAlignment ControlRef inButton,ControlButtonTextAlignment inAlign,
          SInt16 inHOffset);
OSErr     SetBevelButtonTextPlacement ControlRef inButton,ControlButtonTextPlacement inWhere);
OSErr     GetImageWellContentInfo(ControlRef inButton,ControlButtonContentInfoPtr outContent);
OSErr     SetImageWellContentInfo(ControlRef inButton,ControlButtonContentInfoPtr inContent);
OSErr     SetImageWellTransform(ControlRef inButton,IconTransformType inTransform);
OSErr     GetTabContentRect(ControlRef inTabControl,Rect * outContentRect);
OSErr     SetTabEnabled(ControlRef inTabControl,SInt16 inTabToHilite,Boolean inEnabled);
OSErr     SetDisclosureTriangleLastValue(ControlRef inTabControl,SInt16 inValue);

Application-Defined (Callback) Functions

ControlKeyFilterResult  myKeyFilterFunction(ControlRef controlRef,SInt16* keyCode,
                  SInt16 *charCode,EventModifiers *modifiers);
void                    myEditTextValidationFunction(ControlRef controlHdl);

Creating and Disposing of Universal Procedure Pointers Ñ User Pane Functions

ControlUserPaneDrawUPP        NewControlUserPaneDrawUPP(ControlUserPaneDrawProcPtr
                              userRoutine);
ControlUserPaneHitTestUPP     NewControlUserPaneHitTestUPP(ControlUserPaneHitTestProcPtr
                              userRoutine);
ControlUserPaneTrackingUPP    NewControlUserPaneTrackingUPP(ControlUserPaneTrackingProcPtr
                              userRoutine);
ControlUserPaneIdleUPP        NewControlUserPaneIdleUPP(ControlUserPaneIdleProcPtr
                              userRoutine);
ControlUserPaneKeyDownUPP     NewControlUserPaneKeyDownUPP(ControlUserPaneKeyDownProcPtr
                              userRoutine);
ControlUserPaneActivateUPP    NewControlUserPaneActivateUPP(ControlUserPaneActivateProcPtr
                              userRoutine);
ControlUserPaneFocusUPP       NewControlUserPaneFocusUPP(ControlUserPaneFocusProcPtr
                              userRoutine);
ControlUserPaneBackgroundUPP  NewControlUserPaneBackgroundUPP(ControlUserPaneBackgroundProcPtr
                              userRoutine);
void  DisposeControlUserPaneDrawUPP(ControlUserPaneDrawUPP userUPP);
void  DisposeControlUserPaneHitTestUPP(ControlUserPaneHitTestUPP userUPP);
void  DisposeControlUserPaneTrackingUPP(ControlUserPaneTrackingUPP userUPP);
void  DisposeControlUserPaneIdleUPP(ControlUserPaneIdleUPP userUPP);
void  DisposeControlUserPaneKeyDownUPP(ControlUserPaneKeyDownUPP userUPP);
void  DisposeControlUserPaneActivateUPP(ControlUserPaneActivateUPP userUPP);
void  DisposeControlUserPaneFocusUPP(ControlUserPaneFocusUPP userUPP);
void  DisposeControlUserPaneBackgroundUPP(ControlUserPaneBackgroundUPP userUPP);