How to write a FEP

Handling the start of a transaction

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.

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 CCoeEnv’s member function ForEachFepObserverCall() (CCoeEnv is defined in epoc32\include\COEMAIN.H), passing in the address of the non-member function FepObserverHandleStartOfTransactionL() (defined in epoc32\include\FEPBASE.H). 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).

Text cursors

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 RWindowGroup’s SetTextCursor() and CancelTextCursor() 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 CTstInsertionPoint in TFEP1 provides an example of this.

Shortcut keys

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.