--- a/Symbian3/SDK/Source/GUID-CFC70204-1AD4-5DF0-ADDC-CDE4B39CFF96-GENID-1-8-1-3-1-1-9-1-4-1-6-1.dita	Wed Mar 31 11:11:55 2010 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,106 +0,0 @@
-<?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-GENID-1-8-1-3-1-1-9-1-4-1-6-1" xml:lang="en"><title>Simulating
-and intercepting key events</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<section id="GUID-EC0588AB-A48E-42A8-A149-315B36DBE493-GENID-1-8-1-3-1-1-9-1-4-1-6-1-2-1"><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-GENID-1-8-1-3-1-1-9-1-4-1-6-1-2-2"><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-GENID-1-8-1-3-1-1-9-1-4-1-6-1-2-2-3" 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-GENID-1-8-1-3-1-1-9-1-4-1-6-1-2-2-5" 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-GENID-1-8-1-3-1-1-9-1-4-1-6-1-2-2-7" 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-GENID-1-8-1-3-1-1-9-1-4-1-6-1-2-2-9" 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-GENID-1-8-1-3-1-1-9-1-4-1-6-1-2-2-11" 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-GENID-1-8-1-3-1-1-9-1-4-1-6-1-2-2-13" 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-GENID-1-8-1-3-1-1-9-1-4-1-6-1-2-2-15" 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-GENID-1-8-1-3-1-1-9-1-4-1-6-1-2-2-19" 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>
-</conbody></concept>
\ No newline at end of file