Initial contribution of the Adaptation Documentation.
<?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-E8DF12FC-DCA9-57EA-833A-C1E8D6DAF405" xml:lang="en"><title>Drawing
Tutorial</title><shortdesc>This topic provides tips and code snippets to help you get started
drawing. </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-4123E6D4-0CBA-4244-944B-D472801A4875"><title>Standard windows</title> <p>All drawing to standard windows
must be <xref href="GUID-8DB1C618-597C-560C-95A2-C0AB2CEBB027.dita">redraw drawing</xref>,
which means that it takes place between <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow::BeginRedraw()</apiname></xref> and <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow::EndRedraw()</apiname></xref> calls. If you use the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>CCoeControl::DrawNow()</apiname></xref> and <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>CCoeControl::DrawDeferred()</apiname></xref> methods,
CONE takes care of this for you. </p> <p>To redraw to an <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>,
an application starts the sequence by activating a <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>CWindowGc</apiname></xref> to
use a particular window for drawing, it then calls <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow::BeginRedraw()</apiname></xref> before
issuing the drawing commands and finally calling <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow::EndRedraw()</apiname></xref>.
For example: </p> <codeblock id="GUID-25AE81CE-46CF-5E07-8A94-B35A4A06DAE6" xml:space="preserve">gc->Activate(iWindow);
iWindow.BeginRedraw(rect);
DoDraw(rect);
iWindow.EndRedraw();
gc->Deactivate();</codeblock> <p> <codeph>BeginRedraw()</codeph> does the
following: </p> <ul>
<li id="GUID-2742E046-2511-5C6A-8E84-396A80AFED18"><p>marks the rectangle
passed as its argument as valid (in other words, it removes the rectangle
from the invalid region of the window) </p> </li>
<li id="GUID-4FF89A03-8A77-5640-A77C-943164E869B3"><p>sets the clipping region
to the intersection of the invalid region and the rectangle passed as its
argument. </p> </li>
</ul> <p>In a server-initiated redraw, the drawing must exactly match what
was drawn originally, because the Window Server clips the drawing to the newly
validated region. If the rectangle drawn in response to a redraw event does
not cover the entire invalid region, the Window Server generates another redraw
event specifying the bounding rectangle of the region that is still invalid.
This continues until the entire window is valid. </p> <p>In an application-initiated
redraw, it is good practice to invalidate the whole region before passing
it to the redraw. For example: </p> <codeblock id="GUID-A4213BAF-00A8-5461-86BF-E708DFFC87F1" xml:space="preserve">gc->Activate(iWindow);
iWindow.Invalidate(rect);
iWindow.BeginRedraw(rect);
DoDraw(rect);
iWindow.EndRedraw();
gc->Deactivate();</codeblock> <p>After this sequence, the entire window is
valid. </p> </section>
<section id="GUID-CB59A6EF-AC04-4ACD-B82D-CBAD42975B09"><title>Backed-up windows</title> <p>Backed-up windows are redrawn
by the Window Server from the backup bitmap and not by the application. They
therefore have no <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow::Invalidate()</apiname></xref>, <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow::BeginRedraw()</apiname></xref> or <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow::EndRedraw()</apiname></xref> member
functions. The sequence for drawing to backed-up windows is therefore as follows: </p> <codeblock id="GUID-85C7E7CF-6DF7-5619-B6C3-F9530E316A1C" xml:space="preserve">gc->Activate(iWindow);
DoDraw(rect);
gc->Deactivate();</codeblock> <p> <b>Note</b>: Backed-up windows are deprecated
in Symbian^3. </p> </section>
<section id="GUID-1894D9BE-0B8A-4FF9-9EAB-83D072CF1FDE"><title>Pre-emptive multi tasking</title> <p>Because Symbian is a
pre-emptive system, another application—or the Window Server itself—may pre-empt
the application that is drawing or redrawing. The result is that <codeph>DoDraw()</codeph> may
be partially complete when preemption occurs. Then, when the <codeph>DoDraw()</codeph> receives
control again, it may draw to an area that has been invalidated without its
knowledge. </p> <p>For this reason, the Window Server marks a window region
as valid at <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow::BeginRedraw()</apiname></xref> time, <i>not</i> at <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow::EndRedraw()</apiname></xref> time. Then, any regions that
become invalid because of a preempting application’s activity are correctly
added to the invalid region. The <codeph>DoDraw()</codeph> completes, but
the Window Server generates another redraw event and the application must
start the redraw again. </p> </section>
</conbody><related-links>
<link href="GUID-484B51EC-2209-5492-8E9C-9D792AB0DF35.dita"><linktext>Graphics
and Drawing </linktext></link>
</related-links></concept>