Window Server Client-Side Events Overview
A client application connects to the Window Server by creating
a Window Server session and calling RWsSession::Connect().
Events generated by the Window Server are then delivered to the client via
the session, and the client must handle these events appropriately.
Variant: ScreenPlay and non-ScreenPlay. Target audience: Application developers.
Window server event types
The Window Server generates events of three different classes, as shown in the following diagram.
Figure: Window server event types
| Class | Description |
|---|---|
[[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWsSession']]] |
General events, which represent user input events, such as pointer and key events. You handle these by using an active object of standard priority. |
[[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWsSession']]] |
Redraw events. You handle these by using an active object of lower priority. |
[[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWsSession']]] |
Priority key events. You handle these by using an active object of higher priority. |
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.
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.
Symbian recommends that you handle each event class with a separate active object, in order that the classes can be handled at different priorities.
Handling events
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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWsSession']]]RWsSession::GetEvent() function
(or [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWsSession']]]RWsSession::GetRedraw() or [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWsSession']]]RWsSession::GetPriorityKey()) must be called
as the first stage of handling a completed request, and the event must then
be analyzed and handled.
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 GetEvent() handler.
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.