Compound list   Compound Members  

AddressBook Class Reference

The class AddressBook implements the base class for the KDE addressbook. More...

List of all members.

Public Members

Signals

Protected Members

Protected Slots


Detailed Description

The class AddressBook implements the base class for the KDE addressbook.

Overview
It is used by the KabAPI to make the interface to kab files available to application programmers.
Unlike in the first kab version, the configuration file and the data file are different objects of QConfigDB. This way, the data file is no more limited to the one in the users KDE directory, multiple files may be used. Different instances of the program may use different data files. Read-only addressbook files are possible.
Only one configuration file per user is used, it is
~/.kde/share/apps/kab/kab.config
A standard user file will automatically be created as
~/.kde/share/apps/kab/addressbook.kab
File changes are watched by the program, so every instance will automatically update its database on a change of the opened file.

The KDE addressbook database system
kab manages entries in address databases based on a key system where the program assigns keys to added entries. These keys are not reused in one file, so API users can rely on a key to be unique and identifying until the entry is deleted by the user (this is a change to kab 1 that reused freed entry keys). Of course, in different files a key might be used twice.
The keys are objects of the type KabKey and define the section in the addressbook database where the entry is stored (see QConfigDB reference). Keys invalidate on file changes, so keep track of the signal changed().
kab watches file changes. If the opened file changes on disk, it is automatically reloaded and changed() is emitted.

The users standard personal information database
kab assumes that it is able to read and write the users standard database. This way, the kab application itselfes and applications using the KabAPI can rely on the possibility to add entries to this database (from a browser, for example). Usually, this file is opened automatically by the constructor. If - for what reason ever - the file cannot be either created or read, kab will still start up, but no database operation will work until the user opened a file. In this case, the method getState() will return PermDenied. In general it is a good idea to check the return value of the getState() method before using KabAPI operations.

The mirror map
The entries are stored in the QConfigDB object data which represents the currently opened file. In every file there is a section with the name entries that contains a subsection for every entry. The name of the subsection is the key of the entry.
When retrieving the sections, they are ordered alphabetically by their keys. This is not what users expect, since the keys show the insertion order of the entries, not more and not less. Additionally the displaying order should be configurable.
That is why kab uses a STL map to map its entry keys to user (at least programmer...) defined descriptors. Usually, the descriptors are created as a combination of the entry data, and then displayed in aphabetical order in the selector combobox. This map is called the mirror map throughout the documentation. It is created or updated everytime the database changes. Thus the way to find a special entry is:
  1. the user selects an item in the selector combo box, returning its index,
  2. the index is used to find the key of the entry in the mirror map,
  3. and finally the entry is retrieved by its key from the database.
To modify the sorting order, the way to create the entry descriptors in the mirror map nedds to be changed.

The view
If you display an AddressBook object (that is a derived QFrame), it may show an entry of the database that you might select. The entry you hand over to the method displayEntry() does not need to be contained in the currently loaded file. This way you may integrate views of the users addressbook database in your own application as a simple widget type. To allow the user to navigate through the database, you might want to show kab's own toolbar in your mainwindow (or whereever). (The toolbar is not implemented by now).
Some parts of the AddressBook widget are interactive, that means they are displayed as transparent KURLLabels that react when the user clicks on it. These interactive parts have to be enabled by calling setInteractiveMode().


Member Enumeration Type Documentation

enum AddressBook::ErrorCode

The return values of some AddressBook member functions are ErrorCode values.

Enumeration values:


Member Function Documentation

AddressBook::AddressBook(QWidget* parent=0, const char* name=0)

The Qt standard constructor.

AddressBook::~AddressBook()

The destructor.

ErrorCode AddressBook::getState()

Get the internal state of the object.

If no problem occured, it returns NoError. If the standard database could not be loaded, it returns PermDenied.

ErrorCode AddressBook::load(QString filename="")

Load the file with the given path.

An empty file name reloads the currently opened file.

ErrorCode AddressBook::save(const QString& filename="")

Save the file to the given path and file name.

An empty file name saves to the file where the database has been read from.

ErrorCode AddressBook::closeFile(bool saveit=true)

Close this file.

close makes sure that the data object is reset no matter of the state of the assigned file. If save is true, it will not close the file if it could not be saved.

ErrorCode AddressBook::getEntry(const KabKey& key, Entry&)

Retrieve an entry from the database by its key.

ErrorCode AddressBook::getEntry(const KabKey& key, Section*&)

Retrieve the Section of the entry directly, returning a section object.

ErrorCode AddressBook::getEntries(list<Entry>&)

Get all entries in displaying order.

This method might be slow (O(n)).

ErrorCode AddressBook::add(const Entry&, KabKey& key)

Add an Entry, return the new key for further operations.

ErrorCode AddressBook::change(const KabKey& key, const Entry&)

Set the entry with the given key to the new contents.

Be aware of PermDenied for read-only databases or file sharing conflicts. You cannot change entries in a database for which you do not have write access.

ErrorCode AddressBook::remove(const KabKey& key)

Remove the entry with the given key.

Returns NoSuchEntry if there is no entry with this key, PermDenied for read only databases.

unsigned int AddressBook::noOfEntries()

Returns the number of entries in the loaded database.

ErrorCode AddressBook::literalName(const KabKey& key, QString& text, bool reverse=false, bool initials=false)

This method returns the literal name for the entry, containing either the formatted name (if given) or a combination of the first, additional and last name.

The name is returned in text. If reverse is false, the text looks like firstname (add. name) last name, if it is true, + last name, first name (add. name). If initials is true, the text contains initials only: f. a. name [with reverse==false] or name, f. a. [with reverse==true]. If there is no entry with this key, the method returns NoSuchEntry.

ErrorCode AddressBook::literalName(const Entry& entry, QString& text, bool reverse=false, bool initials=false)

This is an overloaded method that differs only in the arguments it takes.

ErrorCode AddressBook::getKey(int index, KabKey&)

Get the key of the item in the selector with the given index.

ErrorCode AddressBook::displayEntry(const AddressBook::Entry&, int index=0)

Display this entry.

If the entry has more than one address, the address at index index is displayed.

ErrorCode AddressBook::displayEntry(int position, int address=0)

Display the entry at the index position in the current file.

The index is the position of the entries description in the string list return by getListOfName, or the position of the entry in the mirror map. If the index is out of range, NoSuchEntry is returned.

ErrorCode AddressBook::getListOfNames(QStrList*)

Fill the string list with name lines.

If your application shows a combobox containing an overview over the currently loaded KabAPI database, then call this method when receiving the signal changed() and display the list in the combo.

QConfigDB* AddressBook::getConfig()

Hand over the configuration database.

Careful!

ErrorCode AddressBook::configureFile()

This method opens a dialog for configuring the file-specific settings for the loaded file.

The database is automatically saved if the user accepts the changes.

ErrorCode AddressBook::createNew(const QString& filename="")

Creates a new database with the given file name.

If the filename is empty, it creates the users standard data file. The method does not load the new database.

ErrorCode AddressBook::createConfigFile()

Creates the local configuration file.

The filename is fixed to kab.config, it will be created in the local kab directory ($HOME/.kde/share/apps/kab). Adapt the global configuration template file ($KDEDIR/share/apps/kab/template.config) for unusual site-specific settings. The method does not load the new config file.

ErrorCode AddressBook::loadConfigFile()

Load the local configuration file.

ErrorCode AddressBook::configureKab()

Open the configuration dialog for the KabAPI.

QSize AddressBook::sizeHint()

The preferred (minimal) size of the view.

ErrorCode AddressBook::makeEntryFromVCard(const QString& card, Entry&)

This method parses a vCard and creates an Entry object from it.

ErrorCode AddressBook::makeVCardFromEntry(const Entry& entry, QString card)

This method creates a vCard string from an entry.

void AddressBook::changed() [signal]

The entries have changed, update the selector.

void AddressBook::browse(const char*) [signal]

The user clicked on the homepage URL.

void AddressBook::mail(const char*) [signal]

The user clicked on the email address.

void AddressBook::edit() [signal]

The user double-clicked the address display.

void AddressBook::setStatus(const char*) [signal]

This is kab radio with the news..

void AddressBook::newFile(const char*) [signal]

Notifies changes of the file name.

void AddressBook::paintEvent(QPaintEvent*) [protected]

The paint event.

void AddressBook::resizeEvent(QResizeEvent*) [protected]

The resize event.

KabKey AddressBook::nextAvailEntryKey() [protected]

Get the next available entry key for this file.

For internal use only.

bool AddressBook::isSameFile(const QString& a, const QString& b) [protected]

Returns true if both pathes point to the same file.

The method resolves relative file names to find this out.

ErrorCode AddressBook::makeEntryFromSection(Section*, Entry&) [protected]

Parse the section and copy its contents into entry.

The method expects a subsection called addresses that contains a number of subsections each containing data for one Address object. All other fields are copied directly into the members of entry.

ErrorCode AddressBook::makeSectionFromEntry(const Entry&, Section&) [protected]

Create a section from the entries settings.

ErrorCode AddressBook::updateMirrorMap() [protected]

Update the mirror map after changes of the database.

Section* AddressBook::entrySection() [protected]

Get the entry section of the file.

Maybe a NULL pointer if no file is opened.

ErrorCode AddressBook::lock() [protected]

Lock the file for changing.

Since all database files are opened read-only, they must be locked before the files contents are changed. After changing the file must be saved and unlocked. Returns PermDenied if the file could not be locked, NoError if it was not locked and is now, and Locked if the file is already locked.

See also:
unlock() , QConfigDB::setFileName()

ErrorCode AddressBook::unlock() [protected]

Unlock the file after changes.

Returns NoError if the file was locked and could be unlocked, PermDenied if the file was not locked and possibly InternError if anything fails.

See also:
lock() , QConfigDB::setFileName()

void AddressBook::setBackground(const QImage&) [protected]

Set the background image.

Kab will store a deep copy of the image. If the image is a null image nothing will be displayed.

void AddressBook::setBackgroundEnabled(bool state) [protected]

Enable or disable the background image.

bool AddressBook::getBackgroundEnabled() [protected]

Retrieve wether the background image is enabled or not.

void AddressBook::setInteractiveMode(bool state) [protected]

Set if the URL labels are interactive.

bool AddressBook::getInteractiveMode() [protected]

Get if the URL labels are interactive.

void AddressBook::reloaded(QConfigDB*) [protected, slot]

Called when data has been cleared or reloaded.

void AddressBook::dataFileChanged() [protected, slot]

Called when the file assigned to data has changed on disk.

void AddressBook::configFileChanged() [protected, slot]

Called when the file assigned to config has changed on disk.

void AddressBook::appearanceChanged() [protected, slot]

Called on kapp->appearanceChanged.

void AddressBook::mailURLClicked(const char*) [protected, slot]

\internal.

void AddressBook::homeURLClicked(const char*) [protected, slot]

\internal.

void AddressBook::addressSelected(int) [protected, slot]

\internal.


Member Data Documentation

QConfigDB* AddressBook::config [protected]

The configuration database.

QConfigDB* AddressBook::data [protected]

The currently open data files.

QImage* AddressBook::background [protected]

The background pattern, a null image by default.

bool AddressBook::backgroundEnabled [protected]

If true, the background image is displayed.

StringKabKeyMap* AddressBook::entries [protected]

The mirror map.

ErrorCode AddressBook::state [protected]

The internal state of the object.

Entry AddressBook::current [protected]

The entry that is displayed now.

int AddressBook::currentAddress [protected]

The address of the entry that has been selected.

KURLLabel* AddressBook::urlEmail [protected]

The interactive email line.

KURLLabel* AddressBook::urlHomepage [protected]

The interactive URL line.

bool AddressBook::urlsEnabled [protected]

Wether the interactive mode is enabled or not.

KDataNavigator* AddressBook::addressNav [protected]

The navigator for selecting the address.


The documentation for this class was generated from the following file:

The KDE Addressbook Developers Reference 
Mirko Sucker, 1999