|
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-0BBC3D60-0EF0-4446-A1A5-CF84A4728C72"><title>Application Menu</title><image href="GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e42175_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-CC4CA423-0A14-457C-8CBE-4A9F0E8D0B96_d0e42183_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="GUID-4F825D83-47A4-36C9-9A25-943A6D799F84.dita"><apiname>CAknApplication</apiname></xref>)</p></li> |
|
24 <li id="GUID-0B6D8737-8FC7-486B-B3ED-6F91CFA69670"><p>document (<xref href="GUID-935C59EE-AD66-33FE-987B-BD97F5147CC1.dita"><apiname>CAknDocument</apiname></xref>)</p> |
|
25 </li> |
|
26 <li id="GUID-FAAD10CF-2F0F-4589-B2B8-A2A8A3696CA5"><p>UI controller |
|
27 (<xref href="GUID-6F2BAB12-6273-3314-B9F1-9AA08403F5EF.dita"><apiname>CAknAppUI</apiname></xref> or <xref href="GUID-9CB85702-5D4F-371E-99D0-F6030DC86539.dita"><apiname>CAknAppViewUI</apiname></xref> depending |
|
28 upon your approach)</p></li> |
|
29 <li id="GUID-ED56D892-18C4-447C-A7AB-811E1D90C2DA"><p>view controller |
|
30 (<xref href="GUID-11967EBB-7439-3775-B287-7560ECA0AF1F.dita"><apiname>CAknView</apiname></xref>) in <xref href="GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita">Symbian |
|
31 view applications</xref></p></li> |
|
32 <li id="GUID-5BFF07E4-6575-4B23-9FA5-824DB057A55C"><p>view (<xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref>)</p> |
|
33 </li> |
|
34 </ol> |
|
35 <section id="GUID-B8AA011F-23EB-4BA5-9FA6-1382D37E13A9"><title>Entry point</title> |
|
36 <p>The two methods that you need to implement for the entry point are as |
|
37 follows:</p> |
|
38 <ul> |
|
39 <li><p>an entry point for the application, with the following syntax:</p> |
|
40 <itemgroup> |
|
41 <codeblock id="GUID-F09C226F-B1D6-4435-8983-7DD62D1BBD26" xml:space="preserve">GLDEF_C TInt E32Main() |
|
42 { |
|
43 return EikStart::RunApplication( NewApplication ); |
|
44 }</codeblock> |
|
45 <p>where:</p> |
|
46 <p><parmname>E32Main()</parmname> is the entry point method called by the |
|
47 application framework</p> |
|
48 <p><parmname>return EikStart::RunApplication(NewApplication )</parmname> calls<xref href="GUID-E5533B10-D01F-3133-8E74-28071766885B.dita#GUID-E5533B10-D01F-3133-8E74-28071766885B/GUID-275C4B9B-53BD-38C5-8C8E-05D480358836"><apiname> EikStart::RunApplication()</apiname></xref></p> |
|
49 </itemgroup> |
|
50 </li> |
|
51 <li><p>a non-leaving factory method that creates a new instance |
|
52 of the application class, or <parmname>NULL</parmname> if the class cannot |
|
53 be instantiated. The expected syntax is as follows:</p> |
|
54 <itemgroup> |
|
55 <codeblock id="GUID-D1F8BE18-84A5-4F32-9BC8-D5458455492A" xml:space="preserve">LOCAL_C CApaApplication* NewApplication() |
|
56 { |
|
57 return new CMyAppClass; |
|
58 }</codeblock> |
|
59 <p>where:</p> |
|
60 <p><parmname>NewApplication()</parmname> is a method that returns a pointer |
|
61 to a <xref href="GUID-C0297A58-2E39-3211-A2B4-C334192CE2A7.dita"><apiname>CApaApplication</apiname></xref> object.</p> |
|
62 <p><parmname>return new CMyAppClass</parmname> returns an instance of the |
|
63 application class as created by the <xref href="GUID-4F825D83-47A4-36C9-9A25-943A6D799F84.dita"><apiname>CAknApplication</apiname></xref> derived |
|
64 class</p> |
|
65 <p>The application framework expects the factory method to have exactly |
|
66 this prototype. In other words, the factory function should be like the above |
|
67 code fragment.</p> |
|
68 </itemgroup> |
|
69 </li> |
|
70 </ul> |
|
71 </section> |
|
72 <section id="GUID-63C94373-F55D-4B58-9637-7BA0E1B14ACF"><title>CAknApplication</title> |
|
73 <p>You must implement at least the following two methods in your <xref href="GUID-4F825D83-47A4-36C9-9A25-943A6D799F84.dita"><apiname>CAknApplication</apiname></xref> derived |
|
74 class:</p> |
|
75 <ul> |
|
76 <li><p>a method that returns the application UID. The syntax is |
|
77 as follows:</p> |
|
78 <codeblock id="GUID-77921F31-5A36-4A6B-AD2C-E9364A50E0F6" xml:space="preserve">TUid CMyAppClass::AppDllUid() const |
|
79 { |
|
80 return KUidMyApp; |
|
81 }</codeblock> |
|
82 <p>where:</p> |
|
83 <itemgroup> |
|
84 <p><xref href="GUID-C0297A58-2E39-3211-A2B4-C334192CE2A7.dita#GUID-C0297A58-2E39-3211-A2B4-C334192CE2A7/GUID-669C19DC-04C9-3979-A87E-8F9EFA8E4D99"><apiname>CApaApplication::AppDllUid()</apiname></xref> is used to get the application |
|
85 UID</p> |
|
86 <p><parmname>KUidMyApp</parmname> is the UID for your application, which |
|
87 is typically declared in an application header file.</p> |
|
88 </itemgroup> |
|
89 <p>The application framework calls the <parmname>AppDllUid()</parmname> method |
|
90 to get the application UID. The application framework checks to see if there |
|
91 is an instance of the application with the same UID already running. If so, |
|
92 then the application framework switches to the already existing application. </p> |
|
93 <note> |
|
94 <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> |
|
95 </note> |
|
96 </li> |
|
97 <li><p>a factory function for creating an object of the document |
|
98 class for your application. The expected syntax is as follows:</p> |
|
99 <codeblock id="GUID-C56EAA45-A671-47D6-8FE6-492B154813BF" xml:space="preserve">CApaDocument* CMyAppClass::CreateDocumentL() |
|
100 { |
|
101 return CMyAppDocument::NewL( *this ); |
|
102 } |
|
103 </codeblock> |
|
104 <p>where:</p> |
|
105 <itemgroup> |
|
106 <p><xref href="GUID-E36E2F07-09E7-32BC-BB83-14DF9232E7D9.dita#GUID-E36E2F07-09E7-32BC-BB83-14DF9232E7D9/GUID-D0810109-8F11-3B65-8806-9A61317D2128"><apiname>CEikApplication::CreateDocumentL()</apiname></xref> is called by the |
|
107 application framework.</p> |
|
108 <p> <parmname>return CMyAppDocument::NewL( *this )</parmname> returns an |
|
109 instance of the <xref href="GUID-935C59EE-AD66-33FE-987B-BD97F5147CC1.dita"><apiname>CAknDocument</apiname></xref> derived class of your application. |
|
110 It represents the data that relates to a particular instance of the application |
|
111 and owns the application <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI |
|
112 controller</xref>.</p> |
|
113 </itemgroup> |
|
114 </li> |
|
115 </ul> |
|
116 <note> |
|
117 <p>The application framework owns the document object and is responsible |
|
118 for destroying it.</p> |
|
119 </note> |
|
120 </section> |
|
121 <section id="GUID-73A8D2EE-F22A-483D-A23A-5E46D709A718"><title>CAknDocument</title> |
|
122 <p>You must implement a <xref href="GUID-935C59EE-AD66-33FE-987B-BD97F5147CC1.dita"><apiname>CAknDocument</apiname></xref> derived class for |
|
123 your application, even if you do not store data, as this is the class that |
|
124 owns the <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI controller</xref> for |
|
125 your application. The expected syntax for creating the UI controller class |
|
126 is as follows:</p> |
|
127 <codeblock id="GUID-C016DB83-2B28-4DEC-8027-A9291E380191" xml:space="preserve">CEikAppUi* CMyAppDocument::CreateAppUiL() |
|
128 { |
|
129 return new ( ELeave ) CMyAppAppUi; |
|
130 }</codeblock> |
|
131 <p>where:</p> |
|
132 <ul> |
|
133 <li><p><xref href="GUID-B33A8A56-D1BE-3E3D-B5AC-F644A5C764DB.dita#GUID-B33A8A56-D1BE-3E3D-B5AC-F644A5C764DB/GUID-37544F28-FD9A-3E11-96B8-7DA8BC84CC59"><apiname>CEikDocument::CreateAppUiL()</apiname></xref> carries out |
|
134 the first phase construction of the UI controller</p></li> |
|
135 <li><p><parmname>new ( ELeave ) CMyAppAppUi </parmname> is a method |
|
136 that creates an instance of the UI controller class of your application</p> |
|
137 </li> |
|
138 </ul> |
|
139 <p>The application framework owns the UI controller object of the application |
|
140 and is responsible for destroying it. There are two alternate classes from |
|
141 which you can derive your UI controller class, <xref href="GUID-77329067-34D9-3698-B764-294535E660EB.dita"><apiname>CAknAppUi</apiname></xref> or <xref href="GUID-2DBA2DA9-3DA7-381C-842C-9F6FEEDF973E.dita"><apiname>CAknViewAppUi</apiname></xref>.</p> |
|
142 <p>For more information on the UI controller options, see <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI controller</xref></p> |
|
143 </section> |
|
144 </conbody></concept> |