|
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-07D2ED79-90B2-4ABC-A61F-108DAEE21955" xml:lang="en"><title>Implementing |
|
13 framework requirements</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <fig id="GUID-9F184193-87DA-40F1-B946-BE7D101626DA"><title>Application menu</title><image href="GUID-98AC61E5-57C9-445E-98CB-79C6642CB041_d0e38543_href.png"/></fig> |
|
15 <p>In the Symbian platform, mobile device users start applications from |
|
16 the application menu. When the mobile device user selects an application, |
|
17 the application framework calls the application's entry point to launch the |
|
18 application. In some cases, applications can also be started by other executables.</p> |
|
19 <fig id="GUID-5A76CBEA-8AF3-4F68-B2FB-9F402D748DF3"><title>Application launch</title><image href="GUID-370F4A51-EC67-4B6C-B14A-5C640A58688B_d0e38551_href.png"/></fig> |
|
20 <p>When an application starts, objects are created in the following order:</p> |
|
21 <ol> |
|
22 <li id="GUID-BC07E865-8B42-4654-90F9-4644B202EDBC"><p>application |
|
23 (<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknApplication.html" format="application/java-archive"><parmname>CAknApplication</parmname></xref>)</p></li> |
|
24 <li id="GUID-0B6D8737-8FC7-486B-B3ED-6F91CFA69670"><p>document (<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknDocument.html" format="application/java-archive"><parmname>CAknDocument</parmname></xref>)</p> |
|
25 </li> |
|
26 <li id="GUID-FAAD10CF-2F0F-4589-B2B8-A2A8A3696CA5"><p>UI controller |
|
27 (<xref href="GUID-B5DE1C86-2B16-4B22-887F-7079E54A8ED6.dita"><parmname>CAknAppUI</parmname></xref> or <xref href="GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita"><parmname>CAknAppViewUI</parmname></xref> depending |
|
28 upon your approach)</p></li> |
|
29 <li id="GUID-ED56D892-18C4-447C-A7AB-811E1D90C2DA"><p>in <xref href="GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita">Symbian |
|
30 view applications</xref> , view controller (<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html" format="application/java-archive"><parmname>CAknView</parmname></xref>)</p> |
|
31 </li> |
|
32 <li id="GUID-5BFF07E4-6575-4B23-9FA5-824DB057A55C"><p>view (<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>)</p></li> |
|
33 </ol> |
|
34 <section id="GUID-B8AA011F-23EB-4BA5-9FA6-1382D37E13A9"><title>Entry point</title> |
|
35 <p>The two methods that you need to implement for the entry point are as |
|
36 follows:</p> |
|
37 <ul> |
|
38 <li><p>an entry point for the application, with the following syntax:</p> |
|
39 <itemgroup> |
|
40 <codeblock id="GUID-F09C226F-B1D6-4435-8983-7DD62D1BBD26" xml:space="preserve">GLDEF_C TInt E32Main() |
|
41 { |
|
42 return EikStart::RunApplication( NewApplication ); |
|
43 }</codeblock> |
|
44 <p>where:</p> |
|
45 <p><parmname>E32Main()</parmname> is the entry point method called by the |
|
46 application framework</p> |
|
47 <p><parmname>return EikStart::RunApplication(NewApplication )</parmname> calls <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/UIKON/EikStartClass.html#%3a%3aEikStart%3a%3aRunApplication%28%29" format="application/java-archive"><parmname>EikStart::RunApplication</parmname></xref></p> |
|
48 </itemgroup> |
|
49 </li> |
|
50 <li><p>a non-leaving factory method that creates a new instance |
|
51 of the application class, or <parmname>NULL</parmname> if the class cannot |
|
52 be instantiated. The expected syntax is as follows:</p> |
|
53 <itemgroup> |
|
54 <codeblock id="GUID-D1F8BE18-84A5-4F32-9BC8-D5458455492A" xml:space="preserve">LOCAL_C CApaApplication* NewApplication() |
|
55 { |
|
56 return new CMyAppClass; |
|
57 }</codeblock> |
|
58 <p>where:</p> |
|
59 <p><parmname>NewApplication()</parmname> is a method that returns a pointer |
|
60 to a <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Application_Architecture/CApaApplicationClass.html" format="application/java-archive"><parmname>CApaApplication</parmname></xref> object.</p> |
|
61 <p><parmname>return new CMyAppClass</parmname> returns an instance of the |
|
62 application class as created by the <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknApplication.html" format="application/java-archive"><parmname>CAknApplication</parmname></xref> derived |
|
63 class</p> |
|
64 <p>The application framework expects the factory method to have exactly |
|
65 this prototype. In other words, the factory function should be like the above |
|
66 code fragment.</p> |
|
67 </itemgroup> |
|
68 </li> |
|
69 </ul> |
|
70 </section> |
|
71 <section id="GUID-63C94373-F55D-4B58-9637-7BA0E1B14ACF"><title>CAknApplication</title> |
|
72 <p>You must implement at least the following two methods in your <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknApplication.html" format="application/java-archive"><parmname>CAknApplication</parmname></xref> derived |
|
73 class:</p> |
|
74 <ul> |
|
75 <li><p>a method that returns the application UID. The syntax is |
|
76 as follows:</p> |
|
77 <codeblock id="GUID-77921F31-5A36-4A6B-AD2C-E9364A50E0F6" xml:space="preserve">TUid CMyAppClass::AppDllUid() const |
|
78 { |
|
79 return KUidMyApp; |
|
80 }</codeblock> |
|
81 <p>where:</p> |
|
82 <itemgroup> |
|
83 <p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Application_Architecture/CApaApplicationClass.html#%3a%3aCApaApplication%3a%3aAppDllUid%28%29const" format="application/java-archive">CApaApplication::AppDllUid()</xref> is used to get the application |
|
84 UID</p> |
|
85 <p><parmname>KUidMyApp</parmname> is the UID for your application, which |
|
86 is typically declared in an application header file</p> |
|
87 </itemgroup> |
|
88 <p>The application framework calls the <parmname>AppDllUid()</parmname> method |
|
89 to get the application UID. The application framework checks to see if there |
|
90 is an instance of the application with the same UID already running. If so, |
|
91 then the application framework switches to the already existing application. </p> |
|
92 <note> |
|
93 <p>You must return the same UID that you declared for the UID3 in the <xref href="GUID-1F7E1476-D7A3-49E4-B05B-F3A0FD6333B6.dita"><parmname>mmp</parmname></xref> and <xref href="GUID-FE9017F4-4197-472F-A3E7-267169A51ABD.dita">registration</xref> files.</p> |
|
94 </note> |
|
95 </li> |
|
96 <li><p>a factory function for creating an object of the document |
|
97 class for your application. The expected syntax is as follows:</p> |
|
98 <codeblock id="GUID-C56EAA45-A671-47D6-8FE6-492B154813BF" xml:space="preserve">CApaDocument* CMyAppClass::CreateDocumentL() |
|
99 { |
|
100 return CMyAppDocument::NewL( *this ); |
|
101 } |
|
102 </codeblock> |
|
103 <p>where:</p> |
|
104 <itemgroup> |
|
105 <p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Application_Architecture/CApaApplicationClass.html#%3a%3aCApaApplication%3a%3aCreateDocumentL%28CApaProcess%20%2a%29" format="application/java-archive"><parmname>CEikApplication::CreateDocumentL</parmname></xref> is called |
|
106 by the application framework</p> |
|
107 <p> <parmname>return CMyAppDocument::NewL( *this )</parmname> returns an |
|
108 instance of the <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknDocument.html" format="application/java-archive"><parmname>CAknDocument</parmname></xref> derived |
|
109 class of your application. It represents the data that relates to a particular |
|
110 instance of the application and owns the application <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI |
|
111 controller</xref>.</p> |
|
112 </itemgroup> |
|
113 </li> |
|
114 </ul> |
|
115 <note> |
|
116 <p>The application framework owns the document object and is responsible |
|
117 for destroying it.</p> |
|
118 </note> |
|
119 </section> |
|
120 <section id="GUID-73A8D2EE-F22A-483D-A23A-5E46D709A718"><title>CAknDocument</title> |
|
121 <p>You must implement a <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknDocument.html" format="application/java-archive"><parmname>CAknDocument</parmname></xref> derived |
|
122 class for your application, even if you do not store data, as this is the |
|
123 class that owns the <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI |
|
124 controller</xref> for your application. The expected syntax for creating the |
|
125 UI controller class is as follows:</p> |
|
126 <codeblock id="GUID-C016DB83-2B28-4DEC-8027-A9291E380191" xml:space="preserve">CEikAppUi* CMyAppDocument::CreateAppUiL() |
|
127 { |
|
128 return new ( ELeave ) CMyAppAppUi; |
|
129 }</codeblock> |
|
130 <p>where:</p> |
|
131 <ul> |
|
132 <li><p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/UIKON/CEikDocumentClass.html#%3a%3aCEikDocument%3a%3aCreateAppUiL%28%29" format="application/java-archive"><parmname>CEikDocument::CreateAppUiL</parmname></xref> carries out the first phase construction of the UI controller</p> |
|
133 </li> |
|
134 <li><p><parmname>new ( ELeave ) CMyAppAppUi </parmname> is a method |
|
135 that creates an instance of the UI controller class of your application</p> |
|
136 </li> |
|
137 </ul> |
|
138 <p>The application framework owns the UI controller object of the application |
|
139 and is responsible for destroying it. There are two alternate classes from |
|
140 which you can derive your UI controller class, <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknAppUi.html" format="application/java-archive"><parmname>CAknAppUi</parmname></xref> or <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknViewAppUi.html" format="application/java-archive"><parmname>CAknViewAppUi</parmname></xref>.</p> |
|
141 <p>For more information on the UI controller options, see <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI controller</xref></p> |
|
142 </section> |
|
143 </conbody></concept> |