LowLevelOverview

LowLevelOverview is a sample program that illustrates the minimum code needed to handle key input and lays bare some of the fundamental components of the input system that are usually hidden. Application writers will not use the input system at this level, but might be interested to see the fundamental components of the input system in order to get a general understanding of how it works. For a typical usage example, see the KeyEventsInViews sample.

Running the sample

Execute the binary LowLevelOverviewSApp. Once it is started, activate the CommonPoint window (if it is not already) and start typing. Keyboard codes and the state of the shift and power keys will be echoed to cout. After twenty seconds, the sample will quit.

Files and classes

TKeyClicker is defined in KeyClicker.h and KeyClicker.C. It derives from MEventTarget and MKeyEventHandler, and overrides KeyDown to respond to key events by printing the key code to standard out.

LowLevelOverviewMain.C sets up event handling and derives this sample. This work is usually done by the View System and the Presentation framework.

Notes

In this example, TKeyClicker is intended to respond when a key is pressed on the keyboard. In order for this to happen, several things must occur.

1) The input system must be running, and a TKeyboardDevice must be informed when the state of the hardware keyboard changes. During the boot process, the input server starts and a TKeyboardDevice is registered with it, so this example doesn't have to do this.

2) A TStandardEventReceiver must be created and connected to the input system. The receiver defines an "application" to the input system. In practical terms, this means it can be become and surrender the input focus. Just creating the receiver is not enough, a TEventReceiverHandle must also be created to establish the connection to the server and set up a thread for distribution of input events. The receiver is then set up with input devices (for example, TKeyboardInputDevice) that correspond to the devices registered with the server.

3) An MEventTarget must be registered with the receiver (or a TInteractor with an input device; however, this example does not use interactors). This example creates a class, TKeyClicker, which derives from MEventTarget. RegisterSimpleTarget is used to register it with the receiver. After this happens, when the receiver receives an event from the server, it considers this target as a possible target for dispatching the event.

4) The target must mix in MKeyEventHandler protocol. Not all targets are interested in all events. An event only dispatches to a target if it recognizes the appropriate protocol in the target, and since the target is intended to receive key events, MKeyEventHandler must bemixed in.

5) The subclass of MKeyEventHandler must override protocol of MKeyEventHandler that corresponds to the kinds of key events it wants to handle. MKeyEventHandler has protocol for KeyDown, KeyUp, ModifierKeyDown, and ModifierKeyUp. In this example, only KeyDown is overriden.

And that's it. As long as the TEventReceiverHandle exists, the receiver remains connected to the server. When the handle (and all copies of it) are deleted, the receiver is destroyed and the connection is broken--the application has ceased to exist.

Because events are distributed through the input system thread, you can block your own thread using the call to TSystemClock::DelayFor, and input events are still distributed to TKeyClicker.

The TEventReceiverHandle adopts the receiver, so it is not (and should not be) destroyedupon completion.

If the receiver surrenders the input focus, it stops receiving events until it again becomes the input focus. When the receiver is connected to the server, it becomes the input focus automatically. You'll notice, however, that if you run this sample and then select a window from a different program (and thus a different receiver), this sample surrenders the input focus and you cannot regain it.

Click the icon to mail questions or corrections about this material to Taligent personnel.