<?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-7C75642D-C0C9-5392-9354-711F42DC2C61" xml:lang="en"><title>Server-Initiated

vs. Application-Initiated Redrawing</title><shortdesc>This topic introduces the reasons that the screen display may need

to be updated and the difference between redrawing that is initiated by an

application and that initiated by the Window Server. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p> <b>Variant</b>: Both (ScreenPlay and non-ScreenPlay). <b>Target

audience</b>: Application developers. </p>

<section id="GUID-D5FE0214-ECEB-4C0F-84C9-2BB44C19E477"><title>Introduction</title> <p>The Window Server maintains the UI

display taking into account the region, ordinal position and visibility requirements

of all displayable windows. The UI may be updated for several reasons: </p> <ul>

<li id="GUID-017DF20B-5881-5B8A-A8A3-0019614535B7"><p>at direct application

request by an application drawing to a window through a <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>  </p> </li>

<li id="GUID-8B9CFD40-0ECB-5F0D-92BA-F8EB327B31CA"><p>due to regions of the

display becoming invalid </p> </li>

<li id="GUID-6F5C9D10-BCE4-5F60-9F85-BE69C4C58F2C"><p>due to actions internal

to the Window Server, such as pointer cursor movements. </p> </li>

</ul> <p>When a window is moved, resized, or otherwise manipulated by an application,

it may cause parts of other windows to become invalid so that they must be

redrawn. The Window Server maintains a list of all invalid regions and causes

them to be redrawn in one of several ways: </p> <ul>

<li id="GUID-2FFC86C2-0971-539B-BD21-E95E9FEB4202"><p>for a region with no

window, the Window Server redraws the invalid region in the default background

color </p> </li>

<li id="GUID-B0289B7D-97E2-5FBD-9983-130A5109FDFF"><p>for a blank window,

the Window Server redraws the invalid region in the window's color </p> </li>

<li id="GUID-931BDE7B-4C56-5350-A26B-F89CCBA72DE6"><p>for a backed-up window,

the invalid region is redrawn from a backup bitmap maintained by the Window

Server </p> </li>

<li id="GUID-24155452-0F5D-508E-B04D-96E06FD0913F"><p>if the invalid region

is owned by an animation DLL, the Window Server invokes the animation DLL

directly to redraw the area: the region is then valid again </p> </li>

<li id="GUID-2A5080AF-1415-5CBF-B775-D547D9C3F222"><p>for a normal <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>,

whenever possible, the Window Server replays the sequence of drawing commands

stored in the redraw stores. However, sometimes this is not possible, because,

for example, the redraw stores have been lost due to low memory conditions.

In these circumstances, the Window Server generates a redraw event and sends

it to the application. This is described in more detail below. </p> </li>

</ul> </section>

<section id="GUID-50054B7B-FF18-40B2-A582-B90FE66D269F"><title>Window Server-initiated redrawing</title> <p>When the Window

Server needs to repaint a standard <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> window and it

is not possible to do this by replaying the drawing commands stored in the

redraw stores, it sends a <xref href="GUID-B5F16BF3-569D-3985-AAB7-439E3410468D.dita"><apiname>TWsRedrawEvent</apiname></xref> message to the

client. </p> <p>It is part of the client's contract with the Window Server

to listen for these events and respond to them by performing a redraw. The

normal way for a client application to do this is through an active object,

which is sometimes called a <b>redrawer</b>. This is normally provided by

the application framework and should have a lower priority than the active

objects for standard events. The client issues an asynchronous request for

the next redraw event, calling the <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-DADAFFD6-4B63-35EE-8F50-F397C119CC27"><apiname>RWsSession::RedrawReady()</apiname></xref> function. </p> <p>The

redrawer's <xref href="GUID-12C281FF-546C-318D-8783-F26B0F619E11.dita"><apiname>RunL()</apiname></xref> function (which handles the completed

request) calls <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-6008C20D-AA95-3803-8B57-54948FA61616"><apiname>RWsSession::GetRedraw()</apiname></xref>. This gets the <xref href="GUID-B5F16BF3-569D-3985-AAB7-439E3410468D.dita"><apiname>TWsRedrawEvent</apiname></xref>,

which contains the handle of the window and the rectangle within it that needs

to be redrawn and then does the redraw. This involves: </p> <ol id="GUID-078DF0F5-E856-5FFF-ADEB-1A09B4BBDFB0">

<li id="GUID-75A15778-D570-5B5D-A07E-5660FFCAB00F"><p>Calling <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-9337538E-7A53-3153-A330-968B5E4F2FF2"><apiname>RWindow::BeginRedraw()</apiname></xref> on

the relevant window and passing in the rectangle. </p> </li>

<li id="GUID-C63A002A-B433-5054-BD73-0368E2FB6C1B"><p>Issuing the <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> drawing

commands that define how to draw the area of the window specified by the rectangle

passed in the <xref href="GUID-B5F16BF3-569D-3985-AAB7-439E3410468D.dita"><apiname>TWsRedrawEvent</apiname></xref>. These drawing commands must

exactly match what was drawn originally, because the Window Server clips the

drawing to the passed rectangle. </p> </li>

<li id="GUID-AA03D7DD-0B8A-5241-87B1-D45BC8AAA369"><p>Calling <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-3DE16607-AD3B-3946-BEB3-88512EAAB9CE"><apiname>RWindow::EndRedraw()</apiname></xref>. </p> </li>

</ol> <p>At the end of the redrawer’s <xref href="GUID-12C281FF-546C-318D-8783-F26B0F619E11.dita"><apiname>RunL()</apiname></xref>, a call is

made to <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-DADAFFD6-4B63-35EE-8F50-F397C119CC27"><apiname>RWsSession::RedrawReady()</apiname></xref> to enable the client

to listen for further requests from the Window Server. </p> <p>The following

diagram demonstrates that typically the <xref href="GUID-12C281FF-546C-318D-8783-F26B0F619E11.dita"><apiname>RunL()</apiname></xref> starts with

a <xref href="GUID-C57CFECB-72CD-39EB-A83E-82A9E985F56B.dita"><apiname>GetRedraw()</apiname></xref> and ends with a call to <xref href="GUID-E3F0CB70-58E4-32FD-9828-71DF2F9976D3.dita"><apiname>RedrawReady()</apiname></xref>. </p> <fig id="GUID-B092D136-8C18-5237-A095-F8C3BBFFDDB4">

<title>              Window Server-initiated redraw            </title>

<image href="GUID-0528A294-AC1B-5CDD-B59C-A105F39D748F_d0e195211_href.png" placement="inline"/>

</fig> <p>A redrawer's <codeph>RunL()</codeph> function must <b>not</b> perform

any non-redraw drawing (that is, any drawing operations that are not bracketed

within the calls to <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph>).

If it does, this causes a panic with code 79 (<codeph>EWservPanicWindowBeginRedrawNotCalled</codeph>)

in the ScreenPlay variant. This is to avoid the infinite loop that would otherwise

be caused by an endless cycle of the non-redraw drawing within the <codeph>RunL()</codeph> triggering

a Window Server-initiated redraw. </p> </section>

<section id="GUID-0238F737-3D2B-4811-8E46-561922210143"><title>Application-initiated redrawing</title> <p>An application

initiates redrawing when it wants to update the UI to reflect a change of

state. There are two scenarios, which we describe under separate headings

below. </p> <p><b>The "draw now" scenario </b> </p> <p>The "draw now" redraw scenario is

when an application wants to push a state change to a window immediately.

Typically the application does this by calling <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-D5458F8C-E199-37DD-B821-050B749122C6"><apiname>CCoeControl::DrawNow()</apiname></xref>.

However, it is possible to achieve the same results using <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> and <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> calls

directly. To illustrate how to do this, consider a digital clock application

that updates the time displayed in the window from 12:02 to 12:03. </p> <p>The

application does the following: </p> <ol id="GUID-D9D43E2B-B29D-5C6F-A1AB-ABA192D3D562">

<li id="GUID-C59E802D-0D4F-595B-9F1C-BED1090EE7D7"><p>Calls <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-28202F81-52FE-30F5-8B8C-ABED0915822E"><apiname>RWindow::Invalidate()</apiname></xref>,

optionally passing in the bounding rectangle. When called without passing

in a rectangle, this function invalidates the entire window. </p> </li>

<li id="GUID-491CB745-6B47-5656-874E-A87DE1BE6254"><p>Calls <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-9337538E-7A53-3153-A330-968B5E4F2FF2"><apiname>RWindow::BeginRedraw()</apiname></xref>.

If the application passed a bounding rectangle to <codeph>Invalidate()</codeph>,

it must pass the same bounding rectangle to <codeph>BeginRedraw()</codeph>.

If the application did not pass a bounding rectangle to <codeph>Invalidate()</codeph>,

it must not pass one to BeginRedraw(). </p> </li>

<li id="GUID-8CA69A7D-0387-5604-9C10-983FB50514B5"><p>Issues the <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> draw

commands. </p> </li>

<li id="GUID-B2474EE6-CC03-55A8-9972-071B76512B26"><p>Calls <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-3DE16607-AD3B-3946-BEB3-88512EAAB9CE"><apiname>RWindow::EndRedraw()</apiname></xref>. </p> </li>

</ol> <fig id="GUID-6E2637DC-F92A-56DE-BB07-F109F5CA681B">

<title>              Application-initiated redrawing, "draw now" scenario

           </title>

<image href="GUID-4BC95F70-2F3F-5CFE-B057-0C5A97430573_d0e195319_href.png" placement="inline"/>

</fig> <p><b>The "draw deferred" scenario </b> </p> <p>The "draw deferred" redraw scenario

is when an application simply marks a window or a rectangle within a window

as invalid. This eventually triggers a Window Server-initiated redraw. Typically

the application does this by calling <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-9FB682AC-0209-302A-83F3-7BCB1162B998"><apiname>CCoeControl::DrawDeferred()</apiname></xref>.

However, it is also possible to do this by calling <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-28202F81-52FE-30F5-8B8C-ABED0915822E"><apiname>RWindow::Invalidate()</apiname></xref>. </p> <fig id="GUID-8B78CE09-EE92-50B3-8000-731BD9C20890">

<title>              Application-initiated redrawing, "draw deferred" scenario

           </title>

<image href="GUID-21EF9E6F-A0BF-5EB2-9E3F-CA6A011D4C89_d0e195343_href.png" placement="inline"/>

</fig> <p>This approach is useful when the data to be displayed might be updated

frequently but it is not necessary to update the display instantaneously. </p> <p>To

illustrate how it works, consider a window that has a rectangle that is used

to display icons (a star, a cross and a triangle) that represent three different

events that can occur in the application. Suppose the events can occur in

quick succession. If you use the "draw now" approach when each event occurs,

the Window Server updates the display separately for each one, as shown in

the following diagram. </p> <fig id="GUID-04BCFA21-8D44-5FEA-BE29-57B40AC9CF99">

<title>              Icons displayed using the "draw now" approach       

    </title>

<image href="GUID-89185EBD-223F-5F52-B1CA-9F9692F7D21F_d0e195357_href.png" placement="inline"/>

</fig> <p>However, if you use the "draw deferred" approach when each event

occurs, the Window Server may not update the display for each one. For example,

the Window Server does not update the display when it is superceded by a later

call. </p> <fig id="GUID-1E0E2A3C-1E63-58F6-940F-0D439FA6C721">

<title>              Icons displayed using the "draw deferred" approach  

         </title>

<image href="GUID-EDC405DC-F222-59CD-836E-180F8E1D2D11_d0e195368_href.png" placement="inline"/>

</fig> <p>If it is important that the display is updated immediately, you

would generally use the "draw now" approach. However, if a short delay in

the display being updated is unlikely to inconvenience the user, the "draw

deferred" approach might be appropriate and has a performance advantage. </p> </section>

</conbody><related-links>

<link href="GUID-484B51EC-2209-5492-8E9C-9D792AB0DF35.dita"><linktext>Graphics

and Drawing </linktext></link>

</related-links></concept>