|
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-DC59BEAD-0047-4D7A-96D1-C5E3EC4F982B" xml:lang="en"><title>Drawing |
|
13 in traditional architecture</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The application framework 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>. The 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 |
|
17 first, and then recursively for each control.</p> |
|
18 <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. |
|
19 The override should do nothing else and should be as fast as possible. For |
|
20 example, it is bad design to create fonts dynamically, and read any bitmaps |
|
21 or resources while drawing. A good rule of thumb is that there should not |
|
22 be trap handlers in the method override; any time-consuming functionality |
|
23 that can be done beforehand should be cached.</p> |
|
24 <p>In most cases controls are drawn on the display using the screen device |
|
25 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 |
|
26 Device Interface - common Symbian platform graphics API) drawing primitives |
|
27 that can be used for drawing virtually anything on screen.</p> |
|
28 <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 |
|
29 a top-level window in an application is as follows:</p> |
|
30 <codeblock id="GUID-27363E40-E10A-4399-BF1A-A48305A1DC1B" xml:space="preserve">void CMyAppView::Draw( const TRect& /*aRect*/ ) const |
|
31 { |
|
32 // Get the standard graphics context |
|
33 CWindowGc& gc = SystemGc(); |
|
34 gc.SetPenStyle( CGraphicsContext::ENullPen ); |
|
35 gc.SetBrushColor( KRgbWhite); |
|
36 gc.SetBrushStyle( CGraphicsContext::ESolidBrush ); |
|
37 |
|
38 // Gets the control's extent |
|
39 TRect rect( Rect()); |
|
40 |
|
41 { |
|
42 gc.Clear( rect ); |
|
43 } |
|
44 } |
|
45 </codeblock> |
|
46 <p>, where</p> |
|
47 <ul> |
|
48 <li><p><parmname>CWindowGc& gc = SystemGc();</parmname> gets |
|
49 the graphics context that is used when drawing the control.</p></li> |
|
50 <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> |
|
51 </li> |
|
52 <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 |
|
53 the size of the control rectangle</p></li> |
|
54 <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> |
|
55 </li> |
|
56 </ul> |
|
57 <section id="GUID-F52B945E-F63A-40FC-B7EF-CBA4CFD415E8"><title>Double buffering</title> |
|
58 <p>For controls that perform intensive drawing operations, the drawing |
|
59 should be cached: a process also known as double-buffering. Here the drawing |
|
60 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 |
|
61 bitmap is passed to screen. In the Symbian platform, the easiest way to implement |
|
62 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 |
|
63 then bind a graphics context to that - this makes it possible to use the |
|
64 same GDI interface for drawing as the display context. The drawing is done |
|
65 to a memory bitmap buffer. Double-buffering is a common paradigm used in games, |
|
66 but can also be utilized in any application when performance of drawing controls |
|
67 is important.</p> |
|
68 <p>The following is a short example of how a double buffer is created and |
|
69 used:</p> |
|
70 <codeblock id="GUID-2FA4ADA3-E8F5-4BEE-86C4-40DE748BB91B" xml:space="preserve">iGcBmp = new (ELeave) CWsBitmap(iEikonEnv->WsSession()); |
|
71 User::LeaveIfError(iGcBmp->Create(aClientRect.Size(), iEikonEnv->ScreenDevice()->DisplayMode())); |
|
72 iGcDevice = CFbsBitmapDevice::NewL(iGcBmp); |
|
73 User::LeaveIfError(iGcDevice->CreateBitmapContext(iGc)); |
|
74 </codeblock> |
|
75 <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>, |
|
76 the bitmap memory buffer, that is created with the same width and height as |
|
77 the top-level window and with the same color bit depth as the display.<parmname> iGcDevice</parmname> is |
|
78 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 |
|
79 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 <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> method, when the |
|
80 control draws itself. The double-buffer drawing should be done outside of |
|
81 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 |
|
82 directly when needed. Only at the end of the off-screen drawing is the memory |
|
83 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> |
|
84 <codeblock id="GUID-9474C692-0E2E-4B2C-A218-C4DF99E85C31" xml:space="preserve">void CMyDrawingExample::Draw(const TRect& /*aRect*/) const |
|
85 { |
|
86 SystemGc().BitBlt(TPoint(0, 0), iGcBmp); |
|
87 }</codeblock> |
|
88 </section> |
|
89 </conbody></concept> |