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
- enum ErrorCode { NoError ,
PermDenied ,
Locked ,
Rejected ,
NoSuchEntry ,
NoFile ,
NoSuchFile ,
InternError ,
OutOfRange ,
NotImplemented
}
- The return values of some AddressBook member functions are ErrorCode values.
- AddressBook (QWidget* parent=0, const char* name=0)
- The Qt standard constructor.
- ~AddressBook ()
- The destructor.
- ErrorCode getState ()
- Get the internal state of the object.
- ErrorCode load (QString filename="")
- Load the file with the given path.
- ErrorCode save (const QString& filename="")
- Save the file to the given path and file name.
- ErrorCode closeFile (bool saveit=true)
- Close this file.
- ErrorCode getEntry (const KabKey& key, Entry&)
- Retrieve an entry from the database by its key.
- ErrorCode getEntry (const KabKey& key, Section*&)
- Retrieve the Section of the entry directly, returning a section object.
- ErrorCode getEntries (list<Entry>&)
- Get all entries in displaying order.
- ErrorCode add (const Entry&, KabKey& key)
- Add an Entry, return the new key for further operations.
- ErrorCode change (const KabKey& key, const Entry&)
- Set the entry with the given key to the new contents.
- ErrorCode remove (const KabKey& key)
- Remove the entry with the given key.
- unsigned int noOfEntries ()
- Returns the number of entries in the loaded database.
- ErrorCode 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.
- ErrorCode 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 getKey (int index, KabKey&)
- Get the key of the item in the selector with the given index.
- ErrorCode displayEntry (const AddressBook::Entry&, int index=0)
- Display this entry.
- ErrorCode displayEntry (int position, int address=0)
- Display the entry at the index position in the current file.
- ErrorCode getListOfNames (QStrList*)
- Fill the string list with name lines.
- QConfigDB* getConfig ()
- Hand over the configuration database.
- ErrorCode configureFile ()
- This method opens a dialog for configuring the file-specific settings for the loaded file.
- ErrorCode createNew (const QString& filename="")
- Creates a new database with the given file name.
- ErrorCode createConfigFile ()
- Creates the local configuration file.
- ErrorCode loadConfigFile ()
- Load the local configuration file.
- ErrorCode configureKab ()
- Open the configuration dialog for the KabAPI.
- QSize sizeHint ()
- The preferred (minimal) size of the view.
- ErrorCode makeEntryFromVCard (const QString& card, Entry&)
- This method parses a vCard and creates an Entry object from it.
- ErrorCode makeVCardFromEntry (const Entry& entry, QString card)
- This method creates a vCard string from an entry.
Signals
- void changed ()
- The entries have changed, update the selector.
- void browse (const char*)
- The user clicked on the homepage URL.
- void mail (const char*)
- The user clicked on the email address.
- void edit ()
- The user double-clicked the address display.
- void setStatus (const char*)
- This is kab radio with the news..
- void newFile (const char*)
- Notifies changes of the file name.
Protected Members
- void paintEvent (QPaintEvent*)
- The paint event.
- void resizeEvent (QResizeEvent*)
- The resize event.
- KabKey nextAvailEntryKey ()
- Get the next available entry key for this file.
- bool isSameFile (const QString& a, const QString& b)
- Returns true if both pathes point to the same file.
- ErrorCode makeEntryFromSection (Section*, Entry&)
- Parse the section and copy its contents into entry.
- ErrorCode makeSectionFromEntry (const Entry&, Section&)
- Create a section from the entries settings.
- ErrorCode updateMirrorMap ()
- Update the mirror map after changes of the database.
- Section* entrySection ()
- Get the entry section of the file.
- ErrorCode lock ()
- Lock the file for changing.
- ErrorCode unlock ()
- Unlock the file after changes.
- void setBackground (const QImage&)
- Set the background image.
- void setBackgroundEnabled (bool state)
- Enable or disable the background image.
- bool getBackgroundEnabled ()
- Retrieve wether the background image is enabled or not.
- void setInteractiveMode (bool state)
- Set if the URL labels are interactive.
- bool getInteractiveMode ()
- Get if the URL labels are interactive.
- QConfigDB* config
- The configuration database.
- QConfigDB* data
- The currently open data files.
- QImage* background
- The background pattern, a null image by default.
- bool backgroundEnabled
- If true, the background image is displayed.
- StringKabKeyMap* entries
- The mirror map.
- ErrorCode state
- The internal state of the object.
- Entry current
- The entry that is displayed now.
- int currentAddress
- The address of the entry that has been selected.
- KURLLabel* urlEmail
- The interactive email line.
- KURLLabel* urlHomepage
- The interactive URL line.
- bool urlsEnabled
- Wether the interactive mode is enabled or not.
- KDataNavigator* addressNav
- The navigator for selecting the address.
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:
- the user selects an item in the selector combo box, returning its
index,
- the index is used to find the key of the entry in the mirror map,
- 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:
- NoError
No error, the operation did not fail.
- PermDenied
Access permissions for the operation are not available.
- Locked
An writing operation on a locked file was requested.
- Rejected
The requested operation has been rejected by the user.
- NoSuchEntry
An entry has been referenced using a unknown key.
- NoFile
No file has been loaded by now.
- NoSuchFile
A filename could not be found on the filesystem.
- InternError
A error in kab's internal logic occured.
- OutOfRange
An index value was out of the allowed range.
- NotImplemented
The requested operation is not implemented.
Member Function Documentation
AddressBook::AddressBook(QWidget* parent=0, const char* name=0)
The Qt standard constructor.
AddressBook::~AddressBook()
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.
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.
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]
void AddressBook::resizeEvent(QResizeEvent*) [protected]
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]
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]
void AddressBook::homeURLClicked(const char*) [protected, slot]
void AddressBook::addressSelected(int) [protected, slot]
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]
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
|