UIQ Classes - How to Access Your Document Class

UIQ uses four types of classes in the implementation of applications. These are an application class, which contains a document class, which contains an application UI class, which contains one or more view classes. In all UIQ applications, application data is handled by the application's document class.

This guide explains the process of accessing the document class in applications you create. Depending on the type of application you write, accessing the document class can be a very common task.

Most often, the document class does not contain the application data directly as member data. Instead, implementing some sort of data-model class, which is owned by the document class, is common practice and recommended. The data-model class is responsible for representing the data. Using a data-model class is not mandatory, but this guide assumes that a data-model class is used.

By using a data-model class, the task of accessing application data is reduced to accessing the document class to get a reference to the data-model class.

Most often, you want to access the document class from a view class. But, there is no reference to the document class created automatically in a view class object. However, a reference to the document class is provided in the application UI class. The application UI class is easily accessed by the view class, so the view class can access the document class thorough the application UI class.

There are two alternative solutions for accessing your document class to get the reference to your data-model class. How often your application accesses the data-model class determines which alternative to use.

The first solution is to call a special function in your application UI class each time you need to access application data. This function returns a pointer to the document class. Use this pointer to access the document class and retrieve a reference to the data-model class. The type of reference this is depends on how you have implemented the data-model class. Use this alternative when access to application data is infrequent.

The second solution is to store a reference that points directly to the data-model class and then use it again and again in your view class. Do this in your application UI class when it creates instances of view classes. Before you create an instance of a view class, retrieve a pointer to your document class by calling a special function. Use this pointer to the document class to get a reference to the data-model class. The type of reference this is depends on how you have implemented the data-model class. Send this, the reference to the data-model class, to the instances of your view classes during construction. Store the data-model reference in local variables in the instances of the view classes. You can then use the reference to access the data-model class directly without having to access the document class each time. Use this alternative when access to application data is frequent.

Your document class, which is derived from CQikDocument, is used for representing the application's data and for containing your application UI class, which is derived from CQikAppUi.

Your document class is easily called from your application UI class. CQikAppUI provides a member variable, iDocument, which is a pointer to your document class. Easy reference to your document class allows easy reference to the data-model class which in turn takes care of data handling.

CQikDocument provides functionality for storing and restoring data. StoreL() and RestoreL() are called from the framework. RestoreL() retrieves data at application startup. StoreL() stores data at application shutdown.

Your application UI class is derived from CQikAppUi. CQikAppUI provides a pointer to the document class. This pointer is protected and therefore Document() is used to return a pointer to the document class which is then used to retrieve a reference to the data-model class.

Your application class contains your view classes.

Your view classes can be derived from CQikViewBase, which is a base class for views. CQikViewBase provides a view with a single page. All UIQ views are derived directly or indirectly from this class.

CQikViewBase handles much of the new functionality found in UIQ 3:

• Constructing views, controls and layouts from resource files,

• Basic focus management,

• Hardware-button navigation between controls,

• Command handling,

• Interface for changing UI configurations in runtime,

• Handling the Context Bar.

The instances of your view classes initiate application data access. CQikViewBase provides a pointer to the application UI class, iQikAppUi. CQikAppUI in turn provides a function, Document(), that returns a reference to the document class.

If access to the data-model class is not frequent, use iQikAppUi.Document() to retrieve a reference to the document class. From there, retrieve a reference to the data-model class. Do this each time you access application data. This is the first method described in the introduction.

If access to the data-model class is frequent, create a reference to the data-model class during construction of the view instance and store it in a local variable. CQikAppUi provides your application UI class with a pointer to the document class, iDocument. Use this to retrieve a reference to the data-model class and then store the reference in a local variable in the view instance. This is the second method described in the introduction.

You may want your application to have views with more than one page. CQikMultiPageViewBase is a base class for views with multiple pages. Since this class inherits from CQikViewBase, all of the functionality described in section 1.3 applies to CQikMultiPageViewBase as well.

An alternative to using CQikMultiPageViewBase for views with multiple pages is to subclass CQikViewBase. However, this should only be attempted if CQikMultiPageViewBase is not sufficient, which is rarely the case.

See UIQ API Reference for more information about CQikDocument, CQikAppUi, CQikViewBase and CQikMultiPageViewBase.

You use four or five base classes to derive the classes for your application. Your document class is derived from CQikDocument, your application class is derived from CQikApplication and your application UI class is derived from CQikAppUi. Furthermore, your application uses view classes, which are derived from CQikViewBase or CQikMultiPageViewBase.

For its view classes, your application can use views derived from CQikViewBase or CQikMultiPageViewBase. These views are marked with "1*" in the diagram. Most likely, your application will have more than one view. You can use any number of views derived from CQikViewBase and any number of views derived from CQikMultiPageViewBase. You can even have some views derived from CQikViewBase and others derived from CQikMultiPageViewBase in the same application.

Use the following #include directive in the header file for your document class:

#include <CQikDocument.h>

Use the following #include directive in the header file your application UI class:

#include <CQikAppUi.h>

Use one of the following #include directives in the header files for your view classes, depending on what type of view is used:

#include <CQikViewBase.h>

#include <CQikMultiPageViewBase.h>

Retrieving and using the document reference is very simple. Below, the two approaches are described. The document reference is only used to retrieve a reference to the data-model class.

2.3.1 Infrequent Access

If your application accesses the document class infrequently, this method is preferable.

From a view class, simply call Document() in your application UI class to get the pointer to your document class. This pointer must be cast to the type of your application's document class:

CMyDocument* Document = static_cast<CMyDocument*>(iQikAppUi.Document());

Then the data-model reference is retrieved, through the document pointer. Exactly how it is retrieved depends on how you have implemented the data-model class.

CMyModel* Model = Document->Model();

From the view class you can then access the application data directly by using code along the lines of "Model.data" and "Model.function()".

2.3.2 Frequent Access

If access to your document class is frequent, it is advisable to create a reference directly to the data-model class, in the view class, during construction of the view instance.

First, your application UI class needs to create a pointer and assign it the iDocument pointer. This pointer has to be cast to the type of your application's document class.

CMyDocument* Document = static_cast<CMyDocument*>(iDocument);

Second, the data-model reference is retrieved, through the document pointer. Exactly how it is retrieved depends on how you have implemented the data-model class.

CMyModel* Model = Document->Model();

Finally, send the model reference to the constructor of the view instance. The view is constructed by NewLC() if you use two-phase construction for your view classes.

CMyView* iView = CMyView::NewLC(*this, KNullViewId, Model);

From the view class you can then access the application data directly by using code along the lines of "Model.data" and "Model.function()".

For this solution to work, you must have declared your constructor method so that it accepts the reference as a parameter.

static CMyView* NewLC(CQikAppUi& aAppUi, const TVwsViewId aParentViewId, CTestAppModel& aModel);

Two-phase construction

The technique of splitting the construction of a class into two parts. The first part is memory assignment and after that pushing the newly created object onto the cleanup stack. This first part must not use any functions or code that can leave. The second part of the construction can use non-leave safe code to initialize the object. See Two Phase Construction in the Symbian OS Guide.