<?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-A7E39E45-02BA-58F4-8807-EFABB8F6E5D0" xml:lang="en"><title>Processing

pen events</title><shortdesc>This topic describes various events processed by Pen or Mouse.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-FB1CCFC8-F70A-4D6E-BF27-3652413359AE"><title>Simple drag

events</title> <p>In order for the FEP control to receive drag events occurring

in its window, all that is needed is to call <codeph>EnableDragEvents()</codeph> in

the control’s construction routine. Having done that, the control will receive

drag events as calls to its <codeph>HandlePointerEventL()</codeph> virtual

function. The <codeph>iType</codeph> member of <codeph>HandlePointerEventL()</codeph> ’s <codeph>aPointerEvent</codeph> parameter

is set to <codeph>TPointerEvent::EDrag</codeph> for drag events. </p> <p>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. </p> </section>

<section id="GUID-739BD481-1EAF-42B3-B0F0-8C50D01CE488"><title>Buffered drag

events</title> <p>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: </p> <codeblock id="GUID-3247B04E-05FD-534E-8F8D-C15DE2FEA33C" xml:space="preserve">User::LeaveIfError(DrawableWindow()-&gt;AllocPointerMoveBuffer(ENumberOfPointsInBuffer, 0));</codeblock> <p>This assumes that <codeph>ENumberOfPointsInBuffer</codeph> has been defined

elsewhere; TFEP2Plugin sets this constant to 32. The control

then receives drag events as calls to its <codeph>HandlePointerBufferReadyL()</codeph> virtual

function, rather than as calls to <codeph>HandlePointerEventL()</codeph>.

To retrieve these drag events, include the following code at the start of

the FEP control’s <codeph>HandlePointerBufferReadyL()</codeph> function: </p> <codeblock id="GUID-18B4F1EB-7090-5C6C-9EB4-98F6CF37FA88" xml:space="preserve">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);</codeblock> <p>Having

done that, <codeph>numberOfPointsInBuffer</codeph> of <codeph>arrayOfPoints</codeph> can

be used for whatever purpose the FEP requires, for example handwriting recognition.

Note that <codeph>AllocPointerMoveBuffer()</codeph> ’s counterpart <codeph>FreePointerMoveBuffer()</codeph> does

not need to be called in the FEP control’s destructor as this happens automatically

when the control’s window is destroyed. </p></section>

<section id="GUID-9E66280C-65AE-4AB1-9F00-65FBE6CF218D"><title>Intercepting

pen events anywhere on the screen</title> <p>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 <xref href="GUID-029C644B-BE0F-37C6-95E2-D27F974E6AD3.dita"><apiname>CAnim</apiname></xref> and <codeph>CAnimDll</codeph> in

the SDK for information on this. The way mouse/pen events can be intercepted

is by returning <codeph>ETrue</codeph> from the function overriding <codeph>MEventHandler::OfferRawEvent()</codeph> (<xref href="GUID-029C644B-BE0F-37C6-95E2-D27F974E6AD3.dita"><apiname>CAnim</apiname></xref> derives

from <xref href="GUID-F1B47E38-4585-3903-93C7-0BCB075465AA.dita"><apiname>MEventHandler</apiname></xref>). 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. </p> <p>The sprite feature

of the window server (<xref href="GUID-75C09150-E93B-323D-AFBF-E42C7BD78229.dita"><apiname>RWsSprite</apiname></xref>, defined in <filepath>epoc32\include\W32STD.H</filepath>)

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 (<xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex</apiname></xref>,

defined in <filepath>epoc32\include\E32STD.H</filepath>) 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 <codeph>CFbsBitmap::Duplicate()</codeph> which

simply increments the existing bitmap’s reference count, thus only one large

bitmap is created rather than one per running application. </p> <p>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. </p></section>