Implementing framework requirements

Figure 1. Application Menu

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.

Figure 2. Application launch

When an application starts, objects are created in the following order:

application (CAknApplication)
document (CAknDocument)
UI controller (CAknAppUI or CAknAppViewUI depending upon your approach)
view controller (CAknView) in Symbian view applications
view (CCoeControl)

Entry point

The two methods that you need to implement for the entry point are as follows:

an entry point for the application, with the following syntax:
```
GLDEF_C TInt E32Main()
    {
    return EikStart::RunApplication( NewApplication );
    }
```
where:

E32Main() is the entry point method called by the application framework

return EikStart::RunApplication(NewApplication ) calls EikStart::RunApplication()
a non-leaving factory method that creates a new instance of the application class, or NULL if the class cannot be instantiated. The expected syntax is as follows:
```
LOCAL_C CApaApplication* NewApplication()
    {
    return new CMyAppClass;
    }
```
where:

NewApplication() is a method that returns a pointer to a CApaApplication object.

return new CMyAppClass returns an instance of the application class as created by the CAknApplication derived class

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.

CAknApplication

You must implement at least the following two methods in your CAknApplication derived class:

a method that returns the application UID. The syntax is as follows:
```
TUid CMyAppClass::AppDllUid() const
    {
    return KUidMyApp;
    }
```
where:

CApaApplication::AppDllUid() is used to get the application UID

KUidMyApp is the UID for your application, which is typically declared in an application header file.

The application framework calls the AppDllUid() 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.

Note:
You must return the same UID that you declared for the UID3 in the mmp and registration files.
a factory function for creating an object of the document class for your application. The expected syntax is as follows:
```
CApaDocument* CMyAppClass::CreateDocumentL()
    {
    return CMyAppDocument::NewL( *this );
    }
```
where:

CEikApplication::CreateDocumentL() is called by the application framework.

return CMyAppDocument::NewL( *this ) returns an instance of the CAknDocument derived class of your application. It represents the data that relates to a particular instance of the application and owns the application UI controller.

Note:

The application framework owns the document object and is responsible for destroying it.

CAknDocument

You must implement a CAknDocument derived class for your application, even if you do not store data, as this is the class that owns the UI controller for your application. The expected syntax for creating the UI controller class is as follows:

CEikAppUi* CMyAppDocument::CreateAppUiL()
    {
    return new ( ELeave ) CMyAppAppUi;
    }

where:

CEikDocument::CreateAppUiL() carries out the first phase construction of the UI controller
new ( ELeave ) CMyAppAppUi is a method that creates an instance of the UI controller class of your application

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, CAknAppUi or CAknViewAppUi.

For more information on the UI controller options, see UI controller

Parent topic: Framework requirements for GUI applications