|
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="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aDraw%28const%20TRect%20%26amp%3b%29const" format="application/java-archive"><parmname>CCoeControl::Draw</parmname></xref> when a control area needs |
|
15 to be updated on the display. Controls may implement <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aDraw%28const%20TRect%20%26amp%3b%29const" format="application/java-archive"><parmname>CCoeControl::Draw</parmname></xref> or leave the drawing |
|
16 to their child controls. For more information on control hierarchies, see <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/guide/Application-Framework-subsystem-guide/UIControlFrameworkGuide/UIControlFrameworkGuide2/RunTimeControlHierarchy.guide.html" format="application/java-archive">The run-time control hierarchy</xref>. </p> |
|
17 <p>The Symbian platform calls <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aDraw%28const%20TRect%20%26amp%3b%29const" format="application/java-archive"><parmname>CCoeControl::Draw</parmname></xref> for the parent control |
|
18 first, and then recursively for each control.</p> |
|
19 <p>Controls should override <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aDraw%28const%20TRect%20%26amp%3b%29const" format="application/java-archive"><parmname>CCoeControl::Draw</parmname></xref> to draw their content. |
|
20 The override should do nothing else and should be as fast as possible. For |
|
21 example, it is bad design to create fonts dynamically, and read any bitmaps |
|
22 or resources while drawing. A good rule of thumb is that there should not |
|
23 be trap handlers in the method override; any time-consuming functionality |
|
24 that can be done beforehand should be cached.</p> |
|
25 <p>In most cases controls are drawn on the display using the screen device |
|
26 graphics context, accessed with <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aSystemGc%28%29const" format="application/java-archive"><parmname>CCoeControl::SystemGc()</parmname></xref>. The graphics context provides a wide set of <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/GDI/index.html" format="application/java-archive">GDI</xref> (Graphics |
|
27 Device Interface - common Symbian platform graphics API) drawing primitives |
|
28 that can be used for drawing virtually anything on screen.</p> |
|
29 <p>An example of a basic override of <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aDraw%28const%20TRect%20%26amp%3b%29const" format="application/java-archive"><parmname>CCoeControl::Draw</parmname></xref> for a control that is |
|
30 a top-level window in an application is as follows:</p> |
|
31 <codeblock id="GUID-9EF298F3-9B92-48C1-BA7C-0C91143D075C" xml:space="preserve">void CMyAppView::Draw( const TRect& /*aRect*/ ) const |
|
32 { |
|
33 // Get the standard graphics context |
|
34 CWindowGc& gc = SystemGc(); |
|
35 gc.SetPenStyle( CGraphicsContext::ENullPen ); |
|
36 gc.SetBrushColor( KRgbWhite); |
|
37 gc.SetBrushStyle( CGraphicsContext::ESolidBrush ); |
|
38 |
|
39 // Gets the control's extent |
|
40 TRect rect( Rect()); |
|
41 |
|
42 { |
|
43 gc.Clear( rect ); |
|
44 } |
|
45 } |
|
46 </codeblock> |
|
47 <p>, where</p> |
|
48 <ul> |
|
49 <li><p><parmname>CWindowGc& gc = SystemGc();</parmname> gets |
|
50 the graphics context that is used when drawing the control.</p></li> |
|
51 <li><p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Window_Server/CWindowGcClass.html#%3a%3aCWindowGc%3a%3aSetPenStyle%28TPenStyle%29" format="application/java-archive"><parmname>CWindowGc::SetPenStyle</parmname></xref>, <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Window_Server/CWindowGcClass.html#%3a%3aCWindowGc%3a%3aSetBrushColor%28const%20TRgb%20%26amp%3b%29" format="application/java-archive"><parmname>CWindowGc::SetBrushColor</parmname></xref>, and <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Window_Server/CWindowGcClass.html#%3a%3aCWindowGc%3a%3aSetBrushStyle%28TBrushStyle%29" format="application/java-archive"><parmname>CWindowGc::SetBrushStyle</parmname></xref> are used to set the drawing primatives for the context.</p> |
|
52 </li> |
|
53 <li><p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Kernel_Architecture_2/TRectClass.html" format="application/java-archive"><parmname>TRect</parmname></xref> gets |
|
54 the size of the control rectangle.</p></li> |
|
55 <li><p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Window_Server/CWindowGcClass.html#%3a%3aCWindowGc%3a%3aClear%28const%20TRect%20%26amp%3b%29" format="application/java-archive"><parmname>CWindowGc:Clear(rect)</parmname></xref> clears the control rectangle.</p> |
|
56 </li> |
|
57 </ul> |
|
58 <section id="GUID-DBACBFCC-F260-4ABE-B55C-BBB23F332E42"><title>Drawing with |
|
59 caches</title> |
|
60 <p>For controls that perform intensive drawing operations, the drawing |
|
61 should be cached: a process also known as double-buffering. Here the drawing |
|
62 is done to a memory context first and then in the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aDraw%28const%20TRect%20%26amp%3b%29const" format="application/java-archive"><parmname>CCoeControl::Draw</parmname></xref> method only the context's |
|
63 bitmap is passed to screen. In the Symbian platform, the easiest way to implement |
|
64 a double buffer is to create a <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Font_and_Bitmap_Server/CFbsBitmapClass.html" format="application/java-archive"><parmname>CFbsBitmap</parmname></xref> and |
|
65 then bind a graphics context to that - this makes it possible to use the |
|
66 same GDI interface for drawing as the display context. The drawing is done |
|
67 to a memory bitmap buffer, and when the Symbian platform updates the invalidated |
|
68 screen area, the memory buffer is copied to it. Double-buffering is a common |
|
69 paradigm used in games, but can also be utilized in any application when performance |
|
70 of drawing controls is important.</p> |
|
71 <p>The following is a short example of how a double buffer is created and |
|
72 used:</p> |
|
73 <codeblock id="GUID-995DBACE-EE60-4666-BDCF-975EE98B01FD" xml:space="preserve">iGcBmp = new (ELeave) CWsBitmap(iEikonEnv->WsSession()); |
|
74 User::LeaveIfError(iGcBmp->Create(aClientRect.Size(), iEikonEnv->ScreenDevice()->DisplayMode())); |
|
75 iGcDevice = CFbsBitmapDevice::NewL(iGcBmp); |
|
76 User::LeaveIfError(iGcDevice->CreateBitmapContext(iGc)); |
|
77 </codeblock> |
|
78 <p><parmname>iGcBmp</parmname> is a pointer to <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Window_Server/CWsBitmapClass.html" format="application/java-archive"><parmname>CWsBitmap</parmname></xref>, |
|
79 the bitmap memory buffer, that is created with the same width and height as |
|
80 the top-level window and with the same color bit depth as the display.<parmname> iGcDevice</parmname> is |
|
81 a pointer to the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/GDI/CBitmapDeviceClass.html" format="application/java-archive"><parmname>CBitmapDevice</parmname></xref> device |
|
82 class and the context <parmname>iGc</parmname> holds the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/GDI/CBitmapContextClass.html" format="application/java-archive"><parmname>CBitmapContext</parmname></xref> instance. <parmname>iGc</parmname> is then used instead of <parmname>CScreenGc</parmname>, obtained from the <parmname>CCoeControl::SystemGc()</parmname> method, |
|
83 when the control draws itself. The double-buffer drawing should be done outside |
|
84 of the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aDraw%28const%20TRect%20%26amp%3b%29const" format="application/java-archive"><parmname>CCoeControl::Draw</parmname></xref> method and can be called |
|
85 directly when needed. Only at the end of the off-screen drawing is the memory |
|
86 buffer flushed to the screen by calling <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aDrawDeferred%28%29const" format="application/java-archive"><parmname>CCoeControl::DrawDeferred()</parmname></xref></p> |
|
87 <codeblock id="GUID-13A1E553-7A78-422C-85AC-7C89696B2D18" xml:space="preserve">void CMyDrawingExample::Draw(const TRect& /*aRect*/) const |
|
88 { |
|
89 SystemGc().BitBlt(TPoint(0, 0), iGcBmp); |
|
90 }</codeblock> |
|
91 </section> |
|
92 </conbody></concept> |