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

    13 Server Client-Side Library Overview</title><shortdesc>The Window Server keeps track of window sizes, positions, visibility

    14 and validity (keeping window content up to date). It also receives and distributes

    15 user input in the form of key presses and 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 Server client-side library details</title> <p>The following

    19 table shows the DLLs that provides the functionality and the library to which

    20 your code must link. </p> <table id="GUID-D5750916-4A95-5944-9ADB-05E35D47592B">

    21 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

    22 <thead>

    23 <row>

    24 <entry>DLL</entry>

    25 <entry>LIB</entry>

    26 <entry>Short description</entry>

    27 </row>

    28 </thead>

    29 <tbody>

    30 <row>

    31 <entry><p> <filepath>ws32_nga.dll</filepath>  </p> </entry>

    32 <entry><p> <filepath>ws32.lib</filepath>  </p> </entry>

    33 <entry><p>The Window Server client-side library for the <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref> variant. </p> </entry>

    34 </row>

    35 <row>

    36 <entry><p> <filepath>ws32_nonnga.dll</filepath>  </p> </entry>

    37 <entry> <p> <filepath>ws32.lib</filepath>  </p></entry>

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

    39 </row>

    40 </tbody>

    41 </tgroup>

    42 </table> <p>The details of the client-side API are very similar in the two

    43 variants. There are some additional features in the ScreenPlay variant for

    44 displaying surfaces.</p> </section>

    45 <section id="GUID-D5B8436F-D7AA-4A72-A967-FC2BB8D8EB0B"><title>Architecture</title> <p>The Window Server is used by all applications

    46 that have a user interface. The primary user input for these applications

    47 comes from the keyboard and pointer, and their primary user-visible output

    48 is to the screen. These input and output devices are shared between all applications

    49 on the system. Each client thread opens a session to the server, and issues

    50 requests for service. </p> <fig id="GUID-4EEE0DBF-A4DC-59A1-8310-504BF05204C7">

    51 <title>              Window Server            </title>

    52 <desc><p>The Window Server controls access by many client applications, to

    53 the machine’s screen, keyboard and pointer. </p> </desc>

    54 <image href="GUID-FE4BBEB4-4E5A-5BF2-A72F-AF53BAD83518_d0e164328_href.png" placement="inline"/>

    55 </fig> <p>The Window Server thread runs at a higher priority than any application;

    56 only the kernel runs at a higher priority. Therefore, all applications' requests

    57 for screen updates, and all handling of machine events such as pointers and

    58 keys, are handled at higher priority than any individual application. </p> <p>Each

    59 client application runs in its own thread. The Window Server presents an interface

    60 to client applications such that they can run without direct interaction with

    61 the other applications on the machine. Drawing is clipped to the visible area

    62 of the application’s windows. Pointer events are only received if they are

    63 related to the application’s windows. Similarly, keyboard events are only

    64 given to an application whose window group has focus or to one that has captured

    65 them. A client application may ignore the majority of events relating to other

    66 applications. It won't even be told about most of them. </p> <p>Each client

    67 application communicates with the Window Server using a Window Server session,

    68 or other object created from the session. The application waits to receive

    69 events by setting up one or more active objects. Events include user input

    70 and requests that windows be redrawn. Applications may create systems of windows

    71 and draw to them. </p> </section>

    72 <section id="GUID-A8BCF1C1-A637-4DDC-9249-BCEF4E23BA06"><title>Window server client-side API</title> <p>The following diagram

    73 shows the key classes in the Window Server client-side library. Below the

    74 diagram we provide a summary of the key concepts. </p> <fig id="GUID-A84A2706-1AF0-598B-976E-0980AD69E6E7">

    75 <title>             Window Server client-side API classes            </title>

    76 <image href="GUID-FEFF353E-DE8A-5FBA-B696-CD01D06BE813_d0e164353_href.png" placement="inline"/>

    77 </fig> <table id="GUID-37EDAB58-6F7B-526A-8E46-891598924120">

    78 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

    79 <thead>

    80 <row>

    81 <entry>Concept</entry>

    82 <entry>Description</entry>

    83 </row>

    84 </thead>

    85 <tbody>

    86 <row>

    87 <entry><p> <b>Session</b>  </p> </entry>

    88 <entry><p>A Window Server session allows an application to control and interrogate

    89 its windows, the events it wishes to receive, and all other window groups

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

    91 </row>

    92 <row>

    93 <entry><p> <b>Events</b>  </p> </entry>

    94 <entry><p>Applications function by waiting for events and handling them. Common

    95 events are user input, and requests that windows be redrawn. The Window Server

    96 session is used to request and obtain events. Most events (such as key and

    97 point events) are encapsulated in <xref href="GUID-5D0B1595-1AC7-3C44-AC6B-0EFB5EABCF31.dita"><apiname>TWsEvent</apiname></xref>. </p> <p>A redraw

    98 event tells the application what screen area needs redrawing. It is encapsulated

    99 in <xref href="GUID-B5F16BF3-569D-3985-AAB7-439E3410468D.dita"><apiname>TWsRedrawEvent</apiname></xref>. </p> </entry>

   100 </row>

   101 <row>

   102 <entry><p> <b>Window group</b>  </p> </entry>

   103 <entry><p>A window group is special non-displayable type of window, which

   104 can be considered as the root window of an application. Keyboard events and

   105 focus are associated with it, and it can have a name, used for such things

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

   107 </row>

   108 <row>

   109 <entry><p> <b>Drawable windows</b>  </p> </entry>

   110 <entry><p>Drawable windows allow applications to draw to the screen. They

   111 have operations to control size, position, visibility, scrolling, z-order,

   112 and parent/child relationships. In a standard drawable window, areas that

   113 become invalid (e.g. when an overlaying window is removed) must be redrawn

   114 by the client application. It is provided by <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>. </p> <p>A

   115 backed-up drawable window's content is stored by the Window Server, and redrawn

   116 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

   117 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>,

   118 and <xref href="GUID-FDF4BB7E-8750-3564-982A-0124A977C82E.dita"><apiname>RDrawableWindow</apiname></xref>. </p> </entry>

   119 </row>

   120 <row>

   121 <entry><p> <b>Graphics</b>  </p> </entry>

   122 <entry><p>Applications draw to drawable windows through a windows graphics

   123 context provided by a windows graphics device. These implement the abstract

   124 graphics context and graphics device interfaces respectively, as defined in

   125 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>;

   126 the windows graphics device by <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref>. The bitmap

   127 class, <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref>, is extended for most efficient use with

   128 the Window Server by <xref href="GUID-17150D76-BB82-3A4B-8B1A-8BA93CB1A9EF.dita"><apiname>CWsBitmap</apiname></xref>. </p> </entry>

   129 </row>

   130 <row>

   131 <entry><p> <b>Sprites and cursors</b>  </p> </entry>

   132 <entry><p>A sprite is an arbitrary-shaped bitmap that can be moved without

   133 applications having to redraw the underlying screen. It has one or more sprite

   134 members, each containing a bitmap image and a time interval for that bitmap

   135 to be displayed. The sprite class is <xref href="GUID-75C09150-E93B-323D-AFBF-E42C7BD78229.dita"><apiname>RWsSprite</apiname></xref>; the sprite

   136 member class is <xref href="GUID-7F4E749E-D08D-3771-A3F1-9AEC5D16B78C.dita"><apiname>TSpriteMember</apiname></xref>. </p> <p>A specialized sprite

   137 type is provided for pointer cursors, which automatically track the position

   138 of a pointer. It is provided by <xref href="GUID-6E71A7F9-E980-3D99-ACB0-6743A0D13EBF.dita"><apiname>RWsPointerCursor</apiname></xref>. </p> <p>Text

   139 cursors are handled by the class <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita"><apiname>CTextView</apiname></xref>. They can take

   140 the form of a text or a line cursor. </p> </entry>

   141 </row>

   142 <row>

   143 <entry><p> <b>Animation client</b>  </p> </entry>

   144 <entry><p>Third-parties can write Window Server plug-in DLLs, as defined in

   145 the Animation API, that perform animations. Providers of such animation DLLs

   146 must also provide a client-side interface to allow applications to control

   147 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

   148 must request an animation DLL to be loaded before the animations provided

   149 by it can be used. This is done through <xref href="GUID-800B3667-F45F-391F-A8A9-F876FB4ABC34.dita"><apiname>RAnimDll</apiname></xref>. </p> </entry>

   150 </row>

   151 <row>

   152 <entry><p> <b>Transparent windows</b>  </p> </entry>

   153 <entry><p>Transparent windows enable you to display semi-transparent bitmaps

   154 on a window. The window must be an <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>. Methods to

   155 create transparent windows can be found in the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> class. </p> </entry>

   156 </row>

   157 <row>

   158 <entry><p> <b>Surfaces</b>  </p> </entry>

   159 <entry><p>In ScreenPlay, applications (such as games and video) that use a

   160 rendering API that can potentially benefit from hardware acceleration (depending

   161 on hardware) can render directly to graphics <i>surfaces</i>. A surface is

   162 a hardware independent buffer for holding an image or part of a scene. Surfaces

   163 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

   164 Window Server delegates the composition of surfaces to a composition engine

   165 which has an adaptation part that enables device creators to take advantage

   166 of graphics processing hardware if it is available. However, this is largely

   167 transparent to application developers. </p> </entry>

   168 </row>

   169 <row>

   170 <entry><p> <b>Direct Screen Access (DSA)</b>  </p> </entry>

   171 <entry><p>Mainly used in the non-ScreenPlay variant, DSA enables applications

   172 that require high frame rates (such as video and games) to bypass the Window

   173 Server and write to the screen directly. This avoids client-server communication

   174 and as a result is faster. However, some interaction with the Window Server

   175 is needed to prevent the application from drawing over other application's

   176 data. </p> <p>In ScreenPlay, Symbian recommends the use of external surfaces

   177 in preference to DSA for most use cases. </p> </entry>

   178 </row>

   179 </tbody>

   180 </tgroup>

   181 </table> </section>

   182 </conbody><related-links>

   183 <link href="GUID-DC5E8C7D-D697-53E8-87F4-344301430E61.dita"><linktext>Window Server

   184 Client-Side Library</linktext></link>

   185 </related-links></concept>