diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE7CF024-4898-551A-841B-38EC57A3EC82.dita --- a/Symbian3/SDK/Source/GUID-CE7CF024-4898-551A-841B-38EC57A3EC82.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CE7CF024-4898-551A-841B-38EC57A3EC82.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,86 +1,86 @@ - - - - - -Ordinal -PositionAll windows in the Window Server have an ordinal - position which describes their z-order—that is, their ordering -from nearest the viewer to furthest away from the viewer. Each window’s ordinal -position is relative to its parent window and is unique among its siblings. -

Variant: Both (ScreenPlay and non-ScreenPlay). Target audience: -Application developers.

-

Ordinal positions are positive integers starting at 0, with 0 being the -front-most position. A window with an ordinal position of 0 is displayed in -the foreground, i.e., in front of all its sibling windows. -The ordinal position of other windows increases by one for each position behind -this window.

-

When a window is created, it is automatically given an ordinal position -of 0 within its parent window. Then, when another child of the same parent -is created, the first window’s ordinal position changes to 1, and the new -window’s position is 0. These ordinal positions can be changed after the windows -have been created, using functions provided by the RWindowTreeNode class.

-

When a window's ordinal position is changed, its order in the sibling list -is also changed, so that the window with ordinal position 0 is always first -in the sibling list, the window with ordinal position 1 is next in the list, -and so on. Changing the ordinal position of windows therefore affects the -result of the RWindowTreeNode::Parent(), RWindowTreeNode::Child(), RWindowTreeNode::NextSibling() and RWindowTreeNode::PrevSibling() functions.

-

To give an illustration of how ordinal positions work, the diagram below -shows three windows, A, B and C, all belonging to the same window group. Their -ordinal positions are as follows: A=0; B=1; C=2.

- - - -

This would be the default ordering of the windows if they were created -in the order CBA. Many sibling windows within an application may not overlap -in practice: nevertheless, each window has a unique ordinal position, even -though this will not be evident in the way they are displayed.

-

If a window’s ordinal position is changed, its position on the screen will -change. All its child windows also move with it, although their ordinal positions, -which are relative to the parent, don’t change.

-
Moving a window to the front

A window is moved -to the front (i.e., to the foreground) by giving it an -ordinal position of 0. The diagram below shows windows A, B and C, but window -B has now been given an ordinal position of 0. A’s position has been incremented -to 1, and C’s remains as 2.

- -

The diagram below shows the same three windows as above, except -that window B now contains a child window, D. Window D’s ordinal position -is 0, relative to its parent window, B.

- -

If window A is now moved to the front, window B moves behind it, -as shown in the diagram below. Window D’s ordinal position is still 0, but -because its position is relative to its parent window, it moves with window -B to behind window A.

- -
-
Moving a window to the back

If a window is given -an ordinal position greater than all its siblings, it is moved to the back -of them. For convenience, the functions for setting ordinal position allow -a negative ordinal position to be specified, which sends the window to the -back and sets its ordinal position to be the highest among its siblings.

-
Ordinal position of window groups

The ordinal position -of a window group has special significance because there is normally one window -group per application. As a result, the z-order of applications on the screen -is typically determined by the ordinal positions of their window groups. For -example, giving a window group an ordinal position of 0 typically brings an -application to the front of the screen. Note, however, that window groups -also have a priority, which overrides ordinal position. Ordinal position only -applies among window groups of the same priority.

The ordinal position -of window groups is typically controlled by a shell or similar application. -The RWsSession class provides functions for -such applications to set window group ordinal positions.

-
Keyboard focus and window group ordinal position

When -a window group is given an ordinal position of 0, it is automatically given -keyboard focus, unless it has disabled keyboard focus by calling EnableReceiptOfFocus(EFalse), -or another window group has a higher priority.

- -Window Types - + + + + + +Ordinal +PositionAll windows in the Window Server have an ordinal + position which describes their z-order—that is, their ordering +from nearest the viewer to furthest away from the viewer. Each window’s ordinal +position is relative to its parent window and is unique among its siblings. +

Variant: Both (ScreenPlay and non-ScreenPlay). Target audience: +Application developers.

+

Ordinal positions are positive integers starting at 0, with 0 being the +front-most position. A window with an ordinal position of 0 is displayed in +the foreground, i.e., in front of all its sibling windows. +The ordinal position of other windows increases by one for each position behind +this window.

+

When a window is created, it is automatically given an ordinal position +of 0 within its parent window. Then, when another child of the same parent +is created, the first window’s ordinal position changes to 1, and the new +window’s position is 0. These ordinal positions can be changed after the windows +have been created, using functions provided by the RWindowTreeNode class.

+

When a window's ordinal position is changed, its order in the sibling list +is also changed, so that the window with ordinal position 0 is always first +in the sibling list, the window with ordinal position 1 is next in the list, +and so on. Changing the ordinal position of windows therefore affects the +result of the RWindowTreeNode::Parent(), RWindowTreeNode::Child(), RWindowTreeNode::NextSibling() and RWindowTreeNode::PrevSibling() functions.

+

To give an illustration of how ordinal positions work, the diagram below +shows three windows, A, B and C, all belonging to the same window group. Their +ordinal positions are as follows: A=0; B=1; C=2.

+ + + +

This would be the default ordering of the windows if they were created +in the order CBA. Many sibling windows within an application may not overlap +in practice: nevertheless, each window has a unique ordinal position, even +though this will not be evident in the way they are displayed.

+

If a window’s ordinal position is changed, its position on the screen will +change. All its child windows also move with it, although their ordinal positions, +which are relative to the parent, don’t change.

+
Moving a window to the front

A window is moved +to the front (i.e., to the foreground) by giving it an +ordinal position of 0. The diagram below shows windows A, B and C, but window +B has now been given an ordinal position of 0. A’s position has been incremented +to 1, and C’s remains as 2.

+ +

The diagram below shows the same three windows as above, except +that window B now contains a child window, D. Window D’s ordinal position +is 0, relative to its parent window, B.

+ +

If window A is now moved to the front, window B moves behind it, +as shown in the diagram below. Window D’s ordinal position is still 0, but +because its position is relative to its parent window, it moves with window +B to behind window A.

+ +
+
Moving a window to the back

If a window is given +an ordinal position greater than all its siblings, it is moved to the back +of them. For convenience, the functions for setting ordinal position allow +a negative ordinal position to be specified, which sends the window to the +back and sets its ordinal position to be the highest among its siblings.

+
Ordinal position of window groups

The ordinal position +of a window group has special significance because there is normally one window +group per application. As a result, the z-order of applications on the screen +is typically determined by the ordinal positions of their window groups. For +example, giving a window group an ordinal position of 0 typically brings an +application to the front of the screen. Note, however, that window groups +also have a priority, which overrides ordinal position. Ordinal position only +applies among window groups of the same priority.

The ordinal position +of window groups is typically controlled by a shell or similar application. +The RWsSession class provides functions for +such applications to set window group ordinal positions.

+
Keyboard focus and window group ordinal position

When +a window group is given an ordinal position of 0, it is automatically given +keyboard focus, unless it has disabled keyboard focus by calling EnableReceiptOfFocus(EFalse), +or another window group has a higher priority.

+ +Window Types + \ No newline at end of file