<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-CFC70204-1AD4-5DF0-ADDC-CDE4B39CFF96" xml:lang="en"><title>Simulating

and intercepting key events</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-EC0588AB-A48E-42A8-A149-315B36DBE493"><title>Simulating

key events</title> <p>Simulating key events is done by calling <xref href="GUID-ADAA039A-7BF3-3B06-8486-2E3604C2633D.dita"><apiname>CCoeFep</apiname></xref> ’s

member function <codeph>SimulateKeyEventsL()</codeph>; this sends to the application

a key event for each of the items in the array passed to it. There are two

overloads of <codeph>SimulateKeyEventsL()</codeph>: 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 <filepath>epoc32\include\E32KEYS.H</filepath> defines

the various modifiers possible. The FEP author needs to derive from <codeph>CCoeFep::MModifiedCharacter</codeph> in

order to use the second overload of <codeph>SimulateKeyEventsL()</codeph>,

implementing all three of its pure virtual functions. The <codeph>ModifierMask()</codeph> function

returns the modifiers whose value the FEP wishes to specify; the values for

the modifiers are returned by the <codeph>ModifierValues()</codeph> function. <codeph>ModifierValues()</codeph> should

not return values for any modifiers that are not also returned by <codeph>ModifierMask()</codeph>. </p> <p>For

example, supposing a FEP wishes to send a key event to an application with

the <userinput>func</userinput> modifier on and the <userinput>shift</userinput> modifier

off. In this case the <codeph>ModifierMask()</codeph> function would return <codeph>EModifierFunc|EModifierShift</codeph> and

the <codeph>ModifierValues()</codeph> function would return <codeph>EModifierFunc</codeph>.

The resulting key event received by the application would then have the <codeph>EModifierFunc</codeph> modifier

on and the <codeph>EModifierShift</codeph> 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 <codeph>ModifierMask()</codeph> function, will

reflect the current state of the keyboard. </p> </section>

<section id="GUID-1B15C661-851B-5922-B8BC-7A772232DBD2"><title>Intercepting

key events</title> <p>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: </p> <codeblock id="GUID-1734E8DC-BB49-5EB9-B373-F8B4A8B92809" xml:space="preserve">STATIC_CAST(CCoeAppUi*, iCoeEnv-&gt;AppUi())-&gt;AddToStackL(this, ECoeStackPriorityFep, ECoeStackFlagRefusesFocus|ECoeStackFlagSharable);</codeblock> <p>and the following code in its destructor: </p> <codeblock id="GUID-D5BF8AAB-6BEA-5CF5-AE66-488CC2C44654" xml:space="preserve">STATIC_CAST(CCoeAppUi*, iCoeEnv-&gt;AppUi())-&gt;RemoveFromStack(this);</codeblock> <p>Passing the flag <codeph>ECoeStackFlagSharable</codeph> to <codeph>AddToStackL()</codeph> 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 <codeph>ECoeStackFlagRefusesFocus</codeph> flag

should be passed to <codeph>AddToStackL()</codeph> because FEPs in general

should not “steal” focus from the target underneath them. For the same reason, <codeph>SetNonFocusing()</codeph> (a

member function of <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref>) 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: </p> <codeblock id="GUID-183A9459-B8F1-5D7F-897E-3B5278B8BEE1" xml:space="preserve">CCoeAppUi&amp; appUi=*STATIC_CAST(CCoeAppUi*, iCoeEnv-&gt;AppUi());

appUi.UpdateStackedControlFlags(this, 0, ECoeStackFlagRefusesFocus);

appUi.HandleStackChanged();

</codeblock> <p>The following code causes the FEP’s control to revert to normal

operation by losing focus: </p> <codeblock id="GUID-D5C24301-9D84-5D62-9E75-4B17892316B2" xml:space="preserve">CCoeAppUi&amp; appUi=*STATIC_CAST(CCoeAppUi*, iCoeEnv-&gt;AppUi());

appUi.UpdateStackedControlFlags(this, ECoeStackFlagRefusesFocus, ECoeStackFlagRefusesFocus);

appUi.HandleStackChanged();

</codeblock> <p>Adding the FEP’s control to the control stack at priority <codeph>ECoeStackPriorityFep</codeph> means

that it gets first refusal of all key events. The UI framework offers key

events to the FEP control by calling its <codeph>OfferKeyEventL()</codeph> 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 <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref>, is: </p> <codeblock id="GUID-7823A4B2-AC86-502E-8609-9277F748C64F" xml:space="preserve">TKeyResponse OfferKeyEventL(const TKeyEvent&amp; aKeyEvent, TEventCode aType);</codeblock> <p>The first thing that should be done at the start of <codeph>OfferKeyEventL()</codeph> is

to call either of the two macros below, both of which are defined in <filepath>epoc32\include\FEPBASE.H</filepath>: </p> <codeblock id="GUID-84B500B8-7B35-5E6D-8C54-77AA59C4FCD7" xml:space="preserve">#define FEP_START_KEY_EVENT_HANDLER_L(aFep, aKeyEvent, aEventCode)

#define FEP_START_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L(aFep, aKeyEvent, aEventCode)

</codeblock> <p>The <codeph>aFep</codeph> parameter must be a <xref href="GUID-ADAA039A-7BF3-3B06-8486-2E3604C2633D.dita"><apiname>CCoeFep</apiname></xref> object.

Note that it should not be a pointer to a <xref href="GUID-ADAA039A-7BF3-3B06-8486-2E3604C2633D.dita"><apiname>CCoeFep</apiname></xref>. The <codeph>aKeyEvent</codeph> and

the <codeph>aEventCode</codeph> parameters should be respectively the <xref href="GUID-0F8FA6A3-F172-36E4-9CF5-60814ABCD562.dita"><apiname>TKeyEvent</apiname></xref> and

the <xref href="GUID-420348F5-4A82-3780-9D27-A3E1F4780F0B.dita"><apiname>TEventCode</apiname></xref> parameters of the <codeph>OfferKeyEventL()</codeph> function

itself. The <codeph>OfferKeyEventL()</codeph> function should only be returned

from by calling either of the following two macros (these are also defined

in <filepath>epoc32\include\FEPBASE.H</filepath>): </p> <codeblock id="GUID-AE03275F-FBD7-52AF-B7CC-C6F6707B9FDC" xml:space="preserve">#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)

</codeblock> <p>Both of these two macros contain a <codeph>return</codeph> statement,

so the <codeph>return</codeph> C++ keyword should not occur in the <codeph>OfferKeyEventL()</codeph> function

at all. Note that the macro used at the start of the <codeph>OfferKeyEventL()</codeph> function

should match the macro used to return from it; in other words, both should

be of the <i>no-down-up-filter</i> type or neither should be. The <i>no-down-up-filter</i> variants

should be used if the FEP wishes to handle <codeph>EEventKeyDown</codeph> or <codeph>EEventKeyUp</codeph> events.

This is likely to be rare, however; most FEPs are probably only interested

in <codeph>EEventKey</codeph> events, in which case <codeph>FEP_START_KEY_EVENT_HANDLER_L</codeph> and <codeph>FEP_END_KEY_EVENT_HANDLER_L</codeph> should be used. These variants filter out <codeph>EEventKeyDown</codeph> and <codeph>EEventKeyUp</codeph> events

so that the FEP only receives <codeph>EEventKey</codeph> events. </p> <p>The

first three parameters of the <codeph>FEP_END_KEY_EVENT_HANDLER_</codeph> <i>XXX</i> macros

are the same as for the <codeph>FEP_START_KEY_EVENT_HANDLER_</codeph> <i>XXX</i> macros.

The fourth parameter should be a <xref href="GUID-2AE56EA4-C71E-33FA-8FCE-D2D15453CD10.dita"><apiname>TKeyResponse</apiname></xref> value (an

enum defined in <filepath>epoc32\include\COEDEF.H</filepath>). Specifying <codeph>EKeyWasNotConsumed</codeph> as

this fourth parameter allows that key event to 'fall through' to the application,

whereas specifying <codeph>EKeyWasConsumed</codeph> 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. </p> <p>For

a FEP running over an OPL application, the <codeph>OfferKeyEventL()</codeph> virtual

function declared in <xref href="GUID-ADAA039A-7BF3-3B06-8486-2E3604C2633D.dita"><apiname>CCoeFep</apiname></xref> will get called. This is a

completely independent function from <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref> ’s virtual

function of the same name, and it has a different signature which is as follows: </p> <codeblock id="GUID-6760C373-FB46-53E5-96ED-A8273126B060" xml:space="preserve">void OfferKeyEventL(TEventResponse&amp; aEventResponse, const TKeyEvent&amp; aKeyEvent, TEventCode aEventCode);</codeblock> <p>This virtual function should be implemented in exactly the same way as <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref> ’s <codeph>OfferKeyEventL()</codeph>,

the meaning of the <codeph>aKeyEvent</codeph> and <codeph>aEventCode</codeph> parameters

being the same as for <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref> ’s <codeph>OfferKeyEventL()</codeph>.

The <codeph>aEventResponse</codeph> parameter should be set by the function

overriding <codeph>CCoeFep::OfferKeyEventL()</codeph> to either <codeph>CCoeFep::EEventWasNotConsumed</codeph> or <codeph>CCoeFep::EEventWasConsumed</codeph>, and this must be done before any function that can leave is called. </p> </section>