|
|
The class AddressBook implements the base class for the KDE addressbook. \par Overview It is used by the KabAPI to make the interface to kab files available to application programmers. <BR> 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. <BR> Only one configuration file per user is used, it is <BR> <TT> ~/.kde/share/apps/kab/kab.config </TT> <BR> A standard user file will automatically be created as <BR> <TT> ~/.kde/share/apps/kab/addressbook.kab </TT> <BR> File changes are watched by the program, so every instance will automatically update its database on a change of the opened file.
\par 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. <BR> 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. <BR> kab watches file changes. If the opened file changes on disk, it is automatically reloaded and ::changed() is emitted.
\par 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.
\par 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 <TT> entries </TT> that contains a subsection for every entry. The name of the subsection is the key of the entry. <BR> 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. <BR> 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: <OL> <LI> the user selects an item in the selector combo box, returning its index, </LI> <LI> the index is used to find the key of the entry in the mirror map, </LI> <LI> and finally the entry is retrieved by its key from the database. </LI> </OL> To modify the sorting order, the way to create the entry descriptors in the mirror map nedds to be changed.
\par 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). <BR> Some parts of the AddressBook widget are \e 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.
enum ErrorCode { NoError, PermDenied, Locked, Rejected, NoSuchEntry, NoEntry, NoFile, NoSuchFile, InternError, OutOfRange, NoSuchField, NotImplemented } | ErrorCode |
The return values of some AddressBook member functions are #ErrorCode values.
enum Telephone { NoTelephone, Fixed, Mobile, Fax, Modem, User1, User2, User3, NoOfTelephoneTypes } | Telephone |
Some predefined telephone types. More are possible, but these are provided and thus, for example, translated.
Entry (class) | Entry |
Each entry in a loaded database has its own ::Entry object.
\par The structure of the address database As you might have read, kab uses the QConfigDB class to manage its data files. This class is intended to handle hierarchical structures. Thus, kab is able to create human readable but still deep and complex data files. This paragraph describes the overall structure of the files, the next two deal with special parts of it. <BR> First of all, kab II data files (that usually end with \c .kab, while in kab 1 the fixed file name was \c addressbook.database) have two main sections (see the documentation of the QConfigDB and Section classes), one is called \c config, it contains different file specific configuration settings like the last displayed entry, and one section called \c entries that in turn contains a subsection for each entry in the database file. The keys of this subsections are the literal strings that are used in the KabKey class in the member KabKey::key. Each entry subsection has some key-value-pairs described below and another subsection "addresses" with one or more addresses in it. See the following example for a kab II data file (without any key-value-pairs): <BR> <PRE> [config] [END] [entries] [1] (the first entry with literal key "1") [addresses] [1] (the first address, addresses are enumerated) [END] [2] (the second address) [END] ... (more addresses may follow) [END] [END] [2] (the second entry) [addresses] [1] [END] [END] [END] ... (more entries may follow) [END] </PRE> <BR>
\par The fields an entry contains An entry contains all settings that are expected to be unique for all addresses directly as key-value-pairs. Everything that is part of a specific address of this person is part of an object of the member list \c addresses referenced in the next paragraph. <BR> The keys defined directly in the entry sections are: <DL> <DD> "title" The title of that person. </DD> <DD> "rank" A possible military rank of that person. </DD> <DD> "fn" The formatted name. If it is not empty, it replaces the standard combination of the other name fields in the address display. </DD> <DD> "nameprefix" A possible name prefix. </DD> <DD> "firstname" The first name. </DD> <DD> "middlename" The middle name. </DD> <DD> "lastname" The last name. </DD> <DD> "birthday" The birthday (a QDate). </DD> <DD> "comment" A free form comment. </DD> <DD> "talk" The talk addresses (a string list). </DD> <DD> "emails" The email addresses (a string list). </DD> <DD> "keywords" A list of free-form keywords. </DD> <DD> "telephone" A list of telephone numbers in a special format. </DD> <DD> "URLs" A list of internet addresses. </DD> <DD> "user_1" The first user-declared data field. </DD> <DD> "user_2" The second user-declared data field. </DD> <DD> "user_3" The third user-declared data field. </DD> <DD> "user_4" The fourth user-declared data field. </DD> </DL> See the next section for a description of the addresses subsections.
\par The fields of the addresses subsections The section for each entry contains a subsection \c addresses with in turn a subsection for each address. The addresses are enumerated in the order they are inserted, their keys are the numbers of inserting converted to a string. <BR> The keys defined in an address subsection are: <DL> <DD> "headline" A headline shown for the address. </DD> <DD> "position" The position of the person. </DD> <DD> "org" The organisation. </DD> <DD> "orgunit" The organisational unit. </DD> <DD> "orgsubunit" The organisational subunit. </DD> <DD> "role" The role of the person. </DD> <DD> "deliverylabel" A label for delivering to this address. </DD> <DD> "address" The street, house no., flat etc line. </DD> <DD> "zip" A zip or postal code. </DD> <DD> "town" The town the person lives in in this address. </DD> <DD> "country" The country for federal states. </DD> <DD> "state" The state for federal states. </DD>
\par The local configuration section For each kab II database file there are some settings that apply only to the file itselfes, not to all kab databases the user works with. These settings are called the local configuration. The settings are stored in the \c config section of the local file. The following keys are declared in this section: <DL> <DD> "user_1" The \e name of the first user-declared field. </DD> <DD> "user_2" The \e name of the second user-declared field. </DD> <DD> "user_3" The \e name of the third user-declared field. </DD> <DD> "user_4" The \e name of the fourth user-declared field. </DD> </DL> More fields will surely follow.
AddressBook (QWidget* parent=0, const char* name=0, bool load=true)
| AddressBook |
The constructor. If \e load is true, the user standard file will automatically be loaded into the object.
~AddressBook ()
| ~AddressBook |
ErrorCode getState ()
| getState |
Get the internal state of the object. If no problem occured, it returns ::NoError. If the standard or the latest opened file could not be loaded, it returns ::PermDenied.
ErrorCode load (QString filename="")
| load |
Load the file with the given path. An empty file name reloads the currently opened file.
ErrorCode save (const QString& filename="", bool force=false)
| save |
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. If force is true, the method will switch to r/w mode for saving and back.
ErrorCode closeFile (bool saveit=true)
| closeFile |
Close this file. ::closeFile assures sure that the ::data object is reset no matter of the state of the assigned file. If \a save is true, it will not close the file if it could not be saved.
ErrorCode getEntry (const KabKey& key, Entry&)
| getEntry |
ErrorCode getEntry (const KabKey& key, Section*&)
| getEntry |
ErrorCode getEntries (std::list<Entry>&)
| getEntries |
ErrorCode add (const Entry&, KabKey& key, bool update=true)
| add |
Add an ::Entry, \a return the new key for further operations. If update is false, the mirror map will not be affected, if it is true, the mirror map gets updated, too.
ErrorCode change (const KabKey& key, const Entry&)
| change |
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 remove (const KabKey& key)
| remove |
Remove the entry with the given key. Returns #NoSuchEntry if there is no entry with this key, #PermDenied for read only databases.
unsigned int noOfEntries ()
| noOfEntries |
ErrorCode literalName (const KabKey& key, QString& text,
bool reverse=false, bool initials=false)
| literalName |
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 \a text. If \a reverse is false, the text looks like firstname (add. name) last name, if it is true, + last name, first name (add. name). If \a 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 literalName (const Entry& entry, QString& text,
bool reverse=false, bool initials=false)
| literalName |
This is an overloaded method that differs only in the arguments it takes.
ErrorCode getKey (int index, KabKey&)
| getKey |
ErrorCode getIndex (const KabKey&, int&)
| getIndex |
Get the index of this key in the selector. This is the reverse functionality to getKey().
ErrorCode getListOfNames (QStringList*, bool reverse=true, bool initials=true)
| getListOfNames |
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* getConfig ()
| getConfig |
Section * configurationSection ()
| configurationSection |
This method returns the QConfigDB section where the configuration of the currently opened file is stored. It might be used to retrieve or to modify these settings. The file-specific settings are saved along with the open file. Do not confuse the configuration section of the opened file with the configuration of the program. Each file might have its own local configuration for some settings where it makes sense. @ return Null if no file has been opened.
ErrorCode createNew (const QString& filename="")
| createNew |
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 createConfigFile ()
| createConfigFile |
Creates the local configuration file. The filename is fixed to \c kab.config, it will be created in the local kab directory (\c $HOME/.kde/share/apps/kab). Adapt the global configuration template file (\c $KDEDIR/share/apps/kab/template.config) for unusual site-specific settings. The method does not load the new config file.
ErrorCode loadConfigFile ()
| loadConfigFile |
ErrorCode makeEntryFromVCard (const QString& card, Entry&)
| makeEntryFromVCard |
ErrorCode makeVCardFromEntry (const Entry& entry, QString card)
| makeVCardFromEntry |
QString getStandardFilename ()
| getStandardFilename |
Returns the complete path to the user standard file. An empty path indicates an error, but this should not happen. It is NOT ensured that the file exists.
QString phoneType (AddressBook::Telephone)
| phoneType |
[static]
QConfigDB * config | config |
[protected]
QConfigDB * data | data |
[protected]
StringKabKeyMap * entries | entries |
[protected]
ErrorCode state | state |
[protected]
KabKey nextAvailEntryKey ()
| nextAvailEntryKey |
[protected]
bool isSameFile (const QString& a, const QString& b)
| isSameFile |
[protected]
Returns true if both pathes point to the same file. The method resolves relative file names to find this out.
ErrorCode makeEntryFromSection (Section*, Entry&)
| makeEntryFromSection |
[protected]
Parse the section and copy its contents into \a entry. The method expects a subsection called \e addresses that contains a number of subsections each containing data for one Entry::Address object. All other fields are copied directly into the members of \a entry.
ErrorCode makeAddressFromMap (KeyValueMap*, Entry::Address&)
| makeAddressFromMap |
[protected]
For internal use only. This parses one address subsection and puts its contents in the Address object.
ErrorCode makeSectionFromEntry (const Entry&, Section&)
| makeSectionFromEntry |
[protected]
ErrorCode updateMirrorMap ()
| updateMirrorMap |
[protected]
Section* entrySection ()
| entrySection |
[protected]
Get the entry section of the file. Maybe a NULL pointer if no file is opened.
void reloaded (QConfigDB*)
| reloaded |
[protected slots slot]
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, lock();, /**, 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., lock, QConfigDB::setFileName, */, ErrorCode, unlock();, /**, 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 dataFileChanged ()
| dataFileChanged |
[protected slots slot]
void configFileChanged ()
| configFileChanged |
[protected slots slot]
void externalChange ()
| externalChange |
[slot]
This slot is called when an external object changed the database through the kabapi.
void changed ()
| changed |
[signal]
void setStatus (const QString&)
| setStatus |
[signal]
void newFile (const QString&)
| newFile |
[signal]
Generated by: root@daffy.perf.redhat.com on Mon Jul 14 13:28:26 2003, using kdoc 2.0a53. |