Nokia N97 SDK
Example Applications Guide

Contacts DB Example

1. About this Example
2. Running the example
3. Architecture
4. Design and Implementation


1. About this Example

The Contacts example demonstrates how to:

This example uses the CContactDatabase and CPbkContactEngine classes for database handling.

This example can be run in both a real S60 device and the emulator provided with the SDK. This example does not involve any configurations.

1.1 APIs demonstrated


1.2 Prerequisites

This example uses the Symbian OS programming concept. Familiarity with it is required in order to fully understand this example.

1.2.1 Emulator

This example does not involve any configurations to the SDK emulator.

1.2.2 S60 device

This example does not involve any configurations to S60 devices.


2. Running the example

When the application starts up and the user presses the Select softkey, the following screen appears:

image2.gif

Pressing the Options softkey displays the following six choices:

image3.gif

Select Default database to open the database. The Phonebook application uses this database.

Selecting Default database from the Open submenu opens the created contact database. If the default contact database is opened, the application title is "Default db”.

image5.gif

Select Contact template to create a contact template.

Selecting Contact template from the Create submenu creates a new contact template. A contact template is a contact item, which is used to initialize the field set for other contact items. The example application does not check if the contact template already exists.

The following dialog appears in the display:

image6.gif

CContactDatabase has the following methods for Contact Template handling:

There can be preset information in the contact template. All contact template information is copied to the new contact items.

Example:

A company name is added to the contact template. When the user adds a new contact to the contact database, a company name is automatically inserted to the new contact items.

image10.gif

The following message appears in the display if a contact database is not opened:

image9.gif

Selecting Edit/View from the Contacts submenu or clicking with the joystick (or similar pointing device) displays the following dialog. Selecting Options menu behaves the same way as if it is opened from the Phonebook application. Selecting Exit from the Options menu closes the contact database example application.

image12.gif

Selecting Create from the Contacts submenu displays the following dialog:

image13.gif

Selecting Delete from the Contacts submenu displays the following dialog displayed below. This shows how to delete a contact. The contact database can be opened or closed. If the contact database is opened, the application closes it before deleting.

image14.gif

Selecting Add to contact group from the Contacts submenu displays the contact groups listbox. This example shows how to add a contact to a contact group.

image15.gif

Select Contacts to display contacts from the selected contact database in the listbox.

Select Groups to display contact groups from the selected contact database in the listbox.

image17.gif

Select Create to create a new contact group. There can be more than one group with the same name in the contact database.

Select Delete to delete selected contact group. This method does not delete contacts from the group.

Selecting Create from the Contact groups submenu displays the following dialog:

image20.gif

Selecting Delete from the Contact groups submenu displays the following dialog:

image21.gif

Select Exit at any time to exit the application.

This use case demonstrates how to create a contacts database, add a contact, a contact group and add a contact to the contact group. The Contacts example is opened for the first time.

  1. Create the new contact database.
  2. Select Create from the Contacts submenu to add the new contact.
  3. Write the contact information and press the Done button.
  4. Select Groups from the Show submenu.
  5. Select Create from the Contact groups submenu.
  6. Enter a name for the contact group.
  7. Select Contacts from the Show submenu.
  8. Select Add to contact group from the Contacts submenu.
  9. Select a group for the contact and press the Select button.
  10. The contact is added to the selected contact group.

3. Architecture

This example makes use of the standard Symbian OS application framework, comprising the Application, Document, UI, and Container classes.

4. Design and Implementation

This section describes the design and implementation of the Contact Database Example. First, the general design of the application is demonstrated, after which separate subsections, describe how the following tasks are implemented:

The following UML diagram illustrates the general architecture of the contact API example application:

image23.gif

In this example CContactDatabase, CPbkContactEngine and CPbkContactEditorDlg are the classes for contacts handling.

4.1 Handling a contact (creating, deleting, editing)

Creating a contact involves the following steps:

4.1.1 Creating a new contact

image24.gif

  1. User selects Create from the Contacts submenu.
  2. AppUI calls AddNewContactDlg function.
  3. A new Phonebook engine object is created and a connection to the file is established.
  4. The contacts dialog resources is loaded.
  5. A new empty contact is created.
  6. The Contacts dialog is launched.
  7. MObjectProvider is set. If the container contained other controls then it would be necessary to call the container's method SetMopParent with the AppUi as parameter.
  8. The Contacts dialog is shown.

4.1.2 Deleting a contact

The following diagram illustrates the contact deletion sequence.

image25.gif

  1. User selects Delete from the Contacts submenu.
  2. AppUI calls the DeleteContactDlg function.
  3. Confirmation dialog is created.
  4. Confirmation dialog is opened with the following query: 'Delete selected contact?’ If the command is cancelled, a jump out occurs.
  5. A new Phonebook engine object is created and connected to the contact database.
  6. Contact is deleted from the contact database.

© Nokia 2009

Back to top