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-E8DF12FC-DCA9-57EA-833A-C1E8D6DAF405" xml:lang="en"><title>Drawing

    13 Tutorial</title><shortdesc>This topic provides tips and code snippets to help you get started

    14 drawing. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

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

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

    17 <section id="GUID-4123E6D4-0CBA-4244-944B-D472801A4875"><title>Standard windows</title> <p>All drawing to standard windows

    18 must be <xref href="GUID-8DB1C618-597C-560C-95A2-C0AB2CEBB027.dita">redraw drawing</xref>,

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

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

    21 an application starts the sequence by activating a <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>CWindowGc</apiname></xref> to

    22 use a particular window for drawing, it then calls <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow::BeginRedraw()</apiname></xref> before

    23 issuing the drawing commands and finally calling <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow::EndRedraw()</apiname></xref>.

    24 For example: </p> <codeblock id="GUID-25AE81CE-46CF-5E07-8A94-B35A4A06DAE6" xml:space="preserve">gc-&gt;Activate(iWindow);

    25 iWindow.BeginRedraw(rect);

    26 DoDraw(rect);

    27 iWindow.EndRedraw();

    28 gc-&gt;Deactivate();</codeblock> <p> <codeph>BeginRedraw()</codeph> does the

    29 following: </p> <ul>

    30 <li id="GUID-2742E046-2511-5C6A-8E84-396A80AFED18"><p>marks the rectangle

    31 passed as its argument as valid (in other words, it removes the rectangle

    32 from the invalid region of the window) </p> </li>

    33 <li id="GUID-4FF89A03-8A77-5640-A77C-943164E869B3"><p>sets the clipping region

    34 to the intersection of the invalid region and the rectangle passed as its

    35 argument. </p> </li>

    36 </ul> <p>In a server-initiated redraw, the drawing must exactly match what

    37 was drawn originally, because the Window Server clips the drawing to the newly

    38 validated region. If the rectangle drawn in response to a redraw event does

    39 not cover the entire invalid region, the Window Server generates another redraw

    40 event specifying the bounding rectangle of the region that is still invalid.

    41 This continues until the entire window is valid. </p> <p>In an application-initiated

    42 redraw, it is good practice to invalidate the whole region before passing

    43 it to the redraw. For example: </p> <codeblock id="GUID-A4213BAF-00A8-5461-86BF-E708DFFC87F1" xml:space="preserve">gc-&gt;Activate(iWindow);

    44 iWindow.Invalidate(rect);

    45 iWindow.BeginRedraw(rect);

    46 DoDraw(rect);

    47 iWindow.EndRedraw();

    48 gc-&gt;Deactivate();</codeblock> <p>After this sequence, the entire window is

    49 valid. </p> </section>

    50 <section id="GUID-CB59A6EF-AC04-4ACD-B82D-CBAD42975B09"><title>Backed-up windows</title> <p>Backed-up windows are redrawn

    51 by the Window Server from the backup bitmap and not by the application. They

    52 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

    53 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-&gt;Activate(iWindow);

    54 DoDraw(rect);

    55 gc-&gt;Deactivate();</codeblock> <p> <b>Note</b>: Backed-up windows are deprecated

    56 in Symbian^3. </p> </section>

    57 <section id="GUID-1894D9BE-0B8A-4FF9-9EAB-83D072CF1FDE"><title>Pre-emptive multi tasking</title> <p>Because Symbian is a

    58 pre-emptive system, another application—or the Window Server itself—may pre-empt

    59 the application that is drawing or redrawing. The result is that <codeph>DoDraw()</codeph> may

    60 be partially complete when preemption occurs. Then, when the <codeph>DoDraw()</codeph> receives

    61 control again, it may draw to an area that has been invalidated without its

    62 knowledge. </p> <p>For this reason, the Window Server marks a window region

    63 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

    64 become invalid because of a preempting application’s activity are correctly

    65 added to the invalid region. The <codeph>DoDraw()</codeph> completes, but

    66 the Window Server generates another redraw event and the application must

    67 start the redraw again. </p> </section>

    68 </conbody><related-links>

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

    70 and Drawing </linktext></link>

    71 </related-links></concept>