General events

All events generated by the window server, except redraw events and priority key events, are delivered to the client in a TWsEvent which is requested asynchronously by the RWsSession::EventReady() function. When this request completes, it is handled by an active object CActive::RunL() function which must use RWsSession::GetEvent() to get the TWsEvent representing the event. The TWsEvent::Type() function is used to identify the event type which can then retrieve the appropriate type of data.

The following table lists for each event type returned by TWsEvent::Type(), what object TWsEvent::EventData() returns, and what the TWsEvent::Handle() represents.

TWsEvent::Type()	TWsEvent::EventData()	TWsEvent::Handle()
EEventNull	n/a	n/a
EEventKey	TKeyEvent	RWindowGroup client handle
EEventKeyUp	TKeyEvent	RWindowGroup client handle
EEventKeyDown	TKeyEvent	RWindowGroup client handle
EEventModifiersChanged	TModifiersChangedEvent	The client handle of the RWindowTreeNode on which RWindowTreeNode::EnableModifierChangedEvents() was called.
EEventPointer	TPointerEvent	RWindow client handle
EEventPointerEnter	TPointerEvent	RWindow client handle
EEventPointerExit	TPointerEvent	RWindow client handle
EEventPointerBufferReady	None - call RWindowBase::RetrievePointerMoveBuffer()	RWindow client handle
EEventDragDrop	TPointerEvent	RWindow client handle
EEventFocusLost	None	RWindowGroup client handle
EEventFocusGained	None	RWindowGroup client handle
EEventSwitchOn	None	The client handle of the RWindowTreeNode on which RWindowTreeNode::EnableOnEvents() was called.
EEventPassword	None	The client handle of the RWindowGroup of the window on which RWindowBase::PasswordWindow() was called.
EEventWindowGroupsChanged	None	The client handle of the RWindowTreeNode on which RWindowTreeNode::EnableGroupChangeEvents() was called.
EEventErrorMessage	TWsErrorMessage	The client handle of the RWindowTreeNode on which RWindowTreeNode::EnableErrorMessages() was called.
EEventMessageReady	None	RWindowGroup client handle
EEventMarkInvalid	n/a	n/a
EEventSwitchOff	None	The client handle of the RWindowTreeNode passed into RWsSession::RequestOffEvents().
EEventKeySwitchOff	None	The client handle of the RWindowTreeNode passed into RWsSession::RequestOffEvents().
EEventScreenDeviceChanged	None	The client handle of the object on which RWindowGroup::EnableScreenChangeEvents() was called.
EEventFocusGroupChanged	None	The client handle of the RWindowTreeNode on which RWindowTreeNode::EnableFocusChangeEvents() was called.
EEventCaseOpened	None	The client handle of the RWindowTreeNode on which RWindowTreeNode::EnableOnEvents() was called.
EEventCaseClosed	None	The client handle of the RWindowTreeNode passed into RWsSession::RequestOffEvents().
EEventWindowGroupListChanged	None	The client handle of the RWindowTreeNode on which RWindowTreeNode::EnableGroupListChangeEvents() was called.
EEventKeyRepeat	n/a (only sent to the key click plug-in interface)	n/a
EEventUser	n/a	n/a

Event types may be grouped as follows:

• those relating to the system, e.g. switch-on

  see How to process system-related events

• those relating to a window group, e.g. focus lost or gained, key code, key up or down

  see How to process window-group related events

• those relating to a window, e.g. a pointer event

  For this type of event the TWsEvent::Handle() function may be used to identify the window. Each window, when created by the client, is given a handle which the client uses to identify the window associated with a particular event.

  see How to process window-related events

Certain event types are not automatically delivered to the window server session: if they are required they must be explicitly requested by a window. The window server session will then receive the events, with a handle to the window that requested them, and the handle can be used to invoke a member function of the window that requested the events. Events that must be requested in this way are of the following types:

• on events, e.g. when the machine is powered up, either by pressing the On key, opening the case, touching the screen or an alarm going off

  Use RWindowTreeNode::EnableOnEvents() to instruct the server to report system switch on events to this window.

• window group changed events

  Use RWindowTreeNode::EnableGroupChangeEvents() to instruct the window server to report group-change events to this window. These events will typically be of interest to a shell or similar application, for example to notify it that it should update its list of running applications

• modifier changed events, i.e. when one of the modifier keys is pressed or released

  Use RWindowTreeNode::EnableModifierChangedEvents() to instruct the window server to report modifier changed events to this window. Values for the modifier keys are defined in TEventModifier.

• focus changed events

  Use RWindowTreeNode::EnableFocusChangeEvents() to instruct the window server to report when the window group with focus changes.

• error message events, e.g. out of memory messages

  use RWindowTreeNode::EnableErrorMessages() to instruct the window server to report error message events.

If several windows associated with a window server session request notification of the same event, then the event is notified separately to all windows which requested it.

Events of type EEventScreenDeviceChanged are issued if the screen size mode changes. Such events are sent, for example, when the cover on a phone that supports screen flipping is opened or closed. Use RWindowGroup::EnableScreenChangeEvents() to instruct the window server to report screen change events to a window group.