9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept id="GUID-DC59BEAD-0047-4D7A-96D1-C5E3EC4F982B" xml:lang="en"><title>Drawing |
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> |
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 |
14 <p>The application framework 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 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 |
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 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 |
16 leave the drawing to their child controls. For more information on control |
17 first, and then recursively for each control.</p> |
17 hierarchies, see <xref href="GUID-E244744F-4837-5B46-8E37-4666A28BF0B7-GENID-1-10-1-3-1-1-7-1-7-1-5-1.dita">The |
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. |
18 run-time control hierarchy</xref>. The 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 |
19 The override should do nothing else and should be as fast as possible. For |
19 the parent control first, and then recursively for each control.</p> |
20 example, it is bad design to create fonts dynamically, and read any bitmaps |
20 <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 |
21 or resources while drawing. A good rule of thumb is that there should not |
21 their content. The override should do nothing else and should be as fast as |
22 be trap handlers in the method override; any time-consuming functionality |
22 possible. For example, it is bad design to create fonts dynamically, and read |
|
23 any bitmaps or resources while drawing. A good rule of thumb is that there |
|
24 should not be trap handlers in the method override; any time-consuming functionality |
23 that can be done beforehand should be cached.</p> |
25 that can be done beforehand should be cached.</p> |
24 <p>In most cases controls are drawn on the display using the screen device |
26 <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 |
27 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>. |
|
28 The graphics context provides a wide set of <xref href="GUID-E89F034F-C807-5FF9-B06B-F7CCD2441041.dita">GDI</xref> (Graphics |
26 Device Interface - common Symbian platform graphics API) drawing primitives |
29 Device Interface - common Symbian platform graphics API) drawing primitives |
27 that can be used for drawing virtually anything on screen.</p> |
30 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 |
31 <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 |
29 a top-level window in an application is as follows:</p> |
32 a control that is 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 |
33 <codeblock id="GUID-27363E40-E10A-4399-BF1A-A48305A1DC1B" xml:space="preserve">void CMyAppView::Draw( const TRect& /*aRect*/ ) const |
31 { |
34 { |
32 // Get the standard graphics context |
35 // Get the standard graphics context |
33 CWindowGc& gc = SystemGc(); |
36 CWindowGc& gc = SystemGc(); |
34 gc.SetPenStyle( CGraphicsContext::ENullPen ); |
37 gc.SetPenStyle( CGraphicsContext::ENullPen ); |
45 </codeblock> |
48 </codeblock> |
46 <p>, where</p> |
49 <p>, where</p> |
47 <ul> |
50 <ul> |
48 <li><p><parmname>CWindowGc& gc = SystemGc();</parmname> gets |
51 <li><p><parmname>CWindowGc& gc = SystemGc();</parmname> gets |
49 the graphics context that is used when drawing the control.</p></li> |
52 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> |
53 <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>, |
|
54 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 |
|
55 primatives for the context</p></li> |
|
56 <li><p><xref href="GUID-101762DC-E498-3325-88AB-B0FF17DC62B6.dita"><apiname>TRect</apiname></xref> gets the size of the control rectangle</p> |
51 </li> |
57 </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 |
58 <li><p><xref href="GUID-D22FD07E-59E0-346A-9BFA-8D109F509DB1.dita"><apiname>CWindowGc:Clear(rect)</apiname></xref> clears the control |
53 the size of the control rectangle</p></li> |
59 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> |
60 </ul> |
57 <section id="GUID-F52B945E-F63A-40FC-B7EF-CBA4CFD415E8"><title>Double buffering</title> |
61 <section id="GUID-F52B945E-F63A-40FC-B7EF-CBA4CFD415E8"><title>Double buffering</title> |
58 <p>For controls that perform intensive drawing operations, the drawing |
62 <p>For controls that perform intensive drawing operations, the drawing |
59 should be cached: a process also known as double-buffering. Here the drawing |
63 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 |
64 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 |
61 bitmap is passed to screen. In the Symbian platform, the easiest way to implement |
65 only the context's bitmap is passed to screen. In the Symbian platform, the |
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 |
66 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 |
63 then bind a graphics context to that - this makes it possible to use the |
67 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 |
68 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, |
69 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 |
70 but can also be utilized in any application when performance of drawing controls |
67 is important.</p> |
71 is important.</p> |
70 <codeblock id="GUID-2FA4ADA3-E8F5-4BEE-86C4-40DE748BB91B" xml:space="preserve">iGcBmp = new (ELeave) CWsBitmap(iEikonEnv->WsSession()); |
74 <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())); |
75 User::LeaveIfError(iGcBmp->Create(aClientRect.Size(), iEikonEnv->ScreenDevice()->DisplayMode())); |
72 iGcDevice = CFbsBitmapDevice::NewL(iGcBmp); |
76 iGcDevice = CFbsBitmapDevice::NewL(iGcBmp); |
73 User::LeaveIfError(iGcDevice->CreateBitmapContext(iGc)); |
77 User::LeaveIfError(iGcDevice->CreateBitmapContext(iGc)); |
74 </codeblock> |
78 </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>, |
79 <p><parmname>iGcBmp</parmname> is a pointer to <xref href="GUID-17150D76-BB82-3A4B-8B1A-8BA93CB1A9EF.dita"><apiname>CWsBitmap</apiname></xref>, |
76 the bitmap memory buffer, that is created with the same width and height as |
80 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 |
81 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 |
82 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 |
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 |
83 the <xref href="GUID-FC746873-0570-3900-AD89-42B205FDC0D3.dita"><apiname>CBitmapContext</apiname></xref> instance. <parmname>iGc</parmname> is |
80 control draws itself. The double-buffer drawing should be done outside of |
84 then used instead of <parmname>CScreenGc</parmname>, obtained from the <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> method, |
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 |
85 when the control draws itself. The double-buffer drawing should be done outside |
82 directly when needed. Only at the end of the off-screen drawing is the memory |
86 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 |
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> |
87 when needed. Only at the end of the off-screen drawing is the memory buffer |
|
88 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> |
84 <codeblock id="GUID-9474C692-0E2E-4B2C-A218-C4DF99E85C31" xml:space="preserve">void CMyDrawingExample::Draw(const TRect& /*aRect*/) const |
89 <codeblock id="GUID-9474C692-0E2E-4B2C-A218-C4DF99E85C31" xml:space="preserve">void CMyDrawingExample::Draw(const TRect& /*aRect*/) const |
85 { |
90 { |
86 SystemGc().BitBlt(TPoint(0, 0), iGcBmp); |
91 SystemGc().BitBlt(TPoint(0, 0), iGcBmp); |
87 }</codeblock> |
92 }</codeblock> |
88 </section> |
93 </section> |