<?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-31A28040-6C8E-5C65-A697-04B30B441686-GENID-1-8-1-3-1-1-9-1-4-1-11-1" xml:lang="en"><title>FEP

References</title><shortdesc>This topic introduces miscellaneous guidelines to write a FEP.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-7881D352-F261-4064-8684-6CA76A184257-GENID-1-8-1-3-1-1-9-1-4-1-11-1-3-1"><title> Handling the

start of a transaction</title><p>Although applications do not need to be FEP-aware

in order to work with FEPs, a situation can occur in some applications in

which the user interface can be improved by the application making use of

a FEPBASE API to communicate with the FEP above it, if there is one. </p> <p>If

no FEP is present, the expected behaviour in some UIs when the user presses

a key is for the application to do two things: firstly, it moves focus to

a previously non-focused text editor control (possibly, although not necessarily,

by launching a dialog), and secondly, it 'seeds' that text editor control

with the character associated with that key. If there is a FEP, by default

(in other words, without the application being FEP-aware) the focus change

would only happen when the FEP outputs text to the application. However, if

the FEP is designed to allow the user to compose a fairly large block of text

to send to the application (as would be likely in a Japanese FEP), it would

be better if the focus change occurred when the user starts composing their

text in the FEP. In order for this to happen, the application needs to be

FEP-aware, albeit in a fairly trivial way. The way the FEP notifies the application

that it is starting a transaction is by calling <codeph>CCoeEnv</codeph> ’s

member function <codeph>ForEachFepObserverCall()</codeph> (<codeph>CCoeEnv</codeph> is

defined in <filepath>epoc32\include\COEMAIN.H</filepath>), passing in the

address of the non-member function <codeph>FepObserverHandleStartOfTransactionL()</codeph> (defined

in <filepath>epoc32\include\FEPBASE.H</filepath>). It is important to note

that this function should only be called as the last C++ statement executed

when handling an event. The reason for this that it may take a considerable

amount of time to return (for example, it may launch a dialog and only return

when the dialog has been exited). </p> </section>

<section id="GUID-C32902E0-39A8-493E-9E7F-D48DEE4717CA-GENID-1-8-1-3-1-1-9-1-4-1-11-1-3-2"><title>Text cursors</title><p>If

a non-inline-editing FEP has a composition window into which the user types,

that window should not use a 'real' text cursor (in other words, a cursor

which is set and unset using <codeph>RWindowGroup</codeph> ’s <codeph>SetTextCursor()</codeph> and <codeph>CancelTextCursor()</codeph> member

functions). The reason is that the window server only allows a single text

cursor for the whole system at any one time. If the FEP’s target control is

a text editor, it should use the window server’s text cursor itself, so the

FEP should not use it. To solve this problem, the text cursor in the FEP’s

composition window can be simulated with a sprite. The class <codeph>CTstInsertionPoint</codeph> in

TFEP1 provides an example of this. </p></section>

<section id="GUID-5F7D9BFA-F74A-47FE-B589-A4EF49AFB901-GENID-1-8-1-3-1-1-9-1-4-1-11-1-3-3"><title>Shortcut keys</title><p>As

FEPs get first refusal of all key events, there is a risk that FEPs can intercept

shortcut keys (if the UI supports them) which are intended for the application

to handle. To define a convention for FEP shortcut keys is non-trivial as

different UIs use different modifier keys and have different policies on using

them. Matters are simplified greatly if a product has a dedicated on/off key

for FEPs as this may be used in combination with other keys to carry out different

functions, as well as on its own to turn the FEP on and off. FEP authors should

consult the documentation for their target UI. </p></section>

</conbody></concept>