1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-A7E39E45-02BA-58F4-8807-EFABB8F6E5D0-GENID-1-8-1-3-1-1-9-1-4-1-7-1" xml:lang="en"><title>Processing |
|
13 pen events</title><shortdesc>This topic describes various events processed by Pen or Mouse.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-FB1CCFC8-F70A-4D6E-BF27-3652413359AE-GENID-1-8-1-3-1-1-9-1-4-1-7-1-3-1"><title>Simple drag |
|
15 events</title> <p>In order for the FEP control to receive drag events occurring |
|
16 in its window, all that is needed is to call <codeph>EnableDragEvents()</codeph> in |
|
17 the control’s construction routine. Having done that, the control will receive |
|
18 drag events as calls to its <codeph>HandlePointerEventL()</codeph> virtual |
|
19 function. The <codeph>iType</codeph> member of <codeph>HandlePointerEventL()</codeph> ’s <codeph>aPointerEvent</codeph> parameter |
|
20 is set to <codeph>TPointerEvent::EDrag</codeph> for drag events. </p> <p>This |
|
21 method makes heavy use of IPC (inter-process communication) as the user drags |
|
22 the mouse/pen around the FEP control’s window, which means that the FEP does |
|
23 not get drag events at optimum frequency. This may be problematic for something |
|
24 like handwriting recognition software. If there is a requirement to follow |
|
25 the path traced by the mouse/pen as closely as possible, another method can |
|
26 be used, namely buffered drag events. </p> </section> |
|
27 <section id="GUID-739BD481-1EAF-42B3-B0F0-8C50D01CE488-GENID-1-8-1-3-1-1-9-1-4-1-7-1-3-2"><title>Buffered drag |
|
28 events</title> <p>The advantage of buffered drag events over simple drag events |
|
29 is that the window server client can receive multiple mouse/pen positions |
|
30 in a single event, which reduces the IPC overhead. To enable this, the following |
|
31 code needs to be called in the FEP control’s construction routine: </p> <codeblock id="GUID-3247B04E-05FD-534E-8F8D-C15DE2FEA33C-GENID-1-8-1-3-1-1-9-1-4-1-7-1-3-2-3" xml:space="preserve">User::LeaveIfError(DrawableWindow()->AllocPointerMoveBuffer(ENumberOfPointsInBuffer, 0));</codeblock> <p>This assumes that <codeph>ENumberOfPointsInBuffer</codeph> has been defined |
|
32 elsewhere; TFEP2Plugin sets this constant to 32. The control |
|
33 then receives drag events as calls to its <codeph>HandlePointerBufferReadyL()</codeph> virtual |
|
34 function, rather than as calls to <codeph>HandlePointerEventL()</codeph>. |
|
35 To retrieve these drag events, include the following code at the start of |
|
36 the FEP control’s <codeph>HandlePointerBufferReadyL()</codeph> function: </p> <codeblock id="GUID-18B4F1EB-7090-5C6C-9EB4-98F6CF37FA88-GENID-1-8-1-3-1-1-9-1-4-1-7-1-3-2-5" xml:space="preserve">TPoint arrayOfPoints[ENumberOfPointsInBuffer]; |
|
37 TPtr8 bufferOfPoints(REINTERPRET_CAST(TUint8*, arrayOfPoints), 0, ENumberOfPointsInBuffer*sizeof(TPoint)); |
|
38 User::LeaveIfError(DrawableWindow()->RetrievePointerMoveBuffer(bufferOfPoints)); |
|
39 const TInt numberOfPointsInBuffer=bufferOfPoints.Length()/sizeof(TPoint);</codeblock> <p>Having |
|
40 done that, <codeph>numberOfPointsInBuffer</codeph> of <codeph>arrayOfPoints</codeph> can |
|
41 be used for whatever purpose the FEP requires, for example handwriting recognition. |
|
42 Note that <codeph>AllocPointerMoveBuffer()</codeph> ’s counterpart <codeph>FreePointerMoveBuffer()</codeph> does |
|
43 not need to be called in the FEP control’s destructor as this happens automatically |
|
44 when the control’s window is destroyed. </p></section> |
|
45 <section id="GUID-9E66280C-65AE-4AB1-9F00-65FBE6CF218D-GENID-1-8-1-3-1-1-9-1-4-1-7-1-3-3"><title>Intercepting |
|
46 pen events anywhere on the screen</title> <p>In order to intercept mouse/pen |
|
47 events anywhere on the screen it is necessary to write a plugin into the window |
|
48 server (WSERV). This is in addition to the FEP plugin which plugs into the |
|
49 FEP architecture. TFEP2plugin provides a working example of this (TFEP2be). |
|
50 The details of how to write a window server plugin DLL are beyond the scope |
|
51 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 |
|
52 the SDK for information on this. The way mouse/pen events can be intercepted |
|
53 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 |
|
54 from <xref href="GUID-F1B47E38-4585-3903-93C7-0BCB075465AA.dita"><apiname>MEventHandler</apiname></xref>). Events which are handled in this way |
|
55 will not be sent to the relevant window server client, in other words, the |
|
56 client who would otherwise have received this event. </p> <p>The sprite feature |
|
57 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>) |
|
58 can be used to display to the user the path on the screen being traced out |
|
59 by their mouse/pen movements. However, care should be taken when using sprites |
|
60 for this purpose. Sprites use bitmaps, which in this context would need to |
|
61 be the size of the screen. Because each running application has its own FEP, |
|
62 which would have its own sprite, which in turn would have its own screen-sized |
|
63 bitmap, it becomes apparent that some optimization must be done to avoid huge |
|
64 amounts of memory being consumed. TFEP2Plugin solves this problem by using |
|
65 a single bitmap shared between each sprite. It uses the 4 byte thread-local |
|
66 storage of the window server plugin DLL to store the identifier of this bitmap. |
|
67 The code which constructs the sprite is protected by a mutex (<xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex</apiname></xref>, |
|
68 defined in <filepath>epoc32\include\E32STD.H</filepath>) as it tests to see |
|
69 if the bitmap to be used by the sprite has already been created by a FEP running |
|
70 the same code in another thread. If it has then it merely calls <codeph>CFbsBitmap::Duplicate()</codeph> which |
|
71 simply increments the existing bitmap’s reference count, thus only one large |
|
72 bitmap is created rather than one per running application. </p> <p>Intercepting |
|
73 mouse/pen events anywhere on the screen is likely to be most useful to handwriting-interpreting |
|
74 FEPs. Given that using this feature involves two polymorphic DLLs (plugging |
|
75 into different frameworks) running in two separate threads in separate processes, |
|
76 there is a choice regarding where the bulk of the FEP’s processing is done. |
|
77 The advantage of the processing being done outside of the window server process |
|
78 (in other words, in the FEP architecture plugin) is that bugs in the processing |
|
79 code (for instance crashing or hanging) do not affect the whole machine. The |
|
80 advantage of the processing being done inside the window server process (in |
|
81 other words, in the window server plugin) is that the long lists of screen |
|
82 positions (tracing out the path of where the user has dragged the mouse/pen) |
|
83 do not need to be communicated between processes. </p></section> |
|
84 </conbody></concept> |
|