|
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-B58D3727-6E05-51C8-8EC2-52768A136BD5" xml:lang="en"><title>Window |
|
13 Server Client-Side Events Overview</title><shortdesc>A client application connects to the Window Server by creating |
|
14 a Window Server session and calling <codeph>RWsSession::Connect()</codeph>. |
|
15 Events generated by the Window Server are then delivered to the client via |
|
16 the session, and the client must handle these events appropriately.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
17 <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref> and <xref href="GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita">non-ScreenPlay</xref>. <b>Target |
|
18 audience</b>: Application developers. </p> |
|
19 <section id="GUID-BC5A4EC6-12CA-4E35-8E05-3FCDDC2AF8E9"><title>Window server event types</title> <p>The Window Server generates |
|
20 events of three different classes, as shown in the following diagram. </p> <fig id="GUID-04CE3E9E-2DB3-5771-B00F-532A57A74E5B"> |
|
21 <title> Window server event types </title> |
|
22 <image href="GUID-8D046AD9-1D28-52AE-8B69-2CBF6441F733_d0e195614_href.png" placement="inline"/> |
|
23 </fig> <table id="GUID-5390256E-7A53-58D4-B698-9AD199182515"> |
|
24 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
25 <thead> |
|
26 <row> |
|
27 <entry>Class</entry> |
|
28 <entry>Description</entry> |
|
29 </row> |
|
30 </thead> |
|
31 <tbody> |
|
32 <row> |
|
33 <entry><p> <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>TWsEvent</apiname></xref> </p> </entry> |
|
34 <entry><p><xref href="GUID-7AC3477E-09C1-519A-9079-DA969B9FC4D7.dita">General events</xref>, |
|
35 which represent user input events, such as pointer and key events. You handle |
|
36 these by using an active object of standard priority. </p> </entry> |
|
37 </row> |
|
38 <row> |
|
39 <entry><p> <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>TWsRedrawEvent</apiname></xref> </p> </entry> |
|
40 <entry><p><xref href="GUID-7750D4BE-9FBA-5D29-806D-B80911170ECD.dita">Redraw events</xref>. |
|
41 You handle these by using an active object of lower priority. </p> </entry> |
|
42 </row> |
|
43 <row> |
|
44 <entry><p> <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>TWsPriorityKeyEvent</apiname></xref> </p> </entry> |
|
45 <entry><p><xref href="GUID-EF87F8F8-1521-5C50-85A9-94038A99021C.dita">Priority |
|
46 key events</xref>. You handle these by using an active object of higher priority. </p> </entry> |
|
47 </row> |
|
48 </tbody> |
|
49 </tgroup> |
|
50 </table> <p>All Window Server applications handle standard events, and nearly |
|
51 all handle redraw events. Only a few, however, handle priority key events. |
|
52 It is only in very rare cases that an application does not handle redraw events, |
|
53 because this requires that all its windows are backed-up windows. </p> <p>Events |
|
54 are always associated with a window. For some event types, such as key events, |
|
55 this is a window group. For other event types, such as pointer events, it |
|
56 is a drawable window. The event delivered to the client contains a handle |
|
57 that can be used to identify the window: this is the handle that was passed |
|
58 as a parameter when the window was created. For window groups, however, this |
|
59 is usually unnecessary, because most applications have only one window group. </p> <p>Symbian |
|
60 recommends that you handle each event class with a separate active object, |
|
61 in order that the classes can be handled at different priorities. </p> </section> |
|
62 <section id="GUID-B6D5EAC2-E9C2-4478-B081-F3F516EA9CE1"><title>Handling events</title> <p>The Window Server maintains a server-side |
|
63 buffer of all events queued to an application—each application has its own |
|
64 queue within the buffer (this is only for general events—redraw and priority |
|
65 key events are handled by a different mechanism). Each application must handle |
|
66 events appropriately. The <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession::GetEvent()</apiname></xref> function |
|
67 (or <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession::GetRedraw()</apiname></xref> or <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession::GetPriorityKey()</apiname></xref>) must be called |
|
68 as the first stage of handling a completed request, and the event must then |
|
69 be analyzed and handled. </p> <p>Each event must be handled relatively quickly |
|
70 (at most a couple of seconds) so that the application remains responsive to |
|
71 user input. If an event requires more extended processing (such as a key which |
|
72 causes a large spreadsheet recalculation), then this processing should be |
|
73 split into smaller chunks and handled by a client-side active object running |
|
74 at lower priority than the <codeph>GetEvent()</codeph> handler. </p> <p>An |
|
75 application which does not observe these protocols will stop running—although |
|
76 it will not stop the whole device. The Window Server supports hotkeys which |
|
77 it handles directly, so that a badly behaved application may be killed by |
|
78 the server. </p> </section> |
|
79 </conbody><related-links> |
|
80 <link href="GUID-CD550DE7-D013-527B-BADE-5CB122C352C8.dita"><linktext>Pointer Handling</linktext> |
|
81 </link> |
|
82 <link href="GUID-B7FF0B9C-3A17-5AAA-A986-7BA4F44DBD41.dita"><linktext>Declaring |
|
83 a Window Server Event-Handling Class</linktext></link> |
|
84 <link href="GUID-A51D3749-442A-54E8-8EB5-BF907694CD8C.dita"><linktext>Processing |
|
85 Window-Group Events</linktext></link> |
|
86 <link href="GUID-E1E11C95-3400-548B-AEEE-577DA8FB9ECB.dita"><linktext>Processing |
|
87 Window Events</linktext></link> |
|
88 <link href="GUID-930A3ABD-84FB-5D76-938C-79383273DAE6.dita"><linktext>Processing |
|
89 System Events</linktext></link> |
|
90 <link href="GUID-08427065-B8E5-5194-B095-3B5213836BED.dita"><linktext>Window Server |
|
91 Client-Side Events</linktext></link> |
|
92 </related-links></concept> |