IKeyboardHandler

The IKeyboardHandler class processes all types of keyboard events.

Create a handler derived from IKeyboardHandler and attach it to any window whose keyboard events you want to handle. You can do this by calling IHandler::handleEventsFor to pass the window to the keyboard handler.

You can attach IKeyboardHandlers to the following controls:

When the keyboard handler receives a keyboard event, it creates an object of IKeyboardEvent and routes that object to the appropriate IKeyboardHandler virtual function. You can override these virtual functions to supply your own specialized processing of these events.

A keyboard event continues to travel up the owner chain until either a handler stops it or the key is processed by the window itself. As a result, an IKeyboardHandler object should not stop the processing of any key event that it does not specifically process because the key has the potential of being handled by any window in the owner chain, such as the frame window.

The return value from the virtual functions specifies whether the keyboard event is passed on for additional processing, as follows:

true
The keyboard event requires no additional processing. Do not pass it to another handler.
false
Pass the keyboard event to the next handler for additional processing, as follows:
  • If there is another handler for the focus window, pass the keyboard event to the next handler.
  • If this is the last handler for the focus window, call IWindow::defaultProcedure to process the keyboard event. This call might cause the keyboard event to be dispatched to the focus window's owner window.

Note: You cannot attach an IKeyboardHandler to the desktop window because you cannot subclass the desktop window.

AIX Considerations

Some types of key processing, such as peeking at or modifying key input prior to its being stored in a control, are best handled by using the class ITextChangeHandler.

OS/2 Considerations

You can attach IKeyboardHandlers to I3StateCheckBox objects.

Windows Considerations

Some types of key processing, such as peeking at or modifying key input prior to its being stored in a control, are best handled by using the class ITextChangeHandler.


IKeyboardHandler - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


[view class]
~IKeyboardHandler
public:
virtual ~IKeyboardHandler()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IKeyboardHandler
public:
IKeyboardHandler()

Provides the default constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Dispatching

The Open Class Library dispatches events that have been sent or posted to a window to the handlers attached to that window. It does this by calling the event-dispatching function of the handler objects. An IKeyboardHandler object processes only keyboard-related events.


[view class]
dispatchHandlerEvent
protected:
virtual bool dispatchHandlerEvent(IEvent& event)

If a keyboard event is received, this function calls the appropriate virtual function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Processing

A keyboard handler contains event-processing members that you can use to provide application-specific processing for a keyboard event. Override at least one of these virtual functions in a derived class.
Note: Some keyboard events are routed to more than one of these virtual functions.


[view class]
characterKeyPress
protected:
virtual bool characterKeyPress(IKeyboardEvent& event)

Implemented by derived classes to handle character key presses. When using this callback function, you do not have to verify the character code value using IKeyboardEvent::isCharacter. This function can only be called for key-down transitions or if the user holds down a key (IKeyboardEvent::isUpTransition returns false).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations
This message is received after a WM_CHAR message. To handle WM_KEYDOWN use IKeyboardHandler::key.

[view class]
key
protected:
virtual bool key(IKeyboardEvent& event)

Implemented by derived classes to handle any and all unprocessed key events. This function lets you process every keystroke as it is entered as well as key-down and key-up transitions (see IKeyboardEvent::isUpTransition for details).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scanCodeKeyPress
protected:
virtual bool scanCodeKeyPress(IKeyboardEvent& event)

Implemented by derived classes to handle scan code key presses. When using this callback function, you do not have to verify that the event contains a scan code value using IKeyboardEvent::isScanCode. This function can only be called for key-down transitions or if the user holds down a key (IKeyboardEvent::isUpTransition returns false).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
virtualKeyPress
protected:
virtual bool virtualKeyPress(IKeyboardEvent& event)

Implemented by derived classes to handle virtual key presses. When using this callback function, you do not have to verify that the event contains a virtual key value using IKeyboardEvent::isVirtual. This function can only be called for key-down transitions or if the user holds down a key (IKeyboardEvent::isUpTransition returns false).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations
This message is received after a WM_CHAR message. To handle WM_KEYDOWN use IKeyboardHandler::key.


IKeyboardHandler - Inherited Member Functions and Data

Inherited Public Functions

IHandler

Inherited Public Data

Inherited Protected Functions

IHandler

Inherited Protected Data