KeyInteractors

KeyInteractors is a sample program that illustrates how to use TInteractor to direct events towards a particular MEventTarget and parse the event stream into higher-level operations on that target. The sample introduces TKeyInputInteractor, which examines the input stream for a sequence of key events that match a target string, and then takes special action when that sequence is encountered. TKeyInputView starts the interactor in response to a key event issued with the power key down, and from that point the interactor takes over until it matches, at which point it calls a function on TKeyInputView and restores normal event handling.

This sample also illustrates a common way views that derive from TContentView implement activate/deactivate protocol. The technique used here puts the interactor in charge of informing the view when it wishes to be activated or deactivated by the view.

Running the sample

Execute KeyInteractorsSApp. With the window active, type some text. The key codes display in the view. Hold down the power key and type a key to start the interactor. Continue typing until you type the letters "color". As the interactor matches the keys, it echos the matched portion of the string to cout. Once the interactor is presented with this sequence of keys, it toggles the color of the view and exits. Close the window to quit.

Files and classes:

TKeyInputView is defined in KeyInputView.h and KeyInputView.C. TKeyInputView is much like the view in the KeyEventsInViews sample, with the addition that it overrides activation protocol to pass activation events to the interactor, and it provides Add/RemoveInteractor and ToggleColor protocol for TKeyInputInteractor to use.

TKeyInputInteractor is defined in KeyInputInteractor.h and KeyInputInteractor.C. It derives from TInteractor for interactor protocol and MKeyEventHandler so that it can receive key events. It is created with a string to match, and implements KeyDown to match keys against successive characters in the string. It overrides HandleDeactivate to reset its match state, and calls ToggleColor on the provided TKeyInputView instance when the string is matched.

Notes:

There are two main uses of interactors. One is to parse events into higher-level semantic units; the other is to direct events from a device to a particular target, short-circuiting the normal dispatch logic. (This example attempts to illustrate both, with somewhat mixed success. A MouseInput sample might do a better job.)

In its role as parser, the TInteractor derived class generally has a reference to the object that created it, and calls member functions on that object in response to particular event sequences.

Typically views that derive from TContentView and that create interactors call activate and deactivate on the interactor as they are activated and deactivated. To do this, the view must retain an alias to the interactor. A common error is using this alias to delete the interactor when the interactor is finished. Typically, an interactor is adopted by a device as a root interactor (using TEvent::StartInteractor), and that device deletes it.

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