--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-0A13A931-016C-5325-97AF-2DE0B210DF2F.dita	Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,200 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License 
+"Eclipse Public License v1.0" which accompanies this distribution, 
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+    Nokia Corporation - initial contribution.
+Contributors: 
+-->
+<!DOCTYPE concept
+  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<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,
+visibility and validity (keeping window content up to date). It also
+receives and distributes user input in the form of key presses and
+pointer events. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>Note that much of the Window Server API is low-level and is encapsulated
+in the UI Control Framework API. </p>
+<section id="GUID-E1891417-0C8F-46FE-BC4D-23C1E1BB750E"><title>Window
+Server client-side library details</title> <p>The following table
+shows the DLLs that provides the functionality and the library to
+which your code must link. </p> <table id="GUID-D5750916-4A95-5944-9ADB-05E35D47592B">
+<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/>
+<colspec colname="col2"/>
+<thead>
+<row>
+<entry>DLL</entry>
+<entry>LIB</entry>
+<entry>Short description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <filepath>ws32_nga.dll</filepath>  </p> </entry>
+<entry><p> <filepath>ws32.lib</filepath>  </p> </entry>
+<entry><p>The Window Server client-side library for the <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref> variant. </p> </entry>
+</row>
+<row>
+<entry><p> <filepath>ws32_nonnga.dll</filepath>  </p> </entry>
+<entry> <p> <filepath>ws32.lib</filepath>  </p></entry>
+<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>
+</row>
+</tbody>
+</tgroup>
+</table> <p>The details of the client-side API are very similar in
+the two variants. There are some additional features in the ScreenPlay
+variant for displaying surfaces.</p> </section>
+<section id="GUID-D5B8436F-D7AA-4A72-A967-FC2BB8D8EB0B"><title>Architecture</title> <p>The Window Server is used by all applications that have a user
+interface. The primary user input for these applications comes from
+the keyboard and pointer, and their primary user-visible output is
+to the screen. These input and output devices are shared between all
+applications on the system. Each client thread opens a session to
+the server, and issues requests for service. </p> <fig id="GUID-4EEE0DBF-A4DC-59A1-8310-504BF05204C7">
+<title>              Window Server            </title>
+<desc><p>The Window Server controls access by many client applications,
+to the machine’s screen, keyboard and pointer. </p> </desc>
+<image href="GUID-FE4BBEB4-4E5A-5BF2-A72F-AF53BAD83518_d0e187538_href.png" placement="inline"/>
+</fig> <p>The Window Server thread runs at a higher priority than
+any application; only the kernel runs at a higher priority. Therefore,
+all applications' requests for screen updates, and all handling of
+machine events such as pointers and keys, are handled at higher priority
+than any individual application. </p> <p>Each client application runs
+in its own thread. The Window Server presents an interface to client
+applications such that they can run without direct interaction with
+the other applications on the machine. Drawing is clipped to the visible
+area of the application’s windows. Pointer events are only received
+if they are related to the application’s windows. Similarly, keyboard
+events are only given to an application whose window group has focus
+or to one that has captured them. A client application may ignore
+the majority of events relating to other applications. It won't even
+be told about most of them. </p> <p>Each client application communicates
+with the Window Server using a Window Server session, or other object
+created from the session. The application waits to receive events
+by setting up one or more active objects. Events include user input
+and requests that windows be redrawn. Applications may create systems
+of windows and draw to them. </p> </section>
+<section id="GUID-A8BCF1C1-A637-4DDC-9249-BCEF4E23BA06"><title>Window
+server client-side API</title> <p>The following diagram shows the
+key classes in the Window Server client-side library. Below the diagram
+we provide a summary of the key concepts. </p> <fig id="GUID-A84A2706-1AF0-598B-976E-0980AD69E6E7">
+<title>             Window Server client-side API classes        
+   </title>
+<image href="GUID-FEFF353E-DE8A-5FBA-B696-CD01D06BE813_d0e187563_href.png" placement="inline"/>
+</fig> <table id="GUID-37EDAB58-6F7B-526A-8E46-891598924120">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>Concept</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <b>Session</b>  </p> </entry>
+<entry><p>A Window Server session allows an application to control
+and interrogate its windows, the events it wishes to receive, and
+all other window groups connected to the Window Server. A session
+is encapsulated by <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession</apiname></xref>. </p> </entry>
+</row>
+<row>
+<entry><p> <b>Events</b>  </p> </entry>
+<entry><p>Applications function by waiting for events and handling
+them. Common events are user input, and requests that windows be redrawn.
+The Window Server session is used to request and obtain events. Most
+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
+what screen area needs redrawing. It is encapsulated in <xref href="GUID-B5F16BF3-569D-3985-AAB7-439E3410468D.dita"><apiname>TWsRedrawEvent</apiname></xref>. </p> </entry>
+</row>
+<row>
+<entry><p> <b>Window group</b>  </p> </entry>
+<entry><p>A window group is special non-displayable type of window,
+which can be considered as the root window of an application. Keyboard
+events and focus are associated with it, and it can have a name, used
+for such things as lists of running applications. A window group is
+provided by <xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita"><apiname>RWindowGroup</apiname></xref>. </p> </entry>
+</row>
+<row>
+<entry><p> <b>Drawable windows</b>  </p> </entry>
+<entry><p>Drawable windows allow applications to draw to the screen.
+They have operations to control size, position, visibility, scrolling,
+z-order, and parent/child relationships. In a standard drawable window,
+areas that become invalid (e.g. when an overlaying window is removed)
+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
+is stored by the Window Server, and redrawn by the server when it
+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
+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>
+</row>
+<row>
+<entry><p> <b>Graphics</b>  </p> </entry>
+<entry><p>Applications draw to drawable windows through a windows
+graphics context provided by a windows graphics device. These implement
+the abstract graphics context and graphics device interfaces respectively,
+as defined in the Graphics API. </p> <p>The windows graphics context
+is provided by <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>; the windows graphics
+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
+Window Server by <xref href="GUID-17150D76-BB82-3A4B-8B1A-8BA93CB1A9EF.dita"><apiname>CWsBitmap</apiname></xref>. </p> </entry>
+</row>
+<row>
+<entry><p> <b>Sprites and cursors</b>  </p> </entry>
+<entry><p>A sprite is an arbitrary-shaped bitmap that can be moved
+without applications having to redraw the underlying screen. It has
+one or more sprite members, each containing a bitmap image and a time
+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,
+which automatically track the position of a pointer. It is provided
+by <xref href="GUID-6E71A7F9-E980-3D99-ACB0-6743A0D13EBF.dita"><apiname>RWsPointerCursor</apiname></xref>. </p> <p>Text cursors are handled
+by the class <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita"><apiname>CTextView</apiname></xref>. They can take the form
+of a text or a line cursor. </p> </entry>
+</row>
+<row>
+<entry><p> <b>Animation client</b>  </p> </entry>
+<entry><p>Third-parties can write Window Server plug-in DLLs, as defined
+in the Animation API, that perform animations. Providers of such animation
+DLLs must also provide a client-side interface to allow applications
+to control the animation. The base class for an animation client-side
+interface is <xref href="GUID-4180CDBA-E9A5-3A4B-9778-26D172FAFD10.dita"><apiname>RAnim</apiname></xref>. </p> <p>Clients must request
+an animation DLL to be loaded before the animations provided by it
+can be used. This is done through <xref href="GUID-800B3667-F45F-391F-A8A9-F876FB4ABC34.dita"><apiname>RAnimDll</apiname></xref>. </p> </entry>
+</row>
+<row>
+<entry><p> <b>Transparent windows</b>  </p> </entry>
+<entry><p>Transparent windows enable you to display semi-transparent
+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>
+</row>
+<row>
+<entry><p> <b>Surfaces</b>  </p> </entry>
+<entry><p>In ScreenPlay, applications (such as games and video) that
+use a rendering API that can potentially benefit from hardware acceleration
+(depending on hardware) can render directly to graphics <i>surfaces</i>. A surface is a hardware independent buffer for holding an image
+or part of a scene. Surfaces are identified using a 128 bit surface
+ID in a <codeph>TSurfaceId</codeph> class.</p> <p>The Window Server
+delegates the composition of surfaces to a composition engine which
+has an adaptation part that enables device creators to take advantage
+of graphics processing hardware if it is available. However, this
+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>
+</row>
+<row>
+<entry><p> <b>Direct Screen Access (DSA)</b>  </p> </entry>
+<entry><p>Mainly used in the non-ScreenPlay variant, DSA enables applications
+that require high frame rates (such as video and games) to bypass
+the Window Server and write to the screen directly. This avoids client-server
+communication and as a result is faster. However, some interaction
+with the Window Server is needed to prevent the application from drawing
+over other application's data. </p> <p>In ScreenPlay, Symbian recommends
+the use of <xref href="GUID-1C025957-258C-54C0-94A5-AD60C14E6D76.dita">external surfaces</xref> in preference to DSA. However, support for
+DSA is maintained for backward compatibility reasons, although there
+are some subtle changes in the support offered.</p><p>ScreenPlay does
+not support the mixing of <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> and DSA rendering
+to the same window. When DSA rendering is present, any <codeph>CWindowGc</codeph> rendering to the same window is ignored. For example, an application
+that uses <codeph>CWindowGC</codeph> rendering in one part of a window
+and DSA rendering in another part will not work as expected in a ScreenPlay
+environment. Similarly, <codeph>CWindowGc</codeph> rendering can no
+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
+until the DSA rendering finishes. It is therefore best to avoid mixing
+the rendering types in the same window.</p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> </section>
+</conbody><related-links>
+<link href="GUID-DC5E8C7D-D697-53E8-87F4-344301430E61.dita"><linktext>Window
+Server Client-Side Library</linktext></link>
+</related-links></concept>
\ No newline at end of file