Processing +pen events

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 +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.