<?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-B58D3727-6E05-51C8-8EC2-52768A136BD5" xml:lang="en"><title>Window
Server Client-Side Events Overview</title><shortdesc>A client application connects to the Window Server by creating
a Window Server session and calling <codeph>RWsSession::Connect()</codeph>.
Events generated by the Window Server are then delivered to the client via
the session, and the client must handle these events appropriately.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<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
audience</b>: Application developers. </p>
<section id="GUID-BC5A4EC6-12CA-4E35-8E05-3FCDDC2AF8E9"><title>Window server event types</title> <p>The Window Server generates
events of three different classes, as shown in the following diagram. </p> <fig id="GUID-04CE3E9E-2DB3-5771-B00F-532A57A74E5B">
<title>              Window server event types            </title>
<image href="GUID-8D046AD9-1D28-52AE-8B69-2CBF6441F733_d0e190606_href.png" placement="inline"/>
</fig> <table id="GUID-5390256E-7A53-58D4-B698-9AD199182515">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>Class</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>TWsEvent</apiname></xref>  </p> </entry>
<entry><p><xref href="GUID-7AC3477E-09C1-519A-9079-DA969B9FC4D7.dita">General events</xref>,
which represent user input events, such as pointer and key events. You handle
these by using an active object of standard priority. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>TWsRedrawEvent</apiname></xref>  </p> </entry>
<entry><p><xref href="GUID-7750D4BE-9FBA-5D29-806D-B80911170ECD.dita">Redraw events</xref>.
You handle these by using an active object of lower priority. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>TWsPriorityKeyEvent</apiname></xref>  </p> </entry>
<entry><p><xref href="GUID-EF87F8F8-1521-5C50-85A9-94038A99021C.dita">Priority
key events</xref>. You handle these by using an active object of higher priority. </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>All Window Server applications handle standard events, and nearly
all handle redraw events. Only a few, however, handle priority key events.
It is only in very rare cases that an application does not handle redraw events,
because this requires that all its windows are backed-up windows. </p> <p>Events
are always associated with a window. For some event types, such as key events,
this is a window group. For other event types, such as pointer events, it
is a drawable window. The event delivered to the client contains a handle
that can be used to identify the window: this is the handle that was passed
as a parameter when the window was created. For window groups, however, this
is usually unnecessary, because most applications have only one window group. </p> <p>Symbian
recommends that you handle each event class with a separate active object,
in order that the classes can be handled at different priorities. </p> </section>
<section id="GUID-B6D5EAC2-E9C2-4478-B081-F3F516EA9CE1"><title>Handling events</title> <p>The Window Server maintains a server-side
buffer of all events queued to an application—each application has its own
queue within the buffer (this is only for general events—redraw and priority
key events are handled by a different mechanism). Each application must handle
events appropriately. The <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession::GetEvent()</apiname></xref> function
(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
as the first stage of handling a completed request, and the event must then
be analyzed and handled. </p> <p>Each event must be handled relatively quickly
(at most a couple of seconds) so that the application remains responsive to
user input. If an event requires more extended processing (such as a key which
causes a large spreadsheet recalculation), then this processing should be
split into smaller chunks and handled by a client-side active object running
at lower priority than the <codeph>GetEvent()</codeph> handler. </p> <p>An
application which does not observe these protocols will stop running—although
it will not stop the whole device. The Window Server supports hotkeys which
it handles directly, so that a badly behaved application may be killed by
the server. </p> </section>
</conbody><related-links>
<link href="GUID-CD550DE7-D013-527B-BADE-5CB122C352C8.dita"><linktext>Pointer Handling</linktext>
</link>
<link href="GUID-B7FF0B9C-3A17-5AAA-A986-7BA4F44DBD41.dita"><linktext>Declaring
a                 Window Server Event-Handling Class</linktext></link>
<link href="GUID-A51D3749-442A-54E8-8EB5-BF907694CD8C.dita"><linktext>Processing
Window-Group                 Events</linktext></link>
<link href="GUID-E1E11C95-3400-548B-AEEE-577DA8FB9ECB.dita"><linktext>Processing
Window Events</linktext></link>
<link href="GUID-930A3ABD-84FB-5D76-938C-79383273DAE6.dita"><linktext>Processing
System Events</linktext></link>
<link href="GUID-08427065-B8E5-5194-B095-3B5213836BED.dita"><linktext>Window Server
Client-Side Events</linktext></link>
</related-links></concept>