How to write a FEP

Simple drag events

In order for the FEP control to receive drag events occurring in its window, all that is needed is to call EnableDragEvents() in the control’s construction routine. Having done that, the control will receive drag events as calls to its HandlePointerEventL() virtual function. The iType member of HandlePointerEventL()’s aPointerEvent parameter is set to TPointerEvent::EDrag for drag events.

This method makes heavy use of IPC (inter-process communication) as the user drags the mouse/pen around the FEP control’s window, which means that the FEP does not get drag events at optimum frequency. This may be problematic for something like handwriting recognition software. If there is a requirement to follow the path traced by the mouse/pen as closely as possible, another method can be used, namely buffered drag events.

Buffered drag events

The advantage of buffered drag events over simple drag events is that the window server client can receive multiple mouse/pen positions in a single event, which reduces the IPC overhead. To enable this, the following code needs to be called in the FEP control’s construction routine:

User::LeaveIfError(DrawableWindow()->AllocPointerMoveBuffer(ENumberOfPointsInBuffer, 0));

This assumes that ENumberOfPointsInBuffer has been defined elsewhere; TFEP2Plugin sets this constant to 32. The control then receives drag events as calls to its HandlePointerBufferReadyL() virtual function, rather than as calls to HandlePointerEventL(). To retrieve these drag events, include the following code at the start of the FEP control’s HandlePointerBufferReadyL() function:

TPoint arrayOfPoints[ENumberOfPointsInBuffer];
TPtr8 bufferOfPoints(REINTERPRET_CAST(TUint8*, arrayOfPoints), 0, ENumberOfPointsInBuffer*sizeof(TPoint));
User::LeaveIfError(DrawableWindow()->RetrievePointerMoveBuffer(bufferOfPoints));
const TInt numberOfPointsInBuffer=bufferOfPoints.Length()/sizeof(TPoint);

Having done that, numberOfPointsInBuffer of arrayOfPoints can be used for whatever purpose the FEP requires, for example handwriting recognition. Note that AllocPointerMoveBuffer()’s counterpart FreePointerMoveBuffer() does not need to be called in the FEP control’s destructor as this happens automatically when the control’s window is destroyed.

Intercepting mouse/pen events anywhere on the screen

In order to intercept mouse/pen events anywhere on the screen it is necessary to write a plugin into the window server (WSERV). This is in addition to the FEP plugin which plugs into the FEP architecture. TFEP2plugin provides a working example of this (TFEP2be). The details of how to write a window server plugin DLL are beyond the scope of this document because the APIs involved belong to the window server. See CAnim and CAnimDll in the SDK for information on this. The way mouse/pen events can be intercepted is by returning ETrue from the function overriding MEventHandler::OfferRawEvent() (CAnim derives from MEventHandler). Events which are handled in this way will not be sent to the relevant window server client, in other words, the client who would otherwise have received this event.

The sprite feature of the window server (RWsSprite, defined in epoc32\include\W32STD.H) can be used to display to the user the path on the screen being traced out by their mouse/pen movements. However, care should be taken when using sprites for this purpose. Sprites use bitmaps, which in this context would need to be the size of the screen. Because each running application has its own FEP, which would have its own sprite, which in turn would have its own screen-sized bitmap, it becomes apparent that some optimization must be done to avoid huge amounts of memory being consumed. TFEP2Plugin solves this problem by using a single bitmap shared between each sprite. It uses the 4 byte thread-local storage of the window server plugin DLL to store the identifier of this bitmap. The code which constructs the sprite is protected by a mutex (RMutex, defined in epoc32\include\E32STD.H) as it tests to see if the bitmap to be used by the sprite has already been created by a FEP running the same code in another thread. If it has then it merely calls CFbsBitmap::Duplicate() which simply increments the existing bitmap’s reference count, thus only one large bitmap is created rather than one per running application.

Intercepting mouse/pen events anywhere on the screen is likely to be most useful to handwriting-interpreting FEPs. Given that using this feature involves two polymorphic DLLs (plugging into different frameworks) running in two separate threads in separate processes, there is a choice regarding where the bulk of the FEP’s processing is done. The advantage of the processing being done outside of the window server process (in other words, in the FEP architecture plugin) is that bugs in the processing code (for instance crashing or hanging) do not affect the whole machine. The advantage of the processing being done inside the window server process (in other words, in the window server plugin) is that the long lists of screen positions (tracing out the path of where the user has dragged the mouse/pen) do not need to be communicated between processes.