10.4. Accessing the Address Book

The KDE user is provided with an address book that may be accessed by all KDE applications. This means that, ideally, the user will need to type in (or otherwise collect) contact information only once for someone they know, and then use it to send an email, dial the telephone, send a fax, and so on, depending on what applications become available. You can access the addressbook with the program ABBrowser, part of KDE, or KMail, the KDE mail client.

The address book provides several pieces of information about each entry—with each entry corresponding to one contact—in a class of type AddressBook::Entry defined in addressbook.h Most members of Entry are public variables. For example, the contact's email addresses are stored in a QStringList called Entry::emails. See addressbook.h for a full list of fields.

In the next section, you learn how to select a contact and read its AddressBook::Entry fields.

10.4.1. Selecting a Contact

In the most likely scenario, you will want to access information on a contact that has been chosen by the user of your application. The KDE address book library, libkab, provides a dialog box for this purpose called KabAPI. The following code Listings 10.10–10.12 constructs a class called KabDemo, executes the dialog and displays the name and first email address of the contact chosen.


Example 10.10. kabdemo.h: Class Declaration for KabDemo, a Demonstration of the KDE Address Book

   1 
   2  1: #ifndef __KABDEMO_H__
   3  2: #define __KABDEMO_H__
   4  3:
   5  4: #include <qlabel.h>
   6  5:
   7  6: class KabDemo : public QLabel
   8  7: {
   9  8:  public:
  10  9:   KabDemo (QWidget *parent, const char *name=0);
  11 10: };
  12 11:
  13 12: #endif


Example 10.11. kabdemo.cpp: Class Definition for KabDemo

   1 
   2  1: #include <stdio.h>
   3  2:
   4  3: #include <qlabel.h>
   5  4:
   6  5: #include <kabapi.h>
   7  6:
   8  7: #include "kabdemo.h"
   9  8:
  10  9:
  11 10: KabDemo::KabDemo (QWidget *parent, const char *name=0) :
  12 11:   QLabel ("Text", parent, name)
  13 12: {
  14 13:
  15 14:   KabAPI kabapi (this);
  16 15:   if (kabapi.init()!=AddressBook::NoError)
  17 16:     {
  18 17:       printf ("Error\n");
  19 18:       exit (0);
  20 19:     }
  21 20:
  22 21:   AddressBook::Entry entry;
  23 22:   KabKey key;
  24 23:   if (kabapi.exec())
  25 24:     {
  26 25:       switch (kabapi.getEntry(entry, key))
  27 26:     {
  28 27:     case AddressBook::NoEntry:
  29 28:       printf ("Nothing selected.\n");
  30 29:       break;
  31 30:     case AddressBook::NoError:
  32 31:       {
  33 32:         QString name;
  34 33:         kabapi.addressbook()->literalName(entry, name);
  35 34:         setText ("Name: "+name +"\nEmail: "+entry.emails[0]);
  36 35:       }
  37 36:       break;
  38 37:     default:
  39 38:       printf ("Internal error.\n");
  40 39:     }
  41 40:     }
  42 41: }
  43 

The two most important lines in Listing 10.11 are 15 and 23. Line 15 calls kabapi.init(), which opens and loads the address book, and thus needs to be called before kabapi can be used. Next is line 23, which calls (kabapi.exec()). This executes the KabAPI dialog. When it completes, kabapi will hold the user's selection.

Lines 25–39 show how to process the user's selection (of course, you'd want to process the various cases more elegantly in your application). The method kabapi.getEnty(entry, key) fills in entry and key with the instance AddressBook::Entry describing the user's selection and an associated KabKey (see addressbook.h for the declaration of KabKey). Figure 10.6 shows the KabAPI dialog and Figure 10.7 shows KabDemo displaying the results of the user's selection.


Figure 10.6. The KabAPI dialog box lets the user choose an entry from the address book.



Figure 10.7. KabDemo displays the results of the user's selection.


You can use the main() function provided in Listing 10.12 to complete KabDemo. You will need to link to libkab by passing the option -lkab to g++.


Example 10.12. main.cpp: A main() Function Suitable for Testing KabDemo

   1 
   2  1: #include <kapp.h>
   3  2:
   4  3: #include "kabdemo.h"
   5  4:
   6  5: int
   7  6: main (int argc, char *argv[])
   8  7: {
   9  8:   KApplication kapplication (argc, argv, "kabdemo");
  10  9:
  11 10:   KabDemo *kabdemo  = new KabDemo (0);
  12 11:
  13 12:   kabdemo->show();
  14 13:
  15 14:   return kapplication.exec();
  16 15: }
  17