<?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>