Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded |

# Qtopia PIM Library Overview

- Introduction
- Overview of Classes
  - Value classes
  - Access classes
  - Iterator classes
- Using the Qtopia PIM Library
- PIM Change signals
- Data Refresh

## Introduction

The Qtopia PIM library provides a set of safe APIs for accessing Qtopia PIM data and provides a smooth transition to the next major revision of Qtopia. Specifically, classes are provided to retrieve, edit, and save Contacts, Tasks, and Events. The access classes attempt to keep themselves in sync with Qtopia's AddressBook, Todo, and Datebook applications, and any other applications.

## Overview of Classes

There are three types of data represented in the PIM library, contacts, events and tasks. For each data type there is three different types of classes to access that data. A Value class, an Access class and an Iterator class.

Value class | Access class | Iterator class
--- | --- | ---
PimContact | AddressBookAccess | AddressBookIterator
PimEvent | DateBookAccess | DateBookIterator
PimTask | TodoAccess | TodoIterator

### Value classes

The Value class is the class used to pass around data for the particular kind of PIM data. For example the PimEvent class is used to get the description of an event, and determine when the event will next occur. It is also this class that you would use to pass the data between applications.

### Access classes

The Access class is used to access the database or table for a particular kind of PIM data. To get the list of contacts first you need to create an instance of AddressBookAccess. This is also the class used to add or update records.

### Iterator classes

The Iterator class is for traversing the stored list of data for a particular kind of PIM data. To determine what PimTasks remain open an application would create a TodoIterator using a TodoAccess instance, and then use the TodoIterator to traverse over each PimTask. It is recommend that an instance of an Iterator class is kept only as long as needed. The PIM library hides the type of storage used for the PIM data, and due to performance reasons keeping an Iterator class while not needed may affect notifications of updates to the PIM data.

## Using the Qtopia PIM Library

This example reads a list of open tasks and then displays a label detailing the tasks. First a TodoAccess instance is created to load the data for Tasks. Then a TodoIterator is initialized from the TodoAccess to traverse the data. For each item a PimTask is created to get the completion status of the task and the description of the task.

    #include <qtextbrowser.h>
    #include <qtopia/qpeapplication.h>
    #include <qtopia/todoaccess.h>

    class TaskList : public QTextBrowser
    {
    public:
        TaskList(QWidget *parent)
            : QTextBrowser(parent)
        {
            QString text;
            TodoAccess a;
            TodoIterator it(a);
            for(;it.current(); ++it) {
                PimTask t(*it);
                if (!t.isCompleted()) {
                    text += "ITEM: " + t.description() + "<BR>";
                }
            }
            setText(text);
        }
    };

    int main(int argc, char **argv)
    {
        QPEApplication qpe(argc, argv);

        TaskList *tl = new TaskList(0);
        qpe.showMainWindow(tl);
        return qpe.exec();
    }

## PIM Change signals

The access class listen for various QCop calls to keep in sync with the main pim applications. When an access class detects an update it will emit a signal indicating it has been udpated.

## Data Refresh

The Qtopia PIM Library will always try to return the most current data to the user. This is done by monitoring the time stamp on the actual data file as well as listening for QPE/PIM messages that are relavent to the data files used by the specific accessor. If a QPE/PIM message is received that indicates the data has been updated the accessor will emit a signal indicating the event and during the next data query the Qtopia PIM Library will refresh its internal caches. Note that since Qtopia PIM Library does not employ a polling mechanism simply touching the data file will not trigger the event to be emitted, however it will be detected the next time data is requested.