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-C6E9D609-E82C-4FAC-9265-F6A4FF61049C" xml:lang="en"><title>Drawing

    13 in the view architecture</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>The Symbian platform calls <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-63295719-90A0-3D53-A643-0C52BF4068A1"><apiname>CCoeControl::Draw()</apiname></xref> when

    15 a control area needs to be updated on the display. Controls may implement <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-63295719-90A0-3D53-A643-0C52BF4068A1"><apiname>CCoeControl::Draw()</apiname></xref> or

    16 leave the drawing to their child controls. For more information on control

    17 hierarchies, see <xref href="GUID-E244744F-4837-5B46-8E37-4666A28BF0B7-GENID-1-8-1-3-1-1-7-1-7-1-5-1.dita">The

    18 run-time control hierarchy</xref>. </p>

    19 <p>The Symbian platform calls <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-63295719-90A0-3D53-A643-0C52BF4068A1"><apiname>CCoeControl::Draw()</apiname></xref> for

    20 the parent control first, and then recursively for each control.</p>

    21 <p>Controls should override <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-63295719-90A0-3D53-A643-0C52BF4068A1"><apiname>CCoeControl::Draw()</apiname></xref> to draw

    22 their content. The override should do nothing else and should be as fast as

    23 possible. For example, it is bad design to create fonts dynamically, and read

    24 any bitmaps or resources while drawing. A good rule of thumb is that there

    25 should not be trap handlers in the method override; any time-consuming functionality

    26 that can be done beforehand should be cached.</p>

    27 <p>In most cases controls are drawn on the display using the screen device

    28 graphics context, accessed with <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-6586DB74-AF5C-330B-9D0A-E4637396A04E"><apiname>CCoeControl::SystemGc()</apiname></xref>.

    29 The graphics context provides a wide set of <xref href="GUID-E89F034F-C807-5FF9-B06B-F7CCD2441041.dita">GDI</xref> (Graphics

    30 Device Interface  - common Symbian platform graphics API) drawing primitives

    31 that can be used for drawing virtually anything on screen.</p>

    32 <p>An example of a basic override of <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-63295719-90A0-3D53-A643-0C52BF4068A1"><apiname>CCoeControl::Draw()</apiname></xref> for

    33 a control that is a top-level window in an application is as follows:</p>

    34 <codeblock id="GUID-9EF298F3-9B92-48C1-BA7C-0C91143D075C" xml:space="preserve">void CMyAppView::Draw( const TRect&amp; /*aRect*/ ) const

    35     {

    36     // Get the standard graphics context

    37     CWindowGc& gc = SystemGc();

    38     gc.SetPenStyle( CGraphicsContext::ENullPen );

    39     gc.SetBrushColor( KRgbWhite);

    40     gc.SetBrushStyle( CGraphicsContext::ESolidBrush );

    41 

    42     // Gets the control's extent

    43     TRect rect( Rect());

    44 

    45         {

    46         gc.Clear( rect );

    47         }

    48     }

    49 </codeblock>

    50 <p>, where</p>

    51 <ul>

    52 <li><p><parmname>CWindowGc&amp; gc = SystemGc();</parmname> gets

    53 the graphics context that is used when drawing the control.</p></li>

    54 <li><p><xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita#GUID-0AEE5955-C530-35F1-A904-69183331B294/GUID-026A1015-0D79-3A66-91BA-5FB343387EE0"><apiname>CWindowGc::SetPenStyle()</apiname></xref>, <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita#GUID-0AEE5955-C530-35F1-A904-69183331B294/GUID-0A923CAA-7A89-3ED2-A844-2F4147B62FEC"><apiname>CWindowGc::SetBrushColor()</apiname></xref>,

    55 and <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita#GUID-0AEE5955-C530-35F1-A904-69183331B294/GUID-363A9FB3-75F7-3EB7-A783-91BBAEBCE670"><apiname>CWindowGc::SetBrushStyle()</apiname></xref> are used to set the drawing

    56 primatives for the context.</p></li>

    57 <li><p><xref href="GUID-101762DC-E498-3325-88AB-B0FF17DC62B6.dita"><apiname>TRect</apiname></xref> gets the size of the control rectangle.</p>

    58 </li>

    59 <li><p><xref href="GUID-D22FD07E-59E0-346A-9BFA-8D109F509DB1.dita"><apiname>CWindowGc:Clear(rect)</apiname></xref> clears the control

    60 rectangle.</p></li>

    61 </ul>

    62 <section id="GUID-DBACBFCC-F260-4ABE-B55C-BBB23F332E42"><title>Drawing with

    63 caches</title>

    64 <p>For controls that perform intensive drawing operations, the drawing

    65 should be cached: a process also known as double-buffering. Here the drawing

    66 is done to a memory context first and then in the <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-63295719-90A0-3D53-A643-0C52BF4068A1"><apiname>CCoeControl::Draw()</apiname></xref> method

    67 only the context's bitmap is passed to screen. In the Symbian platform, the

    68 easiest way to implement a double buffer is to create a <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> and

    69 then bind a graphics context to that  - this makes it possible to use the

    70 same GDI interface for drawing as the display context. The drawing is done

    71 to a memory bitmap buffer, and when the Symbian platform updates the invalidated

    72 screen area, the memory buffer is copied to it. Double-buffering is a common

    73 paradigm used in games, but can also be utilized in any application when performance

    74 of drawing controls is important.</p>

    75 <p>The following is a short example of how a double buffer is created and

    76 used:</p>

    77 <codeblock id="GUID-995DBACE-EE60-4666-BDCF-975EE98B01FD" xml:space="preserve">iGcBmp = new (ELeave) CWsBitmap(iEikonEnv-&gt;WsSession());

    78 User::LeaveIfError(iGcBmp->Create(aClientRect.Size(), iEikonEnv->ScreenDevice()->DisplayMode()));

    79 iGcDevice = CFbsBitmapDevice::NewL(iGcBmp);

    80 User::LeaveIfError(iGcDevice->CreateBitmapContext(iGc));

    81 </codeblock>

    82 <p><parmname>iGcBmp</parmname> is a pointer to <xref href="GUID-17150D76-BB82-3A4B-8B1A-8BA93CB1A9EF.dita"><apiname>CWsBitmap</apiname></xref>,

    83 the bitmap memory buffer, that is created with the same width and height as

    84 the top-level window and with the same color bit depth as the display.<parmname> iGcDevice</parmname> is

    85 a pointer to the <xref href="GUID-2DEFEC47-F36E-3133-A08D-55F7C2534CC0.dita"><apiname>CBitmapDevice</apiname></xref> device class and the context <parmname>iGc</parmname> holds

    86 the <xref href="GUID-FC746873-0570-3900-AD89-42B205FDC0D3.dita"><apiname>CBitmapContext</apiname></xref> instance. <parmname>iGc</parmname> is

    87 then used instead of <parmname>CScreenGc</parmname>, obtained from the <parmname>CCoeControl::SystemGc()</parmname> method,

    88 when the control draws itself. The double-buffer drawing should be done outside

    89 of the <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-63295719-90A0-3D53-A643-0C52BF4068A1"><apiname>CCoeControl::Draw()</apiname></xref> method and can be called directly

    90 when needed. Only at the end of the off-screen drawing is the memory buffer

    91 flushed to the screen 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></p>

    92 <codeblock id="GUID-13A1E553-7A78-422C-85AC-7C89696B2D18" xml:space="preserve">void CMyDrawingExample::Draw(const TRect&amp; /*aRect*/) const

    93     {

    94     SystemGc().BitBlt(TPoint(0, 0), iGcBmp);

    95     }</codeblock>

    96 </section>

    97 </conbody></concept>