--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-0A13A931-016C-5325-97AF-2DE0B210DF2F.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,185 @@
+<?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_d0e164328_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_d0e164353_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 <xref href="GUID-11F60AEB-003B-3E8D-BDB9-D97F698627DF.dita"><apiname>TSurfaceId</apiname></xref> 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> </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 external surfaces
+in preference to DSA for most use cases. </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