Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

PATHDocumentation > Mac OS 8 and 9 > Human Interface Toolbox > Control Manager >

Mac OS 8 Control Manager Reference

Defining Your Own Key Filter Function

The following Control Manager function for defining your own key filter function is new with Appearance Manager 1.0:

MyControlKeyFilterProc allows for the interception and possible changing of keystrokes destined for a control. New with Appearance Manager 1.0.

MyControlKeyFilterProc

The key filter function allows for the interception and possible changing of keystrokes destined for a control.

Controls that support text input (such as editable text and list box controls) can attach a key filter function to filter key strokes and modify them on return.

The Control Manager declares the type for an application-defined key filter function as follows:



 
typedef pascal KeyFilterResult (*ControlKeyFilterProcPtr)(

                     ControlHandle theControl,

                     SInt16* keyCode,

                     SInt16* charCode,

                     SInt16* modifiers);

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



 
typedef UniversalProcPtr ControlKeyFilterUPP;

You typically use the NewControlKeyFilterProc macro like this:

ControlKeyFilterUPP myControlKeyFilterUPP; myControlKeyFilterUPP = NewControlKeyFilterProc (MyKeyFilter);

You typically use the CallControlKeyFilterProc macro like this:

CallControlKeyFilterProc (myControlKeyFilterUPP, theControl , keyCode , charCode , modifiers );

Here's how to declare a key filter function if you were to name the function MyControlKeyFilterProc:



 
pascal ControlKeyFilterResult MyControlKeyFilterProc (

                     ControlHandle theControl, 

                     SInt16* keyCode,

                     SInt16* charCode,

                     SInt16* modifiers);

theControl: A handle to the control in which the mouse-down event occurred.
keyCode: The virtual key code derived from the event structure. This value represents the key pressed or released by the user. It is always the same for a specific physical key on a particular keyboard regardless of which modifier keys were also pressed.
charCode: A particular character derived from the event structure. This value depends on the virtual key code, the state of the modifier keys, and the current 'KCHR' resource.
modifiers: The constant in the modifiers field of the event structure specifying the state of the modifier keys and the mouse button at the time the event was posted.
function result: Returns a value indicating whether or not it allowed or blocked keystrokes; see Key Filter Result Codes .

DISCUSSION

Your key filter function can intercept and change keystrokes destined for a control. Your key filter function can change the keystroke, leave it alone, or block your control definition function from receiving it. For example, an editable text control can use a key filter function to allow only numeric values to be input in its field.

VERSION NOTES

Available with Appearance Manager 1.0 and later.

Key Filter Result Codes

Your key filter function returns these constants to specify whether or not a keystroke is filtered or blocked.



 
enum {

    kControlKeyFilterBlockKey   = 0,

    kControlKeyFilterPassKey    = 1

};

typedef SInt16 ControlKeyFilterResult;

Constant descriptions

kControlKeyFilterBlockKey: The keystroke is blocked and not received by the control.
kControlKeyFilterPassKey: The keystroke is filtered and received by the control.

\xA9 1998 Apple Computer, Inc. – (Last Updated 19 Nov 98)