You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
221 lines
8.2 KiB
221 lines
8.2 KiB
/* -*- C++ -*-
|
|
Dialog widget using the addressbook,
|
|
provided for inclusion in other programs.
|
|
|
|
the KDE addressbook
|
|
|
|
$ Author: Mirko Boehm $
|
|
$ Copyright: (C) 1996-2001, Mirko Boehm $
|
|
$ Contact: mirko@kde.org
|
|
http://www.kde.org $
|
|
$ License: GPL with the following explicit clarification:
|
|
This code may be linked against any version of the Qt toolkit
|
|
from Troll Tech, Norway. $
|
|
|
|
$Id$
|
|
*/
|
|
#ifndef KABAPI_H
|
|
#define KABAPI_H
|
|
|
|
#include "addressbook.h"
|
|
#include <kdialogbase.h>
|
|
|
|
class TQPushButton;
|
|
class TQFrame;
|
|
class KListBox;
|
|
|
|
/**
|
|
* The class KabAPI provides a public interface to access the
|
|
* users address database created using kab. The complete
|
|
* functionality regarding database operations provided by kab is
|
|
* available using an object of this class.
|
|
*
|
|
* The class is derived from the class KDialogBase, thus objects
|
|
* can be used as a KDE dialog where the user may select a person
|
|
* out of the entries in his personal database.
|
|
* The following code may be used to let the user select an address:
|
|
* \code
|
|
* KabAPI kabapi(this);
|
|
* if(dialog.init()!=KabAPI::NoError)
|
|
* {
|
|
* ... error handling
|
|
* }
|
|
* AddressBook::Entry entry;
|
|
* if(kabapi.exec())
|
|
* {
|
|
* if(!kabapi.getEntry(entry))
|
|
* {
|
|
* // ... the database is empty
|
|
* } else {
|
|
* // ... use the entry
|
|
* }
|
|
* }
|
|
* ...
|
|
* \endcode
|
|
* Some methods declared here return keys of entries. The keys are of the
|
|
* datatype KabKey. Every key
|
|
* is (of course) unique and identifying. If you store it, you can access
|
|
* the entry it represents with it. Be careful that the entry may have been
|
|
* deleted by another program instance meanwhile!
|
|
* <tt>Please be careful to test for the return code NotImplemented as
|
|
* long the kab API is not completely finished.</tt>
|
|
* @short The class KabAPI defines the API to access user address databases.
|
|
* @author Mirko Boehm <mirko@kde.org>
|
|
* @version $Id$
|
|
* @see AddressBook #KDialogBase
|
|
*/
|
|
|
|
class KabAPI : public KDialogBase
|
|
{
|
|
// ############################################################################
|
|
Q_OBJECT
|
|
// ----------------------------------------------------------------------------
|
|
public:
|
|
/**
|
|
* The constructor creates a KabAPI object, but it does not load the
|
|
* database itselfes, as you could not query if this could be done
|
|
* without failures. Thus you have to call init before you can
|
|
* use the database.
|
|
* @param parent The TQWidget pointer to the parent widget.
|
|
* @param name The widgets name (used for debugging)
|
|
*/
|
|
KabAPI(TQWidget* parent=0, const char* name=0);
|
|
/**
|
|
* You must call init before accessing the database. init opens the
|
|
* database file (usually $HOME/.trinity/share/apps/kab/addressbook.database)
|
|
* and loads its contents.
|
|
* @return NoError if all succeeded or a valid ErrorCode.
|
|
* @see AddressBook::ErrorCode
|
|
*/
|
|
AddressBook::ErrorCode init();
|
|
/**
|
|
* Get the addressbook object of this API. This is probably the most powerful
|
|
* method in the KabAPI since it allows you to access the database backend
|
|
* itselfes.
|
|
* If the API has not been initialized (using #init) before, zero is returned.
|
|
* @see init
|
|
*/
|
|
AddressBook* addressbook();
|
|
/**
|
|
* Save the database to the file.
|
|
* This method is used to force the database to save its contents.
|
|
* If force is true, the method will try to get writing permissions to
|
|
* the file if the database is opened readonly. After finishing saving,
|
|
* the r/o state is reset. This allows easier file sharing, since by default,
|
|
* all files are opened readonly aand closed after all read accesses.
|
|
*/
|
|
AddressBook::ErrorCode save(bool force=false);
|
|
/**
|
|
* The method getEntry returns the selected entry.
|
|
* @return NoError if all succeeded or a valid ErrorCode.
|
|
* @see AddressBook::ErrorCode
|
|
* @param entry Reference to an AddressBook::Entry -object.
|
|
* @param key Reference to a KabKey where the key of the entry is stored.
|
|
*/
|
|
AddressBook::ErrorCode getEntry(AddressBook::Entry& entry, KabKey& key);
|
|
/**
|
|
* Using the method getEntries, the caller will get a copy of all entries
|
|
* in the database. This might seem unneeded, but the address database can be
|
|
* used by multiple instances of the kab API at the same time, so that,
|
|
* if the programmer wants, for example, print a letter header for all
|
|
* persons, the database might change during the operation. That is why
|
|
* she can retrieve the whole database in one operation.
|
|
* It is required that the referenced list is empty.
|
|
* Note that the function returns NoEntry if the database is empty.
|
|
* @see AddressBook::ErrorCode
|
|
* @short Retrieves all entries out of the database.
|
|
* @param entries Reference to a list of entries.
|
|
* @return NoError or a valid error code.
|
|
*/
|
|
AddressBook::ErrorCode getEntries(std::list<AddressBook::Entry>& entries);
|
|
/**
|
|
* The method requires that the database is not opened readonly.
|
|
* @short Adds an entry to the users default database.
|
|
* @return NoError if all succeeded or a valid ErrorCode, especially PermDenied.
|
|
* @param entry Reference to the entry to be added.
|
|
* @param key Reference to a KabKey where the key of the new entry is stored.
|
|
* @param update Whether to update the mirror map or not.
|
|
* Note: The functionality to edit an entry herein has been removed.
|
|
*/
|
|
AddressBook::ErrorCode add(const AddressBook::Entry& entry, KabKey& key,
|
|
bool update=true);
|
|
/**
|
|
* If the preferences of kab say to query before deleting, the user has
|
|
* to click "yes" on a message box that appeares.
|
|
* If called for a read only database, the method will return
|
|
* PermDenied.
|
|
* @short Deletes an entry in the database by its key.
|
|
* @param key The key of the entry to delete.
|
|
* @return NoEntry if there is no entry with this key or another ErrorCode.
|
|
*/
|
|
AddressBook::ErrorCode remove(const KabKey& key);
|
|
/**
|
|
* Use getEntryByName to find entries that look like the name given.
|
|
* The name might be incomplete or diffuse.
|
|
* @short This method delivers the closest matches to the given name.
|
|
* @param name The name, containing "." for abbreviations.
|
|
* @param entries Reference to a list of entries where matches are stored.
|
|
* @param max Maximum number of returned entries.
|
|
* @return NoError if an entry is found or NoEntry.
|
|
*/
|
|
AddressBook::ErrorCode getEntryByName(const TQString& name,
|
|
std::list<AddressBook::Entry>& entries,
|
|
const int max=5);
|
|
/**
|
|
* This method also searches for close matches to the pattern,
|
|
* but it compares the whole entry given. This way you can search for,
|
|
* for example, nearly similar email addresses. Empty parts of the
|
|
* entry are not considered as criteria.
|
|
* @short This method delivers the closest matches to the given entry.
|
|
* @param pattern The pattern, containing "." for abbreviations.
|
|
* @param entries Reference to a list of entries where matches are stored.
|
|
* @param max Maximum number of returned entries.
|
|
* @return NoError if an entry is found or NoEntry.
|
|
*/
|
|
AddressBook::ErrorCode getEntryByName(const AddressBook::Entry& pattern,
|
|
std::list<AddressBook::Entry>& entries,
|
|
const int max=5);
|
|
/**
|
|
* Execute this dialog. This overloads TQDialog::exec to fill the list box
|
|
* before showing.
|
|
*/
|
|
int exec();
|
|
// ----------------------------------------------------------------------------
|
|
protected:
|
|
/**
|
|
* This is our backend to the users address database.
|
|
*/
|
|
AddressBook* book;
|
|
/**
|
|
* This displays the overview over the addresses in the dialog.
|
|
*/
|
|
KListBox* listbox;
|
|
/**
|
|
* The index of the selected entry. This value is only valid after the
|
|
* KabAPI dialog has been executed and accepted by the user.
|
|
*/
|
|
int selection;
|
|
protected slots:
|
|
/**
|
|
* Capture selections in the dialog (listbox).
|
|
*/
|
|
void entrySelected(int);
|
|
/**
|
|
* Capture status messages from book.
|
|
*/
|
|
void setStatusSlot(const TQString&);
|
|
void slotDoubleClicked ( TQListBoxItem * );
|
|
signals:
|
|
/**
|
|
* Send status messages.
|
|
*/
|
|
void setStatus(const TQString&);
|
|
// ############################################################################
|
|
private:
|
|
class KAbAPIPrivate;
|
|
KAbAPIPrivate *d;
|
|
};
|
|
|
|
#endif // KABAPI_H
|
|
|