|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-CE7CF024-4898-551A-841B-38EC57A3EC82" xml:lang="en"><title>Ordinal |
|
13 Position</title><shortdesc>All windows in the Window Server have an <keyword>ordinal |
|
14 position</keyword> which describes their z-order—that is, their ordering |
|
15 from nearest the viewer to furthest away from the viewer. Each window’s ordinal |
|
16 position is relative to its parent window and is unique among its siblings. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
17 <p> <b>Variant</b>: Both (ScreenPlay and non-ScreenPlay). <b>Target audience</b>: |
|
18 Application developers. </p> |
|
19 <p>Ordinal positions are positive integers starting at 0, with 0 being the |
|
20 front-most position. A window with an ordinal position of 0 is displayed in |
|
21 the <keyword>foreground</keyword>, i.e., in front of all its sibling windows. |
|
22 The ordinal position of other windows increases by one for each position behind |
|
23 this window. </p> |
|
24 <p>When a window is created, it is automatically given an ordinal position |
|
25 of 0 within its parent window. Then, when another child of the same parent |
|
26 is created, the first window’s ordinal position changes to 1, and the new |
|
27 window’s position is 0. These ordinal positions can be changed after the windows |
|
28 have been created, using functions provided by the <codeph>RWindowTreeNode</codeph> class. </p> |
|
29 <p>When a window's ordinal position is changed, its order in the sibling list |
|
30 is also changed, so that the window with ordinal position 0 is always first |
|
31 in the sibling list, the window with ordinal position 1 is next in the list, |
|
32 and so on. Changing the ordinal position of windows therefore affects the |
|
33 result of the <xref href="GUID-9FFD28C7-8747-3438-84BF-44AF26ACEC7D.dita#GUID-9FFD28C7-8747-3438-84BF-44AF26ACEC7D/GUID-12634A4D-36F1-35AD-8D61-EEA63872CF8B"><apiname>RWindowTreeNode::Parent()</apiname></xref>, <xref href="GUID-9FFD28C7-8747-3438-84BF-44AF26ACEC7D.dita#GUID-9FFD28C7-8747-3438-84BF-44AF26ACEC7D/GUID-1FFFFED4-5062-3C9D-B9A6-A89B107080FF"><apiname>RWindowTreeNode::Child()</apiname></xref>, <xref href="GUID-9FFD28C7-8747-3438-84BF-44AF26ACEC7D.dita#GUID-9FFD28C7-8747-3438-84BF-44AF26ACEC7D/GUID-F11A3640-844E-30D3-AAB2-D154E4EACBB4"><apiname>RWindowTreeNode::NextSibling()</apiname></xref> and <xref href="GUID-9FFD28C7-8747-3438-84BF-44AF26ACEC7D.dita#GUID-9FFD28C7-8747-3438-84BF-44AF26ACEC7D/GUID-1B6C1D5F-8F27-3472-87EE-CBB90D1A9280"><apiname>RWindowTreeNode::PrevSibling()</apiname></xref> functions. </p> |
|
34 <p>To give an illustration of how ordinal positions work, the diagram below |
|
35 shows three windows, A, B and C, all belonging to the same window group. Their |
|
36 ordinal positions are as follows: A=0; B=1; C=2. </p> |
|
37 <fig id="GUID-FB15A25F-FB7A-5031-9D17-51CD7C8ACA1D"> |
|
38 <image href="GUID-694C7416-927E-58F7-B010-CA55D2FFA88F_d0e194205_href.png" placement="inline"/> |
|
39 </fig> |
|
40 <p>This would be the default ordering of the windows if they were created |
|
41 in the order CBA. Many sibling windows within an application may not overlap |
|
42 in practice: nevertheless, each window has a unique ordinal position, even |
|
43 though this will not be evident in the way they are displayed. </p> |
|
44 <p>If a window’s ordinal position is changed, its position on the screen will |
|
45 change. All its child windows also move with it, although their ordinal positions, |
|
46 which are relative to the parent, don’t change. </p> |
|
47 <section id="GUID-4B42408E-06DC-4A98-9AC8-7EEAF533D614"><title>Moving a window to the front</title> <p>A window is moved |
|
48 to the front (i.e., to the <keyword>foreground</keyword>) by giving it an |
|
49 ordinal position of 0. The diagram below shows windows A, B and C, but window |
|
50 B has now been given an ordinal position of 0. A’s position has been incremented |
|
51 to 1, and C’s remains as 2. </p> <fig id="GUID-0B1ED6C1-4F47-5527-A9F9-5B4AD03528D5"> |
|
52 <image href="GUID-74B329CD-4640-5636-9D8D-20F0D7E09EB4_d0e194226_href.png" placement="inline"/> |
|
53 </fig> <p>The diagram below shows the same three windows as above, except |
|
54 that window B now contains a child window, D. Window D’s ordinal position |
|
55 is 0, relative to its parent window, B. </p> <fig id="GUID-313C9AEE-6ADB-5842-9EB6-0D563D7FC582"> |
|
56 <image href="GUID-7AE4D17F-728A-5B7E-A3F9-A903E64731B1_d0e194234_href.png" placement="inline"/> |
|
57 </fig> <p>If window A is now moved to the front, window B moves behind it, |
|
58 as shown in the diagram below. Window D’s ordinal position is still 0, but |
|
59 because its position is relative to its parent window, it moves with window |
|
60 B to behind window A. </p> <fig id="GUID-B6882EE3-C071-522B-9D7E-86D84F8D64DC"> |
|
61 <image href="GUID-40A3938E-366E-5318-A7FA-146F9E5E23B1_d0e194242_href.png" placement="inline"/> |
|
62 </fig> </section> |
|
63 <section id="GUID-EDA73282-0AB9-49EE-BAAB-C6D0DB267F56"><title>Moving a window to the back</title> <p>If a window is given |
|
64 an ordinal position greater than all its siblings, it is moved to the back |
|
65 of them. For convenience, the functions for setting ordinal position allow |
|
66 a negative ordinal position to be specified, which sends the window to the |
|
67 back and sets its ordinal position to be the highest among its siblings. </p> </section> |
|
68 <section id="GUID-5288AAAA-9513-4981-98E1-8B5F4EDAC35C"><title>Ordinal position of window groups</title> <p>The ordinal position |
|
69 of a window group has special significance because there is normally one window |
|
70 group per application. As a result, the z-order of applications on the screen |
|
71 is typically determined by the ordinal positions of their window groups. For |
|
72 example, giving a window group an ordinal position of 0 typically brings an |
|
73 application to the front of the screen. Note, however, that window groups |
|
74 also have a priority, which overrides ordinal position. Ordinal position only |
|
75 applies among window groups of the same priority. </p> <p>The ordinal position |
|
76 of window groups is typically controlled by a shell or similar application. |
|
77 The <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession</apiname></xref> class provides functions for |
|
78 such applications to set window group ordinal positions. </p> </section> |
|
79 <section id="GUID-D5CA8ED0-CD91-4FB9-B56F-613EE825435C"><title>Keyboard focus and window group ordinal position</title> <p>When |
|
80 a window group is given an ordinal position of 0, it is automatically given |
|
81 keyboard focus, unless it has disabled keyboard focus by calling <codeph>EnableReceiptOfFocus(EFalse)</codeph>, |
|
82 or another window group has a higher priority. </p> </section> |
|
83 </conbody><related-links> |
|
84 <link href="GUID-99AE1D62-571A-5A63-B472-C0FBC0861F52.dita"><linktext>Window Types</linktext> |
|
85 </link> |
|
86 </related-links></concept> |