|
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-A3BCC33F-D11B-4F98-BCC3-9A06381A02E7" xml:lang="en"><title>Constructing |
|
13 the view controller in the view architecture</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Each view controller acts like a small UI controller.</p> |
|
15 <p>The call on the first phase constructor of the view controller occurs |
|
16 in the<xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita"> UI controller</xref>.</p> |
|
17 <p>The methods you need to implement in your <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html" format="application/java-archive"><parmname>CAknView</parmname></xref>-derived |
|
18 class are as follows:</p> |
|
19 <ul> |
|
20 <li><p>C++ default constructor, which cannot contain any code that |
|
21 might leave. A common implementation is:</p> |
|
22 <itemgroup> |
|
23 <codeblock id="GUID-CA1A42F0-2B6F-4520-B408-1B46037B6E29" xml:space="preserve"> |
|
24 CMyViewAppView::CMyViewAppView() |
|
25 { |
|
26 }</codeblock> |
|
27 <p>The class declaration for this constructor in the class header file |
|
28 needs to be public to support the construction method required.</p> |
|
29 </itemgroup> |
|
30 </li> |
|
31 <li><p>two-phase constructor, a common implementation is:</p> |
|
32 <itemgroup> |
|
33 <codeblock id="GUID-A98C61E4-8C11-4F7D-9782-C440B8FAE374" xml:space="preserve">CMyViewAppView* CMyViewAppView::NewL( const TRect& aRect ) |
|
34 { |
|
35 CMyViewAppView* self = CMyViewAppView::NewLC( aRect ); |
|
36 CleanupStack::Pop( self ); |
|
37 return self; |
|
38 } |
|
39 |
|
40 CMyViewAppView* CMyViewAppView::NewLC( const TRect& aRect ) |
|
41 { |
|
42 CMyViewAppView* self = new ( ELeave ) CMyViewAppView; |
|
43 CleanupStack::PushL( self ); |
|
44 self->ConstructL( aRect ); |
|
45 return self; |
|
46 } |
|
47 </codeblock> |
|
48 <p>The declarations for <parmname>CMyViewAppView::NewL</parmname> and <parmname>CMyViewAppView::NewLC</parmname> in |
|
49 the class header file needs to be public to support the construction method |
|
50 required. </p> |
|
51 <p>In this approach, <parmname>CMyViewAppView::NewL</parmname> is called |
|
52 from the UI controller. It creates a view object by calling <parmname>CMyViewAppView::NewLC</parmname>. <parmname>CMyViewAppView::NewLC</parmname> calls new (<parmname>ELeave</parmname>) on the C++ default constructor <parmname>CMyViewAppView</parmname> to |
|
53 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 |
|
54 leaves, and then calls the second phase construction method of the object. |
|
55 When it returns to <parmname>CMyViewAppView::NewL</parmname>, the pointer |
|
56 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> |
|
57 </itemgroup> |
|
58 </li> |
|
59 <li><p>Symbian 2nd phase constructor with code that might leave. |
|
60 A common implementation is:</p> |
|
61 <itemgroup> |
|
62 <codeblock id="GUID-F282B41C-0AF0-4B62-853A-812F34667C78" xml:space="preserve">void CMyViewAppView::ConstructL() |
|
63 { |
|
64 // construct r_name32 resources |
|
65 BaseConstructL(r_name32 ); |
|
66 } |
|
67 </codeblock> |
|
68 <p><parmname>CMyViewAppView::ConstructL</parmname> is a public class providing |
|
69 the second phase construction that accepts the rectangle the view is drawn |
|
70 to.</p> |
|
71 <p><xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html#04bb841d875636d632ada39cb12514c4" format="application/java-archive"><parmname>CAknView::BaseConstructL</parmname></xref> initializes this view with standard values. It accepts the |
|
72 symbolic ID name of a resource from the resource file.</p> |
|
73 </itemgroup> |
|
74 </li> |
|
75 <li><p>a method for returning the UID for the view. A common implementation |
|
76 is:</p> |
|
77 <itemgroup> |
|
78 <codeblock id="GUID-272134EE-D14C-4F97-A46D-0BEC71EF01ED" xml:space="preserve"> |
|
79 TUid CMyViewAppView::Id() const |
|
80 { |
|
81 return KViewId; |
|
82 } |
|
83 |
|
84 </codeblock> |
|
85 <p><parmname>CMyViewAppView::Id()</parmname> is the override of <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html#71e3a172cd418a5d73071f598fe8d26d" format="application/java-archive"><parmname>CAknView::ID</parmname></xref> to return the UID of the view</p> |
|
86 <p><parmname>KViewId</parmname> is defined somewhere in a header file, |
|
87 and is unique to this application</p> |
|
88 </itemgroup> |
|
89 </li> |
|
90 </ul> |
|
91 <section id="GUID-952D9762-EA63-489D-9698-FC504BD73001"><title>Scalability</title> |
|
92 <p>If you wish to support <xref href="GUID-B02C762B-C452-4184-ABEA-4753E6CD47D2.dita">scalability</xref> in |
|
93 your application, then you need to implement <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/UIKON/CEikAppUiClass.html#%3a%3aCEikAppUi%3a%3aHandleResourceChangeL%28%29" format="application/java-archive"><parmname>CEikAppUi::HandleResourceChangeL</parmname></xref> in the <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita"> UI |
|
94 controller</xref>, and then a <parmname>HandleClientRectChange</parmname> method |
|
95 in the view controller.</p> |
|
96 <p>A common implementation is as follows:</p> |
|
97 <codeblock id="GUID-F5BC393D-EA47-45B2-8892-B71CE934F5B6" xml:space="preserve"> |
|
98 void CMyViewAppView::HandleClientRectChange() |
|
99 { |
|
100 if ( iContainer ) |
|
101 { |
|
102 iContainer->SetRect( ClientRect() ); |
|
103 } |
|
104 } |
|
105 |
|
106 </codeblock> |
|
107 <p>, where</p> |
|
108 <p><parmname>CMyViewAppView::HandleClientRectChange</parmname> calls <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> to set the |
|
109 window size according to the requirements of the mobile device.</p> |
|
110 </section> |
|
111 <section id="GUID-DC760F92-C154-4DAA-AAD1-A0C02766C6B0"><title>Activating and |
|
112 deactivating views</title> |
|
113 <p>In order for a view to be displayed, it needs to be activated by <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html#486d490d911ce5e9495e0ee19b0442db" format="application/java-archive"><parmname>CAknView::DoActivateL</parmname></xref>. The override of this method in the view controller must create |
|
114 a <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 to display visual |
|
115 content to mobile device users. The <parmname>DoActivateL()</parmname> call |
|
116 must be prepared to handle the case where it is called while the view is already |
|
117 active.</p> |
|
118 <p>If the view is not published for external use, or does not handle message |
|
119 parameters, a simple check and return if the view is already active is sufficient.</p> |
|
120 <p>A common implementation is as follows:</p> |
|
121 <codeblock id="GUID-01819343-975C-499B-9DF6-14DA9BB5912E" xml:space="preserve"> |
|
122 void CMyViewAppView::DoActivateL( |
|
123 const TVwsViewId& /*aPrevViewId*/,TUid /*aCustomMessageId*/, |
|
124 const TDesC8& /*aCustomMessage*/) |
|
125 { |
|
126 if (!iContainer) |
|
127 { |
|
128 iContainer = new (ELeave) CMyViewAppContainer; |
|
129 iContainer->SetMopParent(this); |
|
130 iContainer->ConstructL( ClientRect() ); |
|
131 AppUi()->AddToStackL( *this, iContainer ); |
|
132 } |
|
133 |
|
134 // Message handling would take place here. |
|
135 } |
|
136 </codeblock> |
|
137 <p>, where</p> |
|
138 <ul> |
|
139 <li><p><parmname>CMyViewAppView::DoActivateL</parmname> is the override |
|
140 for <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html#486d490d911ce5e9495e0ee19b0442db" format="application/java-archive"><parmname>CAknView::DoActivateL</parmname></xref> for the application.</p></li> |
|
141 <li><p><parmname>if (!iContainer)</parmname> checks to see if the |
|
142 view already exists.</p></li> |
|
143 <li><p><parmname>iContainer = new (ELeave) CMyViewAppContainer;</parmname> calls |
|
144 the first phase constructor of the <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 |
|
145 class that provides the view.</p></li> |
|
146 <li><p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aSetMopParent%28MObjectProvider%20%2a%29" format="application/java-archive"><parmname>iContainer->SetMopParent(this);</parmname></xref> sets the |
|
147 context for the view being created. In this case, it assigns the <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 to the view controller.</p> |
|
148 </li> |
|
149 <li><p><parmname>iContainer->ConstructL( ClientRect() )</parmname> calls |
|
150 the second phase constructor of the <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 |
|
151 class that provides the view.</p></li> |
|
152 <li><p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeAppUiClass.html#%3a%3aCCoeAppUi%3a%3aAddToStackL%28CCoeControl%20%2a%2cTInt%2cTInt%29" format="application/java-archive"><parmname>AppUi()->AddToStackL( *this, iContainer );</parmname></xref> adds |
|
153 the <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 to the control |
|
154 stack for <xref href="GUID-542550FA-F9F1-46D6-8182-6E7FAA013572.dita">key event |
|
155 handling.</xref></p></li> |
|
156 </ul> |
|
157 <p>The view architecture supports an automatic recovery mechanism if <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html#486d490d911ce5e9495e0ee19b0442db" format="application/java-archive"><parmname>CAknView::DoActivateL()</parmname></xref> leaves. The Symbian platform calls <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html#f47363eacbe46c5827282407b354b535" format="application/java-archive"><parmname>CAknView::DoDeactivate()</parmname></xref> in |
|
158 the view that has left, reinstates the previous view of the application, and |
|
159 returns to the view that was just displayed. If the application had no previous |
|
160 view, it exits. If the application’s previous view was the same as the activating |
|
161 view (that is, the view is reactivated with a new message), the application |
|
162 attempts to recover to the default view.</p> |
|
163 <p>In most cases, this mechanism removes the need to put any recovery mechanism |
|
164 in the <parmname>DoActivateL()</parmname> methods. The one situation where |
|
165 you may consider something more complex is when the view can be reactivated |
|
166 (that is, activated with a new message while already active). In this case, |
|
167 the view may attempt a more complex strategy to preserve the existing state |
|
168 if a leave happens during the attempt to handle the new message.</p> |
|
169 <p>To destroy the <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 |
|
170 control in a view control, you must override <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html#f47363eacbe46c5827282407b354b535" format="application/java-archive"><parmname>CAknView::DoDeactivate</parmname></xref>. |
|
171 It is called when the application exits, or another view has been activated |
|
172 and the previous active window needs to be shut down. This order makes view |
|
173 switching fast. In <parmname>DoDeactivate</parmname> the view is removed from |
|
174 the stack and therefore the view’s container and its controls are destroyed. |
|
175 This function must not leave.</p> |
|
176 <p>A common implementation is as follows:</p> |
|
177 <codeblock id="GUID-01F7257D-47C2-4A42-9717-97D3913F3AB0" xml:space="preserve"> |
|
178 void CMyViewAppView::DoDeactivate() |
|
179 { |
|
180 if ( iContainer ) |
|
181 { |
|
182 AppUi()->RemoveFromViewStack( *this, iContainer ); |
|
183 } |
|
184 |
|
185 delete iContainer; |
|
186 iContainer = NULL; |
|
187 }</codeblock> |
|
188 <p>, where</p> |
|
189 <ul> |
|
190 <li><p><parmname>CMyViewAppView::DoDeactivateL</parmname> is the |
|
191 override for <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html#f47363eacbe46c5827282407b354b535" format="application/java-archive"><parmname>CAknView::DoDeactivateL</parmname></xref> for |
|
192 the application.</p></li> |
|
193 <li><p><parmname>if (!iContainer)</parmname> checks to see if the |
|
194 view already exists.</p></li> |
|
195 <li><p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeAppUiClass.html#%3a%3aCCoeAppUi%3a%3aRemoveFromViewStack%28const%20MCoeView%20%26amp%3b%2cCCoeControl%20%2a%29" format="application/java-archive"><parmname>AppUi()->RemoveFromViewStack( *this, iContainer );</parmname></xref> removes |
|
196 the <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 from the control |
|
197 stack.</p></li> |
|
198 <li><p><parmname>delete iContainer;</parmname> deletes the <parmname>CCoeControl</parmname>-derived |
|
199 view.</p></li> |
|
200 </ul> |
|
201 </section> |
|
202 </conbody></concept> |