The controls addressed in this chapter are as follows:

The one remaining control (the list box) will be addressed at Chapter 20 - Lists and Custom List Definition Functions.

The progress indicator 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 demonstation program associated with Chapter 23 - Miscellany.

Preamble - Review of Control Basics

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

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

• Another feature introduced with Mac OS 8 and the Appearance Manager 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 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

Variants and Control Definition IDs

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

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

Bevel Button Menu Constants

Bevel Button and Image Well Content Type Constants

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) or handle (for handle-based content) of a colour icon, icon suite, or picture 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

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

Bevel Button Text Alignment Constants

Bevel Button Text Placement Constants

Control Data Tag Constants - Alignment and Placement

The Bevel Button and Image Well Content Structure

     struct ControlButtonContentInfo 
     {
       ControlContentType contentType;
       union 
       {
         Sint16       resID;
         CIconHandle  cIconHandle;
         Handle       iconSuite;
         Handle       iconRef;
         PicHandle    picture;
       } u;
     };
     typedef struct ControlButtonContentInfo ControlButtonContentInfo;
     typedef ControlButtonContentInfo *ControlButtonContentInfoPtr;

Other Control Data Tag Constants

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.

Bevel Button States

Under platinum appearance, both pressed states look the same, but this may change in future themes.

Variants and Control Definition IDs

Future versions will support drag-and-drop functionality.

Control Values

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

You can also use these constants in the contentType field of the bevel button and image well content 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.

Control Part Codes

The tab control supports one row of tabs running along the top (see Fig 3). You specify the names and icons that label the tabs.

The appearance of the content area of a tab control (also known as a pane) depends on where it is used. In a control panel, the sides of the pane should be tucked under the edge of the content region by one pixel. In a modal dialog box, the left and right sides of the pane should be inset two pixels from the edge of the dialog box's content region. This small distinction helps emphasise the fact that the tab is part of a dialog box. (See Fig 3.)

Controls such as push buttons, radio buttons, scroll bars, etc., may be used within a tab control, and should be embedded within an individual 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. It is important that you make such distinctions unambiguous to the user through clear, specific labelling and placement.

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

Variants and Control Definition IDs

Control Values

Control Data Tag Constants

The Tab Information Structure

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

The Tab Information Resource

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

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

Control Values

Control Data Tag Constants

Control Part Codes

The Edit Text Selection Structure

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

A slider can display tick marks to represent increments within the range of values. You can specify the number of tick marks required. If you use tick marks, they are drawn appropriately for the direction of the slider. You should ensure that tick marks are labelled so that they clearly indicate the effect of moving the indicator.

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

Control Values

Control Part Codes

Group boxes are defined as either primary or secondary. The main visual distinction between the two types is their border: primary group box border lines are two pixels wide with an etched look; secondary group box borders are one pixel wide.

You can use any of four titling options for the border of a group box. The 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 nesting and grouping together subsidiary information. Secondary group boxes should not be used in lieu of primary group boxes, since this produces an inconsistent appearance which could confuse users.

Typical group boxes are shown at Fig 7.

Variants and Control Definition IDs

Control Values

Control Data Tag Constant

Control Part Codes

The clock control supports keyboard navigation and focus. When the clock control has keyboard focus, pressing the up-arrow and down-arrow keys has the same effect as clicking the up and down arrows in the control.

Variants and Control Definition IDs

Control Values

Clock Value Flag Constants

Control Data Tag Constant

Control Part Codes

You might use a determinate progress indicator to, for example, show the progress of a file copying operation. You might use an indeterminate progress indicator to, for example, let the user know that the application is in the process of attempting a communication connection or is waiting to receive data during file transfer. You should consider switching from an indeterminate progress indicator to a determinate one if a process reaches a point where its scope becomes determinable. For example, a remote file transfer may not become determinate until the application has had time to establish a connection and calculate the data transfer rate.

Variants and Control Definition IDs

Progress Indicator Control Values

Control Data Tag Constant

If the user clicks the up arrow, the value displayed is incremented by one unit of change. If the user presses the arrow, the value increases or decreases until the user releases the mouse button. While the user presses the arrow, it is highlighted to provide feedback to the user.

The unit of change should depend on the content. If the content area displays years, for example, the increment should be one year. On the other hand, if you used little arrows to control the size of a RAM cache, for example, you might use multiples of 32K as the increment.

Fig 10 shows a little arrows control used in conjunction with a placard and static text controls.

Variant and Control Definition ID

Control Values

Control Part Codes

One usage of the disclosure triangle is to expand a dialog box or control panel. When the user clicks on the disclosure triangle, the triangle rotates downward and the window expands to provide additional information. A further click on the triangle rotates the triangle back to the right and restores the original appearance of the window.

Another usage pertains to list views (see Fig 11). The triangle appears next to the icon of each folder in the window. The user clicks the triangle to expand the view by revealing a list of the contents of the folder without opening it. The triangle rotates downward when the folder is expanded, which tells the user that the view is expanded even in cases when the folder is empty. Clicking the triangle again restores the view to its original (collapsed) state and turns the triangle back to the right.

Variants and Control Definition IDs

Control Values

Control Data Tag Constant

Control Part Codes

Control Values

Control Part Codes

A non-tracking variant is available for use in dialog boxes 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

Control Values

Control Data Tag Constants

Control Part Codes

The list view header variant provides the same functionality as the window header, but removes the line which separates a standard window header from the content area.

Variants and Control Definition IDs

Control Values

Variants and Control Definition IDs

Future versions will provide a push button variant.

Control Values

Control Values

Control Data Tag Constants

Variants and Control Definition IDs

Control Values

Control Values