Radio groups are embedder 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:
Variant
Var Code
Control Definition ID
Radio group.
0
416
kControlRadioGroupProc
Control Values
Control Value
Content
Initial
Set to 0 on creation. Reset to the index of currently selected embedded radio control after creation. If the currently selected control does not support radio behaviour, this value will be set to 0 and the control will be deselected. To deselect all controls, set to 0.
Minimum
Set to 0.
Maximum
Set to 0 on creation. Reset to the number of embedded controls as controls are added.
Control Part Codes
Constant
Value
Description
kControlRadioGroupPart
27
Event occurred in a radio group.
Asynchronous Arrows
Asynchronous arrows (see Fig 15) 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 box containing a progress indicator. Asynchronous arrows are also known as "chasing arrows".
Variant and Control Definition ID
The asynchronous arrows CDEF resource ID is 7. The one available variant and its control definition ID is as follows:
Variant
Var Code
Control Definition ID
Asynchronous arrows.
0
112
kControlChasingArrowsProc
Control Values
Control Value
Content
Initial
Reserved. Set to 0.
Minimum
Reserved. Set to 0.
Maximum
Reserved. Set to 0.
User Panes (Embedding Control)
The user pane has two main uses:
It can be used as an embedder 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 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:
Variant
Var Code
Control Definition ID
User pane.
0
256
kControlUserPaneProc
Control Values
Control Value
Content
Initial
One or more of the control feature constants. (See Defining Your Own User Pane Functions, below.) Reset to 0 after creation.
Minimum
Ignored. After user pane creation, reset to a setting between -32768 to 32768.
Maximum
Ignored. After user pane creation, reset to a setting between -32768 to 32768.
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.
Scrolling Text Box (Embedding Control)
The scrolling text box implements a scrolling box of non-editable text. This is useful for credits in About boxes, etc. 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 is27. The two available variants and their control definition IDs are as follows:
Variant
Var Code
Control Definition ID
Standard.
0
432
kControlScrollTextBoxProc
Auto-scrolling.
1
433
kControlScrollTextBoxAutoScrollProc
Control Values
Control Value
Content
Initial
Resource ID of a 'TEXT' and, optionally, a 'styl' resource.
Minimum
For the standard variant, set to 0.
For the auto-scrolling variant , the delay (in ticks) before scrolling begins. (This delay is also used between when the scrolling completes and when it begins again.)
Maximum
For the standard variant, set to 0.
For the auto-scrolling variant, the delay (in ticks) between each unit of scrolling.
Control Data Tag Constant
Meaning and Data Type Returned or Set
KControlScrollTextBoxDelayBefore
AutoScrollTag
Gets or sets the number of ticks of delay before the initial scrolling of an auto-scrolling text box begins.
Data type returned or set:UInt32
KControlScrollTextBoxDelay
BetweenAutoScrollTag
Gets or sets the number of ticks of delay between each unit of scrolling in an auto-scrolling text box.
Data type returned or set:UInt32
KControlScrollTextBoxAutoScroll
AmountTag
Gets or sets the number of pixels by which an auto scrolling text box scrolls. (The default is 1.)
Data type returned or set:UInt16
kControlScrollTextBoxContentsTag
Sets the ID of a 'TEXT' resource and, optionally, a 'styl' resource, to be used as the content of a standard or auto-scrolling text box.
Data type returned or set:Sint16
Idle Processing
The following four controls need to perform idle processing for the reasons indicated:
Control
Reason For Idle Processing
Progress Indicator (indeterminate variant).
Animate the indicator.
Clocks (when the kControlClockIsLive clock value flag constant is used).
Update the clock.
Asynchronous arrows.
Animate the arrows.
Edit text control.
Cause TextEdit to be called to blink the insertion point caret.
When these controls are displayed in a document window, your application should call the IdleControls function at least once in your event loop. IdleControls sends a particular message to the CDEF, which responds appropriately.
Defining Your Own Key Filter Function
Controls that support text input (such as edit text control and list box controls) can attach an application-defined key filter function 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.
The Control Manager declares the type for an application-defined key filter function as follows:
As stated at Edit Text Fields, 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;
ControlHandle controlHdl;
...
// ....................................................... create routine descriptor
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(ControlHandle 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. 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;
ControlHandle controlHdl;
...
// ....................................................... create routine descriptor
editTextValidatorUPP = NewControlEditTextValidationProc(editTextValidator);
// ............................. attach edit text validation function to the control
GetDialogItemAsControl(dialogPtr,iEditText1,&controlHdl);
SetControlData(controlHdl,kControlNoPart,kControlEditTextValidationProcTag,
sizeof(editTextValidatorUPP),(Ptr) &editTextValidatorUPP);
...
pascal void editTextValidator(ControlHandle 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 functions which perform actions such as drawing, hit testing, tracking, etc. Such application-defined functions are called user pane functions.
User pane functions provide you with the ability to create a custom Appearance-compliant control without writing your own control definition function.
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 get or set passed in the inTagName parameter and a universal procedure pointer to the user pane function passed in the inData parameter.
User Pane Functions
User pane functions are categorised as follows:
Function
Description
Draw
Draws the content of a user pane control in the rectangle of user pane control.
Hit test
Returns the part code of the control that the point was in when the mouse-down event occurred.
Tracking
Tracks a control while the user holds down the mouse button. The function should track the control by repeatedly calling the action function specified in the actionProc parameter until the mouse button is released. When the mouse button is released, your function should return the part code of the control part that was tracked.
This function will only get called if you have set the kControlHandlesTracking control feature bit on creation of the user pane control.
Idle
Performs idle processing.
This function will only get called if you have set the kControlWantsIdle control feature bit on creation of the user pane control.
Key Down
Handles keyboard event processing. The function should handle the key pressed or released by the user and return the part code of the control where the keyboard event occurred.
This function will only get called if you've set the kControlSupportsFocus control feature bit on creation of the user pane control.
Activate
Handles activate and deactivate event processing. The function should perform any special processing before the user pane becomes activated or deactivated. For example, it should deactivate its TEHandle or ListHandle if the user pane is about to be deactivated.
This function will only get called if you have set the kControlWantsActivate control feature bit on creation of the user pane control.
Focus
Handle keyboard focus. The function is called in response to a change in keyboard focus. It should respond by changing keyboard focus based on the part code passed in the action parameter.
This function will only get called if you have set the kControlSupportsFocus control feature bit on creation of the user pane control.
Background
Sets the background colour or pattern (only for user panes that support embedding). The function should set the user pane background colour or pattern to whatever is appropriate given the bit depth and device type passed in.
This function will only get called if you have set the kControlHasSpecialBackground and kControlSupportsEmbedding control feature bits on creation of the user pane control.
Control Feature Flags
As stated at User Panes, above, the initial value of a user pane is one or more of the control feature constants. As stated in the preceding list of user pane functions, certain user pane functions will only get called if certain control feature flags are set. The control feature flags relevant to user pane functions are as follows:
The control data tag constants relating to user pane functions are as follows:
Control Data Tag Constant
Meaning and Data Type Returned or Set
kControlUserPaneDrawProcTag
Gets or sets a user pane drawing function. Indicates that the Control Manager needs to draw a control.
Data type returned or set:ControlUserPaneDrawingUPP
kControlUserPaneHitTestProcTag
Gets or sets a user pane hit-testing function. Indicates that the Control Manager needs to determine if a control part was hit.
Data type returned or set:ControlUserPaneHitTestUPP
kControlUserPaneTrackingProcTag
Gets or sets a user pane tracking function, which will be called when a control definition function returns the kControlHandlesTracking feature bit in response to a kControlMsgGetFeatures message. Indicates that a user pane handles its own tracking.
Data type returned or set:ControlUserPaneTrackingUPP
kControlUserPaneIdleProcTag
Gets or sets a user pane idle function, which will be called when a control definition function returns the kControlWantsIdle feature bit in response to kControlMsgGetFeatures message. Indicates that a user pane performs idle processing.
Data type returned or set:ControlUserPaneIdleUPP
kControlUserPaneKeyDownProcTag
Gets or sets a user pane key down function, which will be called when a control definition function returns the kControlSupportsFocus feature bit in response to a kControlMsgGetFeatures message. Indicates that a user pane performs keyboard event processing.
Data type returned or set:ControlUserPaneKeyDownUPP
kControlUserPaneActivateProcTag
Gets or sets a user pane activate function, which will be called when a control definition function returns the kControlWantsActivate feature bit in response to a kControlMsgGetFeatures message. Indicates that a user pane wants to be informed of activate and deactivate events.
Data type returned or set:ControlUserPaneActivateUPP
kControlUserPaneFocusProcTag
Gets or sets a user pane keyboard focus function, which will be called when a control definition function returns the kControlSupportsFocus feature bit in response to a kControlMsgGetFeatures message. Indicates that a user pane handles keyboard focus.
Data type returned or set:ControlUserPaneFocusUPP
kControlUserPaneBackgroundProcTag
Gets or sets a user pane background function, which will be called when a control definition function returns the kControlHasSpecialBackground and kControlSupportsEmbedding feature bits in response to a kControlMsgGetFeatures message. Indicates that a user pane can set its background colour or pattern.
Data type returned or set:ControlUserPaneBackgroundUPP
Main Constants, Data Types and Functions
All of the following constants, data types, and functions, with the exception of some of the control part code constants, were introduced with Mac OS 8 and the Appearance Manager. Those introduced with Mac OS 8.5 appear in dark blue.