<?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-07D2ED79-90B2-4ABC-A61F-108DAEE21955" xml:lang="en"><title>Implementing

framework requirements</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<fig id="GUID-0BBC3D60-0EF0-4446-A1A5-CF84A4728C72"><title>Application Menu</title><image href="GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e36608_href.png"/></fig>

<p>In the Symbian platform, mobile device users start applications from

the application menu. When the mobile device user selects an application,

the application framework calls the application's entry point to launch the

application. In some cases, applications can also be started by other executables.</p>

<fig id="GUID-5A76CBEA-8AF3-4F68-B2FB-9F402D748DF3"><title>Application launch</title><image href="GUID-CC4CA423-0A14-457C-8CBE-4A9F0E8D0B96_d0e36616_href.png"/></fig>

<p>When an application starts, objects are created in the following order:</p>

<ol>

<li id="GUID-BC07E865-8B42-4654-90F9-4644B202EDBC"><p>application

(<xref href="GUID-4F825D83-47A4-36C9-9A25-943A6D799F84.dita"><apiname>CAknApplication</apiname></xref>)</p></li>

<li id="GUID-0B6D8737-8FC7-486B-B3ED-6F91CFA69670"><p>document (<xref href="GUID-935C59EE-AD66-33FE-987B-BD97F5147CC1.dita"><apiname>CAknDocument</apiname></xref>)</p>

</li>

<li id="GUID-FAAD10CF-2F0F-4589-B2B8-A2A8A3696CA5"><p>UI controller

(<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

upon your approach)</p></li>

<li id="GUID-ED56D892-18C4-447C-A7AB-811E1D90C2DA"><p>view controller

(<xref href="GUID-11967EBB-7439-3775-B287-7560ECA0AF1F.dita"><apiname>CAknView</apiname></xref>) in <xref href="GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita">Symbian

view applications</xref></p></li>

<li id="GUID-5BFF07E4-6575-4B23-9FA5-824DB057A55C"><p>view (<xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref>)</p>

</li>

</ol>

<section id="GUID-B8AA011F-23EB-4BA5-9FA6-1382D37E13A9"><title>Entry point</title>

<p>The two methods that you need to implement for the entry point are as

follows:</p>

<ul>

<li><p>an entry point for the application, with the following syntax:</p>

<itemgroup>

<codeblock id="GUID-F09C226F-B1D6-4435-8983-7DD62D1BBD26" xml:space="preserve">GLDEF_C TInt E32Main()

    {

    return EikStart::RunApplication( NewApplication );

    }</codeblock>

<p>where:</p>

<p><parmname>E32Main()</parmname> is the entry point method called by the

application framework</p>

<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>

</itemgroup>

</li>

<li><p>a non-leaving factory method that creates a new instance

of the application class, or <parmname>NULL</parmname> if the class cannot

be instantiated. The expected syntax is as follows:</p>

<itemgroup>

<codeblock id="GUID-D1F8BE18-84A5-4F32-9BC8-D5458455492A" xml:space="preserve">LOCAL_C CApaApplication* NewApplication()

    {

    return new CMyAppClass;

    }</codeblock>

<p>where:</p>

<p><parmname>NewApplication()</parmname> is a method that returns a pointer

to a <xref href="GUID-C0297A58-2E39-3211-A2B4-C334192CE2A7.dita"><apiname>CApaApplication</apiname></xref> object.</p>

<p><parmname>return new CMyAppClass</parmname> returns an instance of the

application class as created by the <xref href="GUID-4F825D83-47A4-36C9-9A25-943A6D799F84.dita"><apiname>CAknApplication</apiname></xref> derived

class</p>

<p>The application framework expects the factory method to have exactly

this prototype. In other words, the factory function should be like the above

code fragment.</p>

</itemgroup>

</li>

</ul>

</section>

<section id="GUID-63C94373-F55D-4B58-9637-7BA0E1B14ACF"><title>CAknApplication</title>

<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

class:</p>

<ul>

<li><p>a method that returns the application UID. The syntax is

as follows:</p>

<codeblock id="GUID-77921F31-5A36-4A6B-AD2C-E9364A50E0F6" xml:space="preserve">TUid CMyAppClass::AppDllUid() const

    {

    return KUidMyApp;

    }</codeblock>

<p>where:</p>

<itemgroup>

<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

UID</p>

<p><parmname>KUidMyApp</parmname> is the UID for your application, which

is typically declared in an application header file.</p>

</itemgroup>

<p>The application framework calls the <parmname>AppDllUid()</parmname> method

to get the application UID. The application framework checks to see if there

is an instance of the application with the same UID already running. If so,

then the application framework switches to the already existing application. </p>

<note>

<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>

</note>

</li>

<li><p>a factory function for creating an object of the document

class for your application. The expected syntax is as follows:</p>

<codeblock id="GUID-C56EAA45-A671-47D6-8FE6-492B154813BF" xml:space="preserve">CApaDocument* CMyAppClass::CreateDocumentL()

    {

    return CMyAppDocument::NewL( *this );

    }

</codeblock>

<p>where:</p>

<itemgroup>

<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

application framework.</p>

<p> <parmname>return CMyAppDocument::NewL( *this )</parmname> returns an

instance of the <xref href="GUID-935C59EE-AD66-33FE-987B-BD97F5147CC1.dita"><apiname>CAknDocument</apiname></xref> derived class of your application.

It represents the data that relates to a particular instance of the application

and owns the application <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI

controller</xref>.</p>

</itemgroup>

</li>

</ul>

<note>

<p>The application framework owns the document object and is responsible

for destroying it.</p>

</note>

</section>

<section id="GUID-73A8D2EE-F22A-483D-A23A-5E46D709A718"><title>CAknDocument</title>

<p>You must implement a <xref href="GUID-935C59EE-AD66-33FE-987B-BD97F5147CC1.dita"><apiname>CAknDocument</apiname></xref> derived class for

your application, even if you do not store data, as this is the class that

owns the <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI controller</xref> for

your application. The expected syntax for creating the UI controller class

is as follows:</p>

<codeblock id="GUID-C016DB83-2B28-4DEC-8027-A9291E380191" xml:space="preserve">CEikAppUi* CMyAppDocument::CreateAppUiL()

    {

    return new ( ELeave ) CMyAppAppUi;

    }</codeblock>

<p>where:</p>

<ul>

<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

the first phase construction of the UI controller</p></li>

<li><p><parmname>new ( ELeave ) CMyAppAppUi </parmname> is a method

that creates an instance of the UI controller class of your application</p>

</li>

</ul>

<p>The application framework owns the UI controller object of the application

and is responsible for destroying it. There are two alternate classes from

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>

<p>For more information on the UI controller options, see <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI controller</xref></p>

</section>