Simulating +and intercepting key events

Simulating +key events

Simulating key events is done by calling CCoeFep ’s +member function SimulateKeyEventsL(); this sends to the application +a key event for each of the items in the array passed to it. There are two +overloads of SimulateKeyEventsL(): in the first and most +commonly used overload, only the character codes of the key events are specified; +in the second overload, modifier keys can also be specified for each key event +to be simulated. The header file epoc32\include\E32KEYS.H defines +the various modifiers possible. The FEP author needs to derive from CCoeFep::MModifiedCharacter in +order to use the second overload of SimulateKeyEventsL(), +implementing all three of its pure virtual functions. The ModifierMask() function +returns the modifiers whose value the FEP wishes to specify; the values for +the modifiers are returned by the ModifierValues() function. ModifierValues() should +not return values for any modifiers that are not also returned by ModifierMask().

For +example, supposing a FEP wishes to send a key event to an application with +the func modifier on and the shift modifier +off. In this case the ModifierMask() function would return EModifierFunc|EModifierShift and +the ModifierValues() function would return EModifierFunc. +The resulting key event received by the application would then have the EModifierFunc modifier +on and the EModifierShift modifier off (even if the shift +key is being pressed down). All the other modifiers in the key event, since +they were not returned in the ModifierMask() function, will +reflect the current state of the keyboard.

Intercepting +key events

In order for a FEP to intercept key events before they +reach the application beneath them, the FEP control must be added to the control +stack at a high priority. This is done by using the following code in the +control’s construction routine:

STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->AddToStackL(this, ECoeStackPriorityFep, ECoeStackFlagRefusesFocus|ECoeStackFlagSharable);

and the following code in its destructor:

STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->RemoveFromStack(this);

Passing the flag ECoeStackFlagSharable to AddToStackL() ensures +that if an embedded object is edited from an application, for instance an +embedded drawing is edited inside a word processor document, the FEP’s control +will also be put onto the child application’s control stack when the child +application is started. More importantly, the ECoeStackFlagRefusesFocus flag +should be passed to AddToStackL() because FEPs in general +should not “steal” focus from the target underneath them. For the same reason, SetNonFocusing() (a +member function of CCoeControl) should be called in the +control’s construction routine to prevent mouse or pen events from giving +it focus. On some occasions it may be legitimate for the FEP to take the focus, +for instance if the FEP has a floating window and it is temporarily in a mode +where the user can move this window around the screen by using the arrow keys. +In this case, the FEP’s control can take the focus by calling:

CCoeAppUi& appUi=*STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi()); +appUi.UpdateStackedControlFlags(this, 0, ECoeStackFlagRefusesFocus); +appUi.HandleStackChanged(); +

The following code causes the FEP’s control to revert to normal +operation by losing focus:

CCoeAppUi& appUi=*STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi()); +appUi.UpdateStackedControlFlags(this, ECoeStackFlagRefusesFocus, ECoeStackFlagRefusesFocus); +appUi.HandleStackChanged(); +

Adding the FEP’s control to the control stack at priority ECoeStackPriorityFep means +that it gets first refusal of all key events. The UI framework offers key +events to the FEP control by calling its OfferKeyEventL() virtual +function (although key events for a FEP over an OPL application follow a different +route, described below). The signature of this virtual function, which is +first declared in CCoeControl, is:

TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType);

The first thing that should be done at the start of OfferKeyEventL() is +to call either of the two macros below, both of which are defined in epoc32\include\FEPBASE.H:

#define FEP_START_KEY_EVENT_HANDLER_L(aFep, aKeyEvent, aEventCode) +#define FEP_START_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L(aFep, aKeyEvent, aEventCode) +

The aFep parameter must be a CCoeFep object. +Note that it should not be a pointer to a CCoeFep. The aKeyEvent and +the aEventCode parameters should be respectively the TKeyEvent and +the TEventCode parameters of the OfferKeyEventL() function +itself. The OfferKeyEventL() function should only be returned +from by calling either of the following two macros (these are also defined +in epoc32\include\FEPBASE.H):

#define FEP_END_KEY_EVENT_HANDLER_L(aFep, aKeyEvent, aKeyResponse) +#define FEP_END_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L(aFep, aKeyEvent, aEventCode, aKeyResponse) +

Both of these two macros contain a return statement, +so the return C++ keyword should not occur in the OfferKeyEventL() function +at all. Note that the macro used at the start of the OfferKeyEventL() function +should match the macro used to return from it; in other words, both should +be of the no-down-up-filter type or neither should be. The no-down-up-filter variants +should be used if the FEP wishes to handle EEventKeyDown or EEventKeyUp events. +This is likely to be rare, however; most FEPs are probably only interested +in EEventKey events, in which case FEP_START_KEY_EVENT_HANDLER_L and FEP_END_KEY_EVENT_HANDLER_L should be used. These variants filter out EEventKeyDown and EEventKeyUp events +so that the FEP only receives EEventKey events.

The +first three parameters of the FEP_END_KEY_EVENT_HANDLER_ XXX macros +are the same as for the FEP_START_KEY_EVENT_HANDLER_ XXX macros. +The fourth parameter should be a TKeyResponse value (an +enum defined in epoc32\include\COEDEF.H). Specifying EKeyWasNotConsumed as +this fourth parameter allows that key event to 'fall through' to the application, +whereas specifying EKeyWasConsumed prevents the application +from receiving that event. A good rule of thumb for a FEP that takes key events +as its input is to intercept as few key events as possible when not inside +a FEP transaction, but once inside a transaction to block all key events from +getting through to the application. A transaction may be defined as the composition +and abandoning/committing of a piece of text ('committing' means sending it +on to the application). For a Japanese FEP, that piece of text may be an entire +sentence, whereas for a Chinese FEP it may be just one or two characters.

For +a FEP running over an OPL application, the OfferKeyEventL() virtual +function declared in CCoeFep will get called. This is a +completely independent function from CCoeControl ’s virtual +function of the same name, and it has a different signature which is as follows:

void OfferKeyEventL(TEventResponse& aEventResponse, const TKeyEvent& aKeyEvent, TEventCode aEventCode);

This virtual function should be implemented in exactly the same way as CCoeControl ’s OfferKeyEventL(), +the meaning of the aKeyEvent and aEventCode parameters +being the same as for CCoeControl ’s OfferKeyEventL(). +The aEventResponse parameter should be set by the function +overriding CCoeFep::OfferKeyEventL() to either CCoeFep::EEventWasNotConsumed or CCoeFep::EEventWasConsumed, and this must be done before any function that can leave is called.