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.