Symbian3/SDK/Source/GUID-1A26BD9E-5B8E-4E6D-904E-B8354B14E111.dita
changeset 0 89d6a7a84779
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-1A26BD9E-5B8E-4E6D-904E-B8354B14E111.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License 
+"Eclipse Public License v1.0" which accompanies this distribution, 
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+    Nokia Corporation - initial contribution.
+Contributors: 
+-->
+<!DOCTYPE concept
+  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-1A26BD9E-5B8E-4E6D-904E-B8354B14E111" xml:lang="en"><title>Constructing
+views in the view architecture</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>The call on the first phase constructor method of the view occurs in <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI controller</xref>. The
+view serves as the top-level window under the UI controller.</p>
+<p>The methods you need to implement for your <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html" format="application/java-archive"><parmname>CCoeControl</parmname></xref>-derived
+view are as follows:</p>
+<ul>
+<li><p>C++ default constructor, which cannot contain code that leaves.
+A common implementation is:</p>
+<itemgroup>
+<codeblock id="GUID-7A108F7C-AD2E-4CDA-9758-5FD6ED477917" xml:space="preserve">
+CMyAppView* CMyAppView::NewL( const TRect&amp; aRect )
+    {
+    CMyAppView* self = CMyAppView::NewLC( aRect );
+    CleanupStack::Pop( self );
+    return self;
+    }
+
+CMyAppView* CMyAppView::NewLC( const TRect&amp; aRect )
+    {
+    CMyAppView* self = new ( ELeave ) CMyAppView;
+    CleanupStack::PushL( self );
+    self-&gt;ConstructL( aRect );
+    return self;
+    }
+
+CMyAppView::CMyAppView()
+    {
+    // No implementation required
+    }</codeblock>
+<p>The declarations for <parmname>CMyAppView::NewL</parmname> and <parmname>CMyAppView::NewLC</parmname> in
+the class header file needs to be public to support the construction method
+required.</p>
+<p>In this approach, <parmname>CMyAppView::NewL</parmname> is called from
+the UI controller. It creates a view object by calling <parmname>CMyAppView::NewLC</parmname>. <parmname>CMyAppView::NewLC</parmname> calls
+new (ELeave) on the C++ default constructor <parmname>CMyAppView</parmname> to
+create the object (and leave if it cannot), <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Kernel_Architecture_2/CCleanupClass.html#%3a%3aCCleanup%3a%3aPushL%28CBase%20%2a%29" format="application/java-archive">pushes</xref> a pointer to the clean-up stack in case the second phase construction method
+leaves, and then calls the second phase construction method of the object.
+When it returns to <parmname>CMyAppView::NewL</parmname>, the pointer pushed
+to the cleanup stack is <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Kernel_Architecture_2/CCleanupClass.html#%3a%3aCCleanup%3a%3aPop%28%29" format="application/java-archive">removed</xref>.</p>
+</itemgroup>
+</li>
+<li><p>Symbian 2nd phase constructor with code that might leave.
+A common implementation is:</p>
+<itemgroup>
+<codeblock id="GUID-32125111-6ACB-4539-8CD0-39ED5629789F" xml:space="preserve">
+void CMyAppView::ConstructL( const TRect&amp; aRect )
+    {
+    // Create a window for this application view
+    CreateWindowL();
+
+     //add construction for other controls if required
+
+	   // Set the windows size
+    SetRect( aRect );
+
+    // Activate the window, which makes it ready to be drawn
+    ActivateL();
+    }</codeblock>
+<p><parmname>CMyAppView::ConstructL</parmname> is a private class providing
+the second phase construction that accepts the rectangle the view is drawn
+to.</p>
+<p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aCreateWindowL%28%29" format="application/java-archive"><parmname>CCoeControl::CreateWindowL</parmname></xref> creates a window
+for the control. Note that this window is a child of the UI controller. This
+method makes the control a <xref href="GUID-352850A9-227F-45DB-8DCD-C6268954B4ED.dita">window-owning
+control</xref>. While, the use of window-owning controls is discouraged to
+prevent the taxing of run-time resources, this is the top-level window for
+the UI controller.</p>
+<p>While this is a simple control that does not contain other controls,
+other controls could be added to the control between <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aCreateWindowL%28%29" format="application/java-archive"><parmname>CCoeControl::CreateWindowL</parmname></xref> and <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aSetRect%28const%20TRect%20%26amp%3b%29" format="application/java-archive"><parmname>CCoeControl::SetRect(aRect)</parmname></xref>. For more information,
+see <xref href="GUID-57CA8A13-05C6-4AFE-9804-E2EA2453143A.dita">Compound
+controls in the view architecture</xref>.</p>
+<p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aSetRect%28const%20TRect%20%26amp%3b%29" format="application/java-archive"><parmname>CCoeControl::SetRect(aRect)</parmname></xref> sets the window
+size according to the requirements of the mobile device. The top-level control
+rectangle is set to the area that the framework provides for the application.
+Calling <parmname>SetRect</parmname> calls the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aSizeChanged%28%29" format="application/java-archive"><parmname>CCoeControl::SizeChanged</parmname></xref> method, where the control should set the position and size
+for any child controls and thus adjust the control layout to the UI.</p>
+<p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aActivateL%28%29" format="application/java-archive"><parmname>CCoeControl::ActivateL</parmname></xref> sets the control
+as ready to be drawn.</p>
+</itemgroup>
+</li>
+</ul>
+<p>If required for your application, you may need to implement other methods
+for your control. For top-level windows, you would need to implement <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aSizeChanged%28%29" format="application/java-archive"><parmname>CCoeControl::SizeChanged</parmname></xref> to respond to
+changes to the size and position of the contents of this control. This is
+called by the Symbian platform when a change occurs. A typical implementation
+for a compound control is:</p>
+<codeblock id="GUID-6F100E69-F0BB-4637-A1AA-57024AF20CF4" xml:space="preserve">void CMyAppView::SizeChanged()
+    {
+    // Control resize code
+    iControl-&gt;SetExtent( const TPoint &amp;aPosition, const TSize &amp;aSize);
+    }</codeblock>
+</conbody></concept>
\ No newline at end of file