|
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-0A13A931-016C-5325-97AF-2DE0B210DF2F" xml:lang="en"><title>Window Server Client-Side Library Overview</title><shortdesc>The Window Server keeps track of window sizes, positions, |
|
13 visibility and validity (keeping window content up to date). It also |
|
14 receives and distributes user input in the form of key presses and |
|
15 pointer events. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
16 <p>Note that much of the Window Server API is low-level and is encapsulated |
|
17 in the UI Control Framework API. </p> |
|
18 <section id="GUID-E1891417-0C8F-46FE-BC4D-23C1E1BB750E"><title>Window |
|
19 Server client-side library details</title> <p>The following table |
|
20 shows the DLLs that provides the functionality and the library to |
|
21 which your code must link. </p> <table id="GUID-D5750916-4A95-5944-9ADB-05E35D47592B"> |
|
22 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/> |
|
23 <colspec colname="col2"/> |
|
24 <thead> |
|
25 <row> |
|
26 <entry>DLL</entry> |
|
27 <entry>LIB</entry> |
|
28 <entry>Short description</entry> |
|
29 </row> |
|
30 </thead> |
|
31 <tbody> |
|
32 <row> |
|
33 <entry><p> <filepath>ws32_nga.dll</filepath> </p> </entry> |
|
34 <entry><p> <filepath>ws32.lib</filepath> </p> </entry> |
|
35 <entry><p>The Window Server client-side library for the <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref> variant. </p> </entry> |
|
36 </row> |
|
37 <row> |
|
38 <entry><p> <filepath>ws32_nonnga.dll</filepath> </p> </entry> |
|
39 <entry> <p> <filepath>ws32.lib</filepath> </p></entry> |
|
40 <entry><p>The Window Server client-side library for the <xref href="GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita">non-ScreenPlay</xref> variant. </p></entry> |
|
41 </row> |
|
42 </tbody> |
|
43 </tgroup> |
|
44 </table> <p>The details of the client-side API are very similar in |
|
45 the two variants. There are some additional features in the ScreenPlay |
|
46 variant for displaying surfaces.</p> </section> |
|
47 <section id="GUID-D5B8436F-D7AA-4A72-A967-FC2BB8D8EB0B"><title>Architecture</title> <p>The Window Server is used by all applications that have a user |
|
48 interface. The primary user input for these applications comes from |
|
49 the keyboard and pointer, and their primary user-visible output is |
|
50 to the screen. These input and output devices are shared between all |
|
51 applications on the system. Each client thread opens a session to |
|
52 the server, and issues requests for service. </p> <fig id="GUID-4EEE0DBF-A4DC-59A1-8310-504BF05204C7"> |
|
53 <title> Window Server </title> |
|
54 <desc><p>The Window Server controls access by many client applications, |
|
55 to the machine’s screen, keyboard and pointer. </p> </desc> |
|
56 <image href="GUID-FE4BBEB4-4E5A-5BF2-A72F-AF53BAD83518_d0e187538_href.png" placement="inline"/> |
|
57 </fig> <p>The Window Server thread runs at a higher priority than |
|
58 any application; only the kernel runs at a higher priority. Therefore, |
|
59 all applications' requests for screen updates, and all handling of |
|
60 machine events such as pointers and keys, are handled at higher priority |
|
61 than any individual application. </p> <p>Each client application runs |
|
62 in its own thread. The Window Server presents an interface to client |
|
63 applications such that they can run without direct interaction with |
|
64 the other applications on the machine. Drawing is clipped to the visible |
|
65 area of the application’s windows. Pointer events are only received |
|
66 if they are related to the application’s windows. Similarly, keyboard |
|
67 events are only given to an application whose window group has focus |
|
68 or to one that has captured them. A client application may ignore |
|
69 the majority of events relating to other applications. It won't even |
|
70 be told about most of them. </p> <p>Each client application communicates |
|
71 with the Window Server using a Window Server session, or other object |
|
72 created from the session. The application waits to receive events |
|
73 by setting up one or more active objects. Events include user input |
|
74 and requests that windows be redrawn. Applications may create systems |
|
75 of windows and draw to them. </p> </section> |
|
76 <section id="GUID-A8BCF1C1-A637-4DDC-9249-BCEF4E23BA06"><title>Window |
|
77 server client-side API</title> <p>The following diagram shows the |
|
78 key classes in the Window Server client-side library. Below the diagram |
|
79 we provide a summary of the key concepts. </p> <fig id="GUID-A84A2706-1AF0-598B-976E-0980AD69E6E7"> |
|
80 <title> Window Server client-side API classes |
|
81 </title> |
|
82 <image href="GUID-FEFF353E-DE8A-5FBA-B696-CD01D06BE813_d0e187563_href.png" placement="inline"/> |
|
83 </fig> <table id="GUID-37EDAB58-6F7B-526A-8E46-891598924120"> |
|
84 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
85 <thead> |
|
86 <row> |
|
87 <entry>Concept</entry> |
|
88 <entry>Description</entry> |
|
89 </row> |
|
90 </thead> |
|
91 <tbody> |
|
92 <row> |
|
93 <entry><p> <b>Session</b> </p> </entry> |
|
94 <entry><p>A Window Server session allows an application to control |
|
95 and interrogate its windows, the events it wishes to receive, and |
|
96 all other window groups connected to the Window Server. A session |
|
97 is encapsulated by <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession</apiname></xref>. </p> </entry> |
|
98 </row> |
|
99 <row> |
|
100 <entry><p> <b>Events</b> </p> </entry> |
|
101 <entry><p>Applications function by waiting for events and handling |
|
102 them. Common events are user input, and requests that windows be redrawn. |
|
103 The Window Server session is used to request and obtain events. Most |
|
104 events (such as key and point events) are encapsulated in <xref href="GUID-5D0B1595-1AC7-3C44-AC6B-0EFB5EABCF31.dita"><apiname>TWsEvent</apiname></xref>. </p> <p>A redraw event tells the application |
|
105 what screen area needs redrawing. It is encapsulated in <xref href="GUID-B5F16BF3-569D-3985-AAB7-439E3410468D.dita"><apiname>TWsRedrawEvent</apiname></xref>. </p> </entry> |
|
106 </row> |
|
107 <row> |
|
108 <entry><p> <b>Window group</b> </p> </entry> |
|
109 <entry><p>A window group is special non-displayable type of window, |
|
110 which can be considered as the root window of an application. Keyboard |
|
111 events and focus are associated with it, and it can have a name, used |
|
112 for such things as lists of running applications. A window group is |
|
113 provided by <xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita"><apiname>RWindowGroup</apiname></xref>. </p> </entry> |
|
114 </row> |
|
115 <row> |
|
116 <entry><p> <b>Drawable windows</b> </p> </entry> |
|
117 <entry><p>Drawable windows allow applications to draw to the screen. |
|
118 They have operations to control size, position, visibility, scrolling, |
|
119 z-order, and parent/child relationships. In a standard drawable window, |
|
120 areas that become invalid (e.g. when an overlaying window is removed) |
|
121 must be redrawn by the client application. It is provided by <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>. </p> <p>A backed-up drawable window's content |
|
122 is stored by the Window Server, and redrawn by the server when it |
|
123 becomes invalid. It is provided by <xref href="GUID-27A95595-F74D-32B2-A960-0CA290C8A3B3.dita"><apiname>RBackedUpWindow</apiname></xref>. </p> <p>These window types are derived from a sequence of base |
|
124 classes, <xref href="GUID-9FFD28C7-8747-3438-84BF-44AF26ACEC7D.dita"><apiname>RWindowTreeNode</apiname></xref>, <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita"><apiname>RWindowBase</apiname></xref>, and <xref href="GUID-FDF4BB7E-8750-3564-982A-0124A977C82E.dita"><apiname>RDrawableWindow</apiname></xref>. </p> </entry> |
|
125 </row> |
|
126 <row> |
|
127 <entry><p> <b>Graphics</b> </p> </entry> |
|
128 <entry><p>Applications draw to drawable windows through a windows |
|
129 graphics context provided by a windows graphics device. These implement |
|
130 the abstract graphics context and graphics device interfaces respectively, |
|
131 as defined in the Graphics API. </p> <p>The windows graphics context |
|
132 is provided by <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>; the windows graphics |
|
133 device by <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref>. The bitmap class, <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref>, is extended for most efficient use with the |
|
134 Window Server by <xref href="GUID-17150D76-BB82-3A4B-8B1A-8BA93CB1A9EF.dita"><apiname>CWsBitmap</apiname></xref>. </p> </entry> |
|
135 </row> |
|
136 <row> |
|
137 <entry><p> <b>Sprites and cursors</b> </p> </entry> |
|
138 <entry><p>A sprite is an arbitrary-shaped bitmap that can be moved |
|
139 without applications having to redraw the underlying screen. It has |
|
140 one or more sprite members, each containing a bitmap image and a time |
|
141 interval for that bitmap to be displayed. The sprite class is <xref href="GUID-75C09150-E93B-323D-AFBF-E42C7BD78229.dita"><apiname>RWsSprite</apiname></xref>; the sprite member class is <xref href="GUID-7F4E749E-D08D-3771-A3F1-9AEC5D16B78C.dita"><apiname>TSpriteMember</apiname></xref>. </p> <p>A specialized sprite type is provided for pointer cursors, |
|
142 which automatically track the position of a pointer. It is provided |
|
143 by <xref href="GUID-6E71A7F9-E980-3D99-ACB0-6743A0D13EBF.dita"><apiname>RWsPointerCursor</apiname></xref>. </p> <p>Text cursors are handled |
|
144 by the class <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita"><apiname>CTextView</apiname></xref>. They can take the form |
|
145 of a text or a line cursor. </p> </entry> |
|
146 </row> |
|
147 <row> |
|
148 <entry><p> <b>Animation client</b> </p> </entry> |
|
149 <entry><p>Third-parties can write Window Server plug-in DLLs, as defined |
|
150 in the Animation API, that perform animations. Providers of such animation |
|
151 DLLs must also provide a client-side interface to allow applications |
|
152 to control the animation. The base class for an animation client-side |
|
153 interface is <xref href="GUID-4180CDBA-E9A5-3A4B-9778-26D172FAFD10.dita"><apiname>RAnim</apiname></xref>. </p> <p>Clients must request |
|
154 an animation DLL to be loaded before the animations provided by it |
|
155 can be used. This is done through <xref href="GUID-800B3667-F45F-391F-A8A9-F876FB4ABC34.dita"><apiname>RAnimDll</apiname></xref>. </p> </entry> |
|
156 </row> |
|
157 <row> |
|
158 <entry><p> <b>Transparent windows</b> </p> </entry> |
|
159 <entry><p>Transparent windows enable you to display semi-transparent |
|
160 bitmaps on a window. The window must be an <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>. Methods to create transparent windows can be found in the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> class. </p> </entry> |
|
161 </row> |
|
162 <row> |
|
163 <entry><p> <b>Surfaces</b> </p> </entry> |
|
164 <entry><p>In ScreenPlay, applications (such as games and video) that |
|
165 use a rendering API that can potentially benefit from hardware acceleration |
|
166 (depending on hardware) can render directly to graphics <i>surfaces</i>. A surface is a hardware independent buffer for holding an image |
|
167 or part of a scene. Surfaces are identified using a 128 bit surface |
|
168 ID in a <codeph>TSurfaceId</codeph> class.</p> <p>The Window Server |
|
169 delegates the composition of surfaces to a composition engine which |
|
170 has an adaptation part that enables device creators to take advantage |
|
171 of graphics processing hardware if it is available. However, this |
|
172 is largely transparent to application developers. </p><p>See <xref href="GUID-1C025957-258C-54C0-94A5-AD60C14E6D76.dita">External Surfaces</xref> for more information.</p> </entry> |
|
173 </row> |
|
174 <row> |
|
175 <entry><p> <b>Direct Screen Access (DSA)</b> </p> </entry> |
|
176 <entry><p>Mainly used in the non-ScreenPlay variant, DSA enables applications |
|
177 that require high frame rates (such as video and games) to bypass |
|
178 the Window Server and write to the screen directly. This avoids client-server |
|
179 communication and as a result is faster. However, some interaction |
|
180 with the Window Server is needed to prevent the application from drawing |
|
181 over other application's data. </p> <p>In ScreenPlay, Symbian recommends |
|
182 the use of <xref href="GUID-1C025957-258C-54C0-94A5-AD60C14E6D76.dita">external surfaces</xref> in preference to DSA. However, support for |
|
183 DSA is maintained for backward compatibility reasons, although there |
|
184 are some subtle changes in the support offered.</p><p>ScreenPlay does |
|
185 not support the mixing of <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> and DSA rendering |
|
186 to the same window. When DSA rendering is present, any <codeph>CWindowGc</codeph> rendering to the same window is ignored. For example, an application |
|
187 that uses <codeph>CWindowGC</codeph> rendering in one part of a window |
|
188 and DSA rendering in another part will not work as expected in a ScreenPlay |
|
189 environment. Similarly, <codeph>CWindowGc</codeph> rendering can no |
|
190 longer be used to seed the DSA content as it could previously. However, <codeph>CWindowGc</codeph> rendering can be provided but it is not rendered |
|
191 until the DSA rendering finishes. It is therefore best to avoid mixing |
|
192 the rendering types in the same window.</p> </entry> |
|
193 </row> |
|
194 </tbody> |
|
195 </tgroup> |
|
196 </table> </section> |
|
197 </conbody><related-links> |
|
198 <link href="GUID-DC5E8C7D-D697-53E8-87F4-344301430E61.dita"><linktext>Window |
|
199 Server Client-Side Library</linktext></link> |
|
200 </related-links></concept> |