Class RWindowTreeNode

RWindowTreeNode

Support

Supported from 5.0

Description

Handle to a node in the server-side window tree.

This handle class is used as the base for both window groups and the windows within them; it is not intended for user derivation, and may not be directly constructed: use one of the standard derived classes instead.

Derivation

MWsClientClass Base class for all classes whose objects are clients of the window server engine RWindowTreeNode Handle to a node in the server-side window tree

Defined in RWindowTreeNode:
Child(), ClearPointerCursor(), Close(), Destroy(), DisableErrorMessages(), DisableFocusChangeEvents(), DisableGroupChangeEvents(), DisableModifierChangedEvents(), DisableOnEvents(), EFadeIncludeChildren, EFadeWindowOnly, EnableErrorMessages(), EnableFocusChangeEvents(), EnableGroupChangeEvents(), EnableModifierChangedEvents(), EnableOnEvents(), FullOrdinalPosition(), NextSibling(), OrdinalPosition(), OrdinalPriority(), Parent(), PrevSibling(), RWindowTreeNode(), SetCustomPointerCursor(), SetFaded(), SetNonFading(), SetOrdinalPosition(), SetPointerCursor(), TFadeControl

Inherited from MWsClientClass:
WsHandle()

protected: RWindowTreeNode();

Description

Protected default constructor.

This constructor creates a sessionless, uninitialised window tree node handle. This class is not for user derivation; however derived classes form part of the standard Window Server client library.

All objects of classes derived from RWindowTreeNode are lightweight handles which can be used as non-pointer instance members. The constructor without parameters is provided to allow such a member to be set up before its owning object has obtained a window server session; however such a node handle will not be valid.

Note that RWindowTreeNode-derived objects must have a reference to a window server session in order to be valid.

protected: RWindowTreeNode(RWsSession& aWs);

Description

Protected constructor which creates an uninitialised window tree node handle within a server session.

This class is not for user derivation; however derived classes form part of the standard Window Server client library, and are constructed with a public constructor with the same signature as this one.

Parameters

RWsSession& aWs Window server session.

TUint32 Child() const;

Description

Gets the first child of the node.

Return value

TUint32 The client handle of the child node that currently has ordinal position 0. This is 0 if there isn't a child.

void ClearPointerCursor();

Support

Supported from 6.0

Description

Clears pointer cursor settings.

These are the settings made by calling SetPointerCursor().

void Close();

Description

Closes the node.

This function should be called on all windows once they are no longer needed. It causes the window server to destroy the server-side window, and frees client-side resources owned by the window.

Note: When Close() is called on a parent window, its children are disconnected from the window tree and are hence removed from the screen. However, any client-side resources owned by its children are not freed. To free these resources, Close() (or Destroy()) must be called on all its children individually.

void Destroy();

Description

Closes and deletes the node.

This function calls Close() followed by delete on the window. Use this function only when the window is allocated in its own heap cell.

void DisableErrorMessages();

Description

Cancels notification of error message events.

Use this function to instruct the server to stop reporting error message events to this window. If the window server has not previously been instructed to report error message events, this function has no effect (i.e. the default is that windows do not get error messages).

See also:

• EnableErrorMessages()

void DisableFocusChangeEvents();

Support

Supported from 6.0

Description

Disables delivery of focus changed events.

Use this function to instruct the server to stop reporting window group focus changed events to this window. If the window server has not previously been instructed to report window group changed events, this function has no effect (i.e. the default is that windows do not get the events).

See also:

• EnableFocusChangeEvents()

void DisableGroupChangeEvents();

Description

Cancel notification of group changed events.

Use this function to instruct the server to stop reporting window group changed events to this window. If the window server has not previously been instructed to report window group changed events, this function has no effect (i.e. the default is that windows do not get the events).

See also:

• EnableGroupChangeEvents()

void DisableModifierChangedEvents();

Description

Cancels notification of modifier changed events.

Use this function to instruct the server to stop reporting modifier changed events to this window. If the window server has not previously been instructed to report modifier changed events, this function has no effect (i.e. the default is that windows do not get the events).

See also:

• EnableModifierChangedEvents()

void DisableOnEvents();

Description

Cancels notification of on events.

This function instructs the server to stop reporting on events to this window. If the window server has not previously been instructed to report on events, this method has no effect (i.e. the default is that windows do not get the events).

See also:

• EnableOnEvents()

TInt EnableErrorMessages(TEventControl aCircumstances);

Description

Requests notification of error message events.

Use this function to instruct the window server to report error message events (of type EEventErrorMessage).

Parameters

TEventControl aCircumstances The circumstances in which error message events are to be reported.

Return value

TInt KErrNone if successful, otherwise one of the system-wide error codes.

See also:

• DisableErrorMessages()

TInt EnableFocusChangeEvents();

Support

Supported from 6.0

Description

Enables focus changed events.

After this function is called, the EEventFocusGroupChanged event is delivered to the window server message queue every time the focus window group changes. The handle of the event is set to the client handle of the widow that this function is called on.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• DisableFocusChangeEvents()

TInt EnableGroupChangeEvents();

Description

Requests notification of group-change events.

Use this function 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. Window group changed events are of type EEventWindowGroupsChanged.

Return value

TInt KErrNone if successful, otherwise one of the system-wide error codes.

See also:

• DisableGroupChangeEvents()

TInt EnableModifierChangedEvents(TUint aModifierMask, TEventControl aCircumstances);

Description

Requests notification of modifier changed events.

Use this function to instruct the window server to report modifier changed events to this window. Values for the modifier keys are defined in TEventModifier. If more than one modifier key is to be monitored, their values should be combined using a bit-wise OR operation. Modifier changed events are of type EEventModifiersChanged.

Parameters

TUint aModifierMask The modifiers to be reported. May be a combination of values defined in TEventModifier TEventControl aCircumstances The circumstances in which modifier changed events are to be reported.

Return value

TInt KErrNone if successful, otherwise one of the system-wide error codes.

See also:

• DisableModifierChangedEvents()

TInt EnableOnEvents(TEventControl aCircumstances=EEventControlOnlyWithKeyboardFocus);

Description

Requests notification of on events. On events are of type EEventSwitchOn.

Parameters

TEventControl aCircumstances=EEventControlOnlyWithKeyboardFocus The circumstances in which on events are to be reported.

Return value

TInt KErrNone if successful, otherwise one of the system-wide error codes.

See also:

• DisableOnEvents()

TInt FullOrdinalPosition() const;

Description

Get the current full ordinal position of a window.

This function normally returns a useful value only when called on a window group, because only window groups are normally given different priorities. For other types of window the value returned is usually the same as that returned by OrdinalPosition().

Return value

TInt The window's full ordinal position.

TUint32 NextSibling() const;

Description

Gets the next window after this one in its sibling list.

The return value is the client handle that was passed in the next sibling window's Construct() function: see RBlankWindow::Construct().

Return value

TUint32 Window handle of next sibling, or 0 if no next sibling exists.

See also:

• PrevSibling()
• Child()
• Parent()

TInt OrdinalPosition() const;

Description

Gets the current ordinal position of the window tree node.

The ordinal position returned is the window's position amongst windows with the same parent (an with the same priority). Displayable windows almost always have the same priority, but window groups might typically have different priorities. If a window group's ordinal position among window groups of all priorities is required, use FullOrdinalPosition().

Note:

• All group windows (across all clients) have the same parent.

Return value

TInt The window's ordinal position.

TInt OrdinalPriority() const;

Support

Supported from 5.1

Description

Gets the ordinal priority of the specified window.

Notes:

• The function was added for FEPs that need to know the priority in their dialogues.

• This function and RWsSession::GetWindowGroupOrdinalPriority() may return different values because this function isn't subject to any ordinal priority adjustment, while the window group ordinal priority may be.

Return value

TInt The ordinal priority of the specified window

TUint32 Parent() const;

Description

Get the node's parent.

The return value is the client integer handle that was passed as an argument to the parent window tree node's Construct() function: see RBlankWindow::Construct(). If called on a window group, this function returns 0, as window groups have no parent.

Return value

TUint32 Handle ID for the parent, or zero for window groups.

See also:

• Child()

TUint32 PrevSibling() const;

Description

Gets the node before this one in the sibling list.

The return value is the handle that was passed in the previous sibling window's Construct() function: see RBlankWindow::Construct().

Return value

TUint32 Handle ID for the previous sibling, or zero if no previous sibling exists.

See also:

• NextSibling()

void SetCustomPointerCursor(const RWsPointerCursor& aPointerCursor);

Description

Sets the pointer cursor to an application-defined cursor.

Parameters

const RWsPointerCursor& aPointerCursor The cursor to use.

void SetFaded(TBool aFaded,TFadeControl aIncludeChildren);

Description

Set window as faded or unfaded.

This function allows a single window to be faded or unfaded. The function also allows the same action to be applied to all of the window's children.

Notes:

• A redraw is required to un-fade a window because information is lost during fading (blank and backup windows deal with this themselves). Areas in shadow when the window is faded also require a redraw.

• While a window is faded all drawing to that window will be adjust appropriately by the window server.

Parameters

TBool aFaded ETrue to fade the window, EFalse to un-fade it. TFadeControl aIncludeChildren Fade control flags. This sets whether fading/un-fading is also to apply to child windows.

Panic codes

The function will panic if it is called on a window group, with aIncludeChildren not set to include all child windows.

void SetFaded(TBool aFaded,TFadeControl aIncludeChildren,TUint8 aBlackMap,TUint8 aWhiteMap);

Support

Supported from 6.0

Description

Sets one or more windows as faded or unfaded, specifying a fading map.

Fading is used to change the colour of a window to make other windows stand out. For example, you would fade all other windows when displaying a dialogue.

Fading can either make a faded window closer to white or closer to black. Setting the fading map allows you to over-ride the default fading parameters set in RWsSession::SetDefaultFadingParameters().

The white and black fading values define the range over which colours are re-mapped when a window is faded. As the values get closer together, all colours colours in the faded window becomes more similar — creating the fading effect. When the numbers cross over (so that the black value is greater than the white value) the colours in the faded window start to invert — i.e. colours that were closer to white in the unfaded window are mapped to a darker colour when the window is faded.

The function also allows the fading action applied to this window to be applied to all of its children.

Notes:

• Fading a window for a 2nd time will not change the fading map used.

• A redraw is required to un-fade a window because information is lost during fading. Note that blank (RBlankWindow) and backup (RBackupWindow) windows deal with this themselves. Areas in shadow when the window is faded also require a redraw.

• While a window is faded all drawing to that window will be adjust appropriately by the window server.

Parameters

TBool aFaded ETrue to fade the window, EFalse to un-fade it. TFadeControl aIncludeChildren Fade control flags. This sets whether fading/un-fading is also to apply to all child windows. TUint8 aBlackMap Black map fading parameter. TUint8 aWhiteMap White map fading parameter.

Panic codes

The function will panic if it is called on a window group, with aIncludeChildren not set to include all child windows.

See also:

• RWsSession::SetDefaultFadingParameters()
• CWindowGc::SetFadingParameters()

void SetNonFading(TBool aNonFading);

Description

Sets whether a window is non-fading.

When the non-fading flag is set the window will unfade if needed and remain unfaded until this flag is removed. This is useful for toolbars etc. which must never be faded.

Parameters

TBool aNonFading ETrue to set the non-fading flag, EFalse (the default) to re-set it.

void SetOrdinalPosition(TInt aPos);

Description

Sets the ordinal position of a window.

The ordinal position is relative to all other windows of the same priority as this window: the priority of all displayable windows (i.e. not window groups) is almost always 0 (the default).

Parameters

TInt aPos Ordinal position. Set this to -1 to send the window to the back (the last ordinal position).

void SetOrdinalPosition(TInt aPos, TInt aOrdinalPriority);

Description

Sets the ordinal position and priority of a window.

Only window groups are normally given non-default priorities.

Parameters

TInt aPos New ordinal position among windows of the same priority. Set this to -1 to send the window to the back (the last ordinal position). TInt aOrdinalPriority New window group priority.

TInt SetPointerCursor(TInt aCursorNumber);

Description

Sets the pointer cursor from system pointer cursor list.

Use this function to set the current cursor to one contained in the system pointer cursor list. If the list does not contain a cursor with an index of aCursorNumber, the function will attempt to set the cursor to the default system pointer cursor, which has an index of 0 in the list.

The RWsSession class provides functions for setting and controlling the system pointer cursor list.

Parameters

TInt aCursorNumber Cursor index in the system pointer cursor list.

Return value

TInt KErrNone if successful, otherwise one of the system-wide error codes.

See also:

• ClearPointerCursor()

TFadeControl

Description

Fade control flags.

These flags define whether fading is applied to all child windows when SetFaded() is called on a window.

EFadeIncludeChildren Include all child windows in fading/un-fading action. EFadeWindowOnly Fade only the parent window. Note that it will cause a panic if this value is used when SetFaded() is called on a window group.