![[Index]](../../../../_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../_stock/btn_next_wt.gif){kind=small}
|
|
|
|
|
|
Location:
W32STD.H
Link against: ws32.lib
class RWsSession : public MWsClientClass, public RSessionBase;
Window server session.
The session between the client and the window server can be used to mediate asynchronous events, for client interface control and for system control. A description of each of these capabilities is given below.
Mediating asynchronous events:
Primarily, the session mediates asynchronous events to the user. Three event streams are available: the standard event stream which all applications must use; the redraw event stream which must be used by all applications except those which exclusively use backed-up windows; and the priority key event stream which may be used for abort keys and the like for specialist applications.
All these events are mediated as standard asynchronous services. Typical window server client programs encapsulate each service they require in an active object whose RunL() identifies the event and calls the appropriate member function of a class associated with an application framework, or a window.
Client interface control:
The client's interface with the window server has several aspects, each of which is controlled through the window server session.
Flushing defines how requests to the window server are handled.
System control:
Many system-wide settings may be controlled through the window server session. Typically, these functions are only used by the system shell and its associated sessions/applications. They include: auto-repeat and double-click, querying all window groups in the system, setting the default shadow vector, setting the system pointer cursors, counting resources used by the window server (this is only useful for debugging checks), getting and setting the state of the modifier keys (for instance Shift and Ctrl), and setting the window server background colour.
RHandleBase - A handle to an objectRSessionBase - Client-side handle to a session with a serverMWsClientClass - Base class for all classes whose objects are clients of the window serverRWsSession - Window server sessionDefined in RWsSession:
ClaimSystemPointerCursorList(), ClearAllRedrawStores(), ClearDefaultSystemPointerCursor(), ClearHotKeys(), ClearSystemPointerCursor(), Close(), ComputeMode(), Connect(), Connect(), ECustomTextCursorAlignBaseline, ECustomTextCursorAlignBottom, ECustomTextCursorAlignTop, ELoggingDisable, ELoggingEnable, ELoggingHeapDump, ELoggingStatusDump, EPriorityControlComputeOff, EPriorityControlComputeOn, EPriorityControlDisabled, ESystemInfoArraySize, EventReady(), EventReadyCancel(), FetchMessage(), FindWindowGroupIdentifier(), FindWindowGroupIdentifier(), Flush(), FreeSystemPointerCursorList(), GetBackgroundColor(), GetColorModeList(), GetDefModeMaxNumColors(), GetDefaultOwningWindow(), GetDoubleClickSettings(), GetEvent(), GetFocusScreen(), GetFocusWindowGroup(), GetKeyboardRepeatRate(), GetModifierState(), GetPriorityKey(), GetRedraw(), GetWindowGroupClientThreadId(), GetWindowGroupHandle(), GetWindowGroupNameFromIdentifier(), GetWindowGroupOrdinalPriority(), HeapCount(), HeapSetFail(), LogCommand(), LogMessage(), NumWindowGroups(), NumWindowGroups(), PasswordEntered(), PointerCursorArea(), PointerCursorArea(), PointerCursorMode(), PointerCursorPosition(), PriorityKeyReady(), PriorityKeyReadyCancel(), PurgePointerEvents(), RWsSession(), RedrawReady(), RedrawReadyCancel(), RequestOffEvents(), ResourceCount(), RestoreDefaultHotKey(), SendEventToAllWindowGroups(), SendEventToAllWindowGroups(), SendEventToOneWindowGroupsPerClient(), SendEventToWindowGroup(), SendMessageToAllWindowGroups(), SendMessageToAllWindowGroups(), SendMessageToWindowGroup(), SetAutoFlush(), SetBackgroundColor(), SetBufferSizeL(), SetClientCursorMode(), SetCustomTextCursor(), SetDefaultSystemPointerCursor(), SetDoubleClick(), SetFocusScreen(), SetHotKey(), SetKeyboardRepeatRate(), SetMaxBufferSizeL(), SetModifierState(), SetPointerCursorArea(), SetPointerCursorMode(), SetPointerCursorPosition(), SetShadowVector(), SetSystemFaded(), SetSystemFaded(), SetSystemPointerCursor(), SetWindowGroupOrdinalPosition(), ShadowVector(), TComputeMode, TCustomTextCursorAlignment, TLoggingCommand, TWindowGroupChainInfo, Version(), WindowGroupList(), WindowGroupList(), WindowGroupList(), WindowGroupList(), anonymous
Inherited from MWsClientClass:
WsHandle()
Inherited from RHandleBase:
Attributes(),
Duplicate(),
FullName(),
Handle(),
HandleInfo(),
Name(),
SetHandle(),
SetHandleNC(),
iHandle
Inherited from RSessionBase:
CreateSession(),
EAutoAttach,
EExplicitAttach,
Open(),
Send(),
SendReceive(),
SetReturnedHandle(),
ShareAuto(),
ShareProtected(),
TAttachMode
IMPORT_C RWsSession();
Default C++ constructor.
Constructs an uninitialised window server session. Note that it does not establish a connection to the window server - this must be done explicitly by calling the session's Connect() function. Before Connect() is called, no corresponding session object exists in the server, and the RWsSession contains no meaningful handle.
|
IMPORT_C TInt Connect();
Connects the client session to the window server.
Connect() should be the first function called on an RWsSession object after it is created. The function establishes a connection to the window server, creating a corresponding session object in the server. Each session has one and only one connection to the server. Attempting to call Connect() when a connection has already been made will cause a panic.
After a connection has been successfully established, all events are delivered to the client application through the RWsSession object.
|
IMPORT_C TInt Connect(RFs &aFileServer);
Connects the client session to the window server using pre constructed file server session.
Connect() should be the first function called on an RWsSession object after it is created. The function establishes a connection to the window server, creating a corresponding session object in the server. Each session has one and only one connection to the server. Attempting to call Connect() when a connection has already been made will cause a panic.
After a connection has been successfully established, all events are delivered to the client application through the RWsSession object.
|
|
IMPORT_C void Close();
Closes the window server session.
This function cleans up all resources in the RWsSession and disconnects it from the server. Prior to disconnecting from the window server, the client-side window server buffer is destroyed without being flushed. This function should be called when the RWsSession is no longer needed - normally just before it is destroyed.
IMPORT_C TVersion Version();
Gets the window server version.
|
| Capability: | SwEvent |
IMPORT_C TInt SetHotKey(THotKey aType, TUint aKeyCode, TUint aModifierMask, TUint aModifier);
Sets the hot keys.
Hot keys allow standard functions to be performed by application-defined key combinations.
This function maps any key press (with optional modifiers) to one of the hot keys defined in THotKey. More than one key combination may be mapped to each hot key: a new mapping is added each time the function is called.
Modifier key states are defined in TEventModifier. The modifiers that you want to be in a particular state should be specified in aModifierMask and the ones of these you want to be set should be specified in aModifiers. For example, if you want to capture FN-A and you want the SHIFT modifier unset, but you don't care about the state of the other modifiers then set both the flags for SHIFT and FN in aModiferMask and only set FN in aModifiers.
Note: default hotkey settings exist, but this function can be used for customisation. Typically it might be be used by a shell application or other application that controls system-wide settings.
This function always causes a flush of the window server buffer.
|
|
| Capability: | SwEvent |
IMPORT_C TInt ClearHotKeys(THotKey aType);
Clears all mappings for the specified hotkey, including the default mapping.
Hotkeys allow standard functions to be performed by application-defined key combinations.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt RestoreDefaultHotKey(THotKey aType);
Restores the default mapping for a hot key.
The function clears current mappings for a hot key and restores the default mapping. See THotKey for the default.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C void EventReady(TRequestStatus *aStat);
Requests standard events from the window server.
Standard events include all events except redraws and priority key events.
The client application will typically handle the completed request using the RunL() function of an active object, and in this case the request status aStat should be the iStatus member of that CActive object.
Notes:
The active object runs when an event is waiting. You should call GetEvent() in the RunL() function to get the event.
You should not call this function again until you've either called GetEvent() or EventReadyCancel().
|
IMPORT_C void EventReadyCancel();
Cancels a request for standard events from the window server.
This request was made using EventReady().
The client application will typically use an active object to handle standard events, and this function should be called from the active object's DoCancel() function.
This function always causes a flush of the window server buffer.
IMPORT_C void GetEvent(TWsEvent &aEvent);
Gets a standard event from the session for processing.
The type of event returned by GetEvent() may be any of those listed in TEventCode. To access the data within an event, the event should be converted to the appropriate type, using functions provided by the TWsEvent class. TWsEvent also provides a function to find out the type of the event.
Notes:
It is possible that the returned event is of type EEventNull. Clients should normally ignore these events.
This function should only be called in response to notification that an event has occurred, otherwise the client will be panicked.
This function would normally be called in the RunL() function of an active object which completes with the EventReady() function's request status.
This function always causes a flush of the window server buffer.
|
IMPORT_C void PurgePointerEvents();
Removes all pointer events waiting to be delivered to this session.
The events are removed from the event queue without being processed. This might occur, for example, at application startup.
IMPORT_C void RedrawReady(TRequestStatus *aStat);
Requests redraw events from the window server.
Typically, a client will create an active object for redraw events with a lower priority than the active objects for standard events. The client will then typically handle completed redraw requests in the active object's RunL() function.
As in EventReady(), the request status aStat should be used as the iStatus member of an active object. When a redraw event occurs the active object's RunL() function is called. The redraw event can be obtained by calling GetRedraw() in the RunL().
Note: you should not call this function again until you've either called GetRedraw() or RedrawReadyCancel().
|
IMPORT_C void RedrawReadyCancel();
Cancels a redraw event request.
If active objects are used, this function should be called from the active object's DoCancel() function.
This function always causes a flush of the window server buffer.
IMPORT_C void GetRedraw(TWsRedrawEvent &aEvent);
Gets the redraw event from the session.
This function is similar to GetEvent(), except that the event is returned as a TWsRedrawEvent, and hence there is no need to convert it from a TWsEvent.
The function should only be called after notification that a redraw is waiting.
It always causes a flush of the window server buffer.
|
IMPORT_C void PriorityKeyReady(TRequestStatus *aStat);
Requests priority key events from the window server.
Typically, an client will create an active object for priority key events with a higher priority than the active objects for standard events. The client will then normally handle completed priority key requests in the active object's RunL() function.
As in EventReady(), the request status argument should be the set to the iStatus member of CActive. When priority key events occur, they are obtained using GetPriorityKey().
Note: you should not call this function again until you've either called GetPriorityKey() or PriorityKeyReadyCancel().
|
IMPORT_C void PriorityKeyReadyCancel();
Cancels a priority key event request.
If active objects are used, this function should be called from the active object's DoCancel() function.
This function always causes a flush of the window server buffer.
IMPORT_C void GetPriorityKey(TWsPriorityKeyEvent &aEvent);
Gets the completed priority key event from the window server session.
Priority key events are typically used for providing "Abort" or "Escape" keys for an application.
This function is similar to GetEvent(), except that it returns a TWsPriorityKeyEvent instead of a TWsEvent.
Note: this should only be called after notification that a priority key event has occurred.
This function always causes a flush of the window server buffer.
|
IMPORT_C void Flush();
Sends all pending commands in the buffer to the window server.
Delivering a command to the window server requires a context switch, and so it is more efficient to deliver several commands in one go. Hence all client commands are normally first placed into a buffer for delivery to the window server.
The buffer is delivered when it gets full, or when a command that returns a value is called (there are a few exceptions to this), or when this function is called.
Note: this function is called when a prompt response is required from the window server, e.g. after doing some drawing.
IMPORT_C TBool SetAutoFlush(TBool aState);
Sets a session's auto-flush state.
If auto-flush is set to ETrue, the window server buffer is flushed immediately anything is put into it, instead of waiting until it becomes full. This setting is normally used only in a debugging environment.
If the auto-flush state is EFalse, the window server buffer is flushed normally.
|
|
| Capability: | WriteDeviceData |
IMPORT_C TInt SetKeyboardRepeatRate(const TTimeIntervalMicroSeconds32 &aInitialTime, const TTimeIntervalMicroSeconds32 &aTime);
Sets the system-wide keyboard repeat rate.
This is the rate at which keyboard events are generated when a key is held down.
The default settings for the keyboard repeat rate are 0.3 seconds for the initial delay, and 0.1 seconds for the interval between subsequent repeats. However, since the settings are system-wide, these will not necessarily be the current settings when an application is launched: the settings may have been over-ridden by another module.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C void GetKeyboardRepeatRate(TTimeIntervalMicroSeconds32 &aInitialTime, TTimeIntervalMicroSeconds32 &aTime);
Gets the current system-wide settings for the keyboard repeat rate.
This function always causes a flush of the window server buffer.
|
IMPORT_C void GetDoubleClickSettings(TTimeIntervalMicroSeconds32 &aInterval, TInt &aDistance);
Gets the current system-wide settings for pointer double clicks.
Double click distances are measured in pixels as the sum of the X distance moved and the Y distance moved between clicks. For example: a first click at 10, 20 and a second click at 13,19 gives a distance of (13-10)+(21-20) = 4.
This function always causes a flush of the window server buffer.
|
| Capability: | WriteDeviceData |
IMPORT_C TInt SetDoubleClick(const TTimeIntervalMicroSeconds32 &aInterval, TInt aDistance);
Sets the system-wide double click settings.
Double click distance is measured, in pixels, as the sum of the X distance moved and the Y distance moved between clicks. For example: a first click at 10, 20 and a second click at 13,19 gives a distance of (13-10)+(21-20) = 4.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt NumWindowGroups() const;
Gets the total number of window groups currently running in the window server.
This includes all the groups running in all sessions.
This function always causes a flush of the window server buffer.
|
IMPORT_C TInt WindowGroupList(CArrayFixFlat< TInt > *aWindowList);
Gets a list of identifiers of all window groups in all window server sessions.
An array buffer must be created to store the resultant list.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt WindowGroupList(RArray< TWindowGroupChainInfo > *aWindowList);
Gets a list of identifier of window group and parent identifier of window group of all window groups in all window server sessions.
An array buffer must be created to store the resultant list.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt NumWindowGroups(TInt aPriority) const;
Gets the number of window groups of a given window group priority running in all sessions in the window server.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt WindowGroupList(TInt aPriority, CArrayFixFlat< TInt > *aWindowList);
Lists the number of window groups of a given window group priority running in all window server sessions.
This function is the same as WindowGroupList() described above, but allows the application to restrict the list of window groups to those of a particular window group priority.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt WindowGroupList(TInt aPriority, RArray< TWindowGroupChainInfo > *aWindowList);
Lists the number of window groups of a given window group priority running in all window server sessions.
This function is the same as WindowGroupList() described above, but allows the application to restrict the list of window groups to those of a particular window group priority.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt GetFocusWindowGroup();
Gets the identifier of the window group that currently has the keyboard focus.
Note: this might not necessarily be the front-most window group, as window groups can disable keyboard focus.
This function always causes a flush of the window server buffer.
|
IMPORT_C TInt GetDefaultOwningWindow();
Gets the identifier of the current default owning window group.
This function always causes a flush of the window server buffer.
|
IMPORT_C TInt SetWindowGroupOrdinalPosition(TInt aIdentifier, TInt aPosition);
Sets the ordinal position of a window group.
This function allows the caller to change the ordinal position of an existing window group. It would typically be used by a shell application.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt GetWindowGroupClientThreadId(TInt aIdentifier, TThreadId &aThreadId);
Gets the thread ID of the client that owns the window group specified by the window group identifier.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt GetWindowGroupHandle(TInt aIdentifier);
Gets the handle of the window specified by the window group identifier.
This is the handle that was passed as an argument to RWindowGroup::Construct().
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt GetWindowGroupOrdinalPriority(TInt aIdentifier);
Gets a window group's priority.
This function always causes a flush of the window server buffer.
|
|
| Capability: | SwEvent | Required when aEvent.Type() < EEventUser. |
IMPORT_C TInt SendEventToWindowGroup(TInt aIdentifier, const TWsEvent &aEvent);
Sends an event to a window group.
This function always causes a flush of the window server buffer.
|
|
| Capability: | SwEvent | Required when aEvent.Type() < EEventUser. |
IMPORT_C TInt SendEventToAllWindowGroups(const TWsEvent &aEvent);
Sends the specified event to all existing window groups.
This function always causes a flush of the window server buffer.
|
|
| Capability: | SwEvent | Required when aEvent.Type() < EEventUser. |
IMPORT_C TInt SendEventToAllWindowGroups(TInt aPriority, const TWsEvent &aEvent);
Sends the specified event to all window groups with the specified priority.
This function always causes a flush of the window server buffer.
|
|
| Capability: | SwEvent | Required when aEvent.Type() < EEventUser. |
IMPORT_C TInt SendEventToOneWindowGroupsPerClient(const TWsEvent &aEvent);
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt GetWindowGroupNameFromIdentifier(TInt aIdentifier, TDes &aWindowName);
Gets the name of a window group from its identifier.
Using the list of identifiers returned by WindowGroupList(), it is possible to get the names of all window groups in the system. Note that window names are a zero length string by default.
Note that the window group name must have been previously set using RWindowGroup::SetName() to contain a meaningful value.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt FindWindowGroupIdentifier(TInt aPreviousIdentifier, const TDesC &aMatch, TInt aOffset=0);
Gets all window groups whose names match a given string, which can contain wildcards.
An example use of this function might be to find all the currently running instances of a particular application, assuming that the window group name contains the application name. An optional argument, aOffset, specifies the number of characters to be ignored at the beginning of the window group name. As several window group names may match the given string, and the function can return only one at a time, there is an argument, aPreviousIdentifier, which gives the identifier for the previous match that was returned. In other words, it means, "get me the next match after this one." The first time the function is called, give 0 as the previous identifier.
Matching is done using TDesC::MatchF(), which does a folded match. Wildcards '*' and '?' can be used to denote one or more characters and exactly one character, respectively. Windows are searched in front to back order.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt FindWindowGroupIdentifier(TInt aPreviousIdentifier, TThreadId aThreadId);
Gets the identifiers of window groups belonging to a client which is owned by a thread with the specified thread ID.
The thread may own more than one window group, so the identifier returned is the one after aPreviousIdentifier. The first time the function is called, use 0 for the previous identifier.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt SendMessageToWindowGroup(TInt aIdentifier, TUid aUid, const TDesC8 &aParams);
Sends a message to a window group.
The window group will then receive an event of type EEventMessageReady notifying it that a message has been received. The window group can belong to this or another session.
In order to receive messages sent using this function you will need to implement the MCoeMessageObserver interface which is defined in the UI Control Framework API.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt SendMessageToAllWindowGroups(TUid aUid, const TDesC8 &aParams);
Sends a message to all window groups.
In order to receive messages sent using this function you will need to implement the MCoeMessageObserver interface which is defined in the UI Control Framework API.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt SendMessageToAllWindowGroups(TInt aPriority, TUid aUid, const TDesC8 &aParams);
Sends a message to all window groups with the specified priority.
In order to receive messages sent using this function you will need to implement the MCoeMessageObserver interface which is defined in the UI Control Framework API.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt FetchMessage(TUid &aUid, TPtr8 &aParams, const TWsEvent &aMessageEvent);
This function always causes a flush of the window server buffer.
|
|
IMPORT_C void SetShadowVector(const TPoint &aVector);
Sets the shadow vector.
|
IMPORT_C TPoint ShadowVector() const;
Gets the current value of the shadow vector.
This function always causes a flush of the window server buffer.
|
IMPORT_C void SetBackgroundColor(TRgb aColor);
Sets the background colour for the window server.
This background can only be seen in areas of the display that have no windows on them: so for many applications it will never be seen. It affects no other windows.
|
IMPORT_C TRgb GetBackgroundColor() const;
Gets the window server's background colour.
This function always causes a flush of the window server buffer.
|
IMPORT_C TInt SetSystemPointerCursor(const RWsPointerCursor &aPointerCursor, TInt aCursorNumber);
Sets a cursor in the system pointer cursor list.
To gain access to the list, the client must first call ClaimSystemPointerCursorList().
This function always causes a flush of the window server buffer.
|
|
IMPORT_C void ClearSystemPointerCursor(TInt aCursorNumber);
Clears a system pointer cursor from the list.
Before calling this function, the client must first gain access to the list by calling ClaimSystemPointerCursorList().
|
| Capability: | WriteDeviceData |
IMPORT_C TInt ClaimSystemPointerCursorList();
Claims the system pointer cursor list.
You must call this function before you can call SetSystemPointerCursor() or ClearSystemPointerCursor().
This function always causes a flush of the window server buffer.
|
IMPORT_C void FreeSystemPointerCursorList();
Releases the system pointer cursor list and deletes all the entries in it.
A client should call this function when it no longer needs the system pointer cursor list.
IMPORT_C TInt SetCustomTextCursor(TInt aIdentifier, const TArray< TSpriteMember > &aSpriteMemberArray, TUint aSpriteFlags, TCustomTextCursorAlignment aAlignment);
Adds
![[Top]](../../../../_stock/arrow_up_2.gif){kind=icon}