<?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_d0e213336_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>