Window Server Client-Side Events Overview

Window server event types

The Window Server generates events of three different classes, as shown in the following diagram.

Figure 1. Window server event types

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 RWsSession::GetEvent() function (or RWsSession::GetRedraw() or 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.