Source Code (Use browser search to find items of interest.)
Class Index
kdelibs'KabAPI (./kdelibs/kab/kabapi.h:78)
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 @ref #init before you can
* use the database.
* @param parent The QWidget pointer to the parent widget.
*/
KabAPI(QWidget* parent=0, const char* name=0);
/** You must call init before accessing the database. init opens the
* database file (usually $HOME/.kde/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 QString& 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 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 AddressBook::Entry& pattern,
std::list<AddressBook::Entry>& entries,
const int max=5);
/** Execute this dialog. This overloads QDialog::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 QString&);
signals:
/** Send status messages. */
void setStatus(const QString&);
// ############################################################################
private:
class KAbAPIPrivate;
KAbAPIPrivate *d;
};
kdelibs'KabAPI::KabAPI() (./kdelibs/kab/kabapi.cc:46)
KabAPI::KabAPI(QWidget* parent, const char* name)
: KDialogBase(parent, name),
book(0),
listbox(new KListBox(this)),
selection(-1)
{
CHECK_PTR(listbox);
setMainWidget(listbox);
showButtonApply(false);
enableButtonSeparator(true);
connect(listbox, SIGNAL(highlighted(int)), SLOT(entrySelected(int)));
}
kdelibs'KabAPI::exec() (./kdelibs/kab/kabapi.cc:59)
int KabAPI::exec()
{
QStringList names;
// -----
if(book==0)
{
kdDebug(KAB_KDEBUG_AREA)
<< "KabAPI::exec: you have to call init before using the API."
<< endl;
return -1;
} else {
if(book->getListOfNames(&names, true, false)==AddressBook::NoError)
{
listbox->clear();
listbox->insertStringList(names);
if(names.count()>0)
{
listbox->setCurrentItem(0);
}
listbox->setMinimumSize(listbox->sizeHint());
adjustSize();
resize(minimumSize());
return KDialogBase::exec();
} else {
kdDebug(KAB_KDEBUG_AREA) << "KabAPI::exec: error creating interface."
<< endl;
return -1;
}
}
}
AddressBook::ErrorCode KabAPI::init()
{
// ############################################################################
book=new AddressBook(0, "KABAPI::book", true); //change parent from "this" to "0" //dsweet
if(book->getState()==AddressBook::NoError)
{
connect(book, SIGNAL(setStatus(const QString&)),
SLOT(setStatusSlot(const QString&)));
return AddressBook::NoError;
} else {
return AddressBook::InternError;
}
// ############################################################################
}
AddressBook::ErrorCode KabAPI::getEntry(AddressBook::Entry& entry, KabKey& key)
{
// ############################################################################
if(book->noOfEntries()==0)
{
return AddressBook::NoEntry;
}
if(selection>=0)
{
if(book->getKey(selection, key)==AddressBook::NoError)
{
if(book->getEntry(key, entry)==AddressBook::NoError)
{
return AddressBook::NoError;
} else {
return AddressBook::InternError; // this may not happen
}
} else {
return AddressBook::NoEntry;
}
} else {
return AddressBook::InternError;
}
// ############################################################################
}
AddressBook::ErrorCode KabAPI::add(const AddressBook::Entry& entry, KabKey& key,
bool update)
{
// ############################################################################
if(book->add(entry, key, update)!=AddressBook::NoError)
{
KMessageBox::sorry(this, i18n("Your new entry could not be added."));
return AddressBook::InternError;
} else {
return AddressBook::NoError;
}
// ############################################################################
}
AddressBook::ErrorCode KabAPI::remove(const KabKey& key)
{
CHECK_PTR(book);
// ############################################################################
if(book->AddressBook::remove(key)==AddressBook::NoError)
{
return AddressBook::NoError;
} else {
return AddressBook::NoEntry;
}
// ############################################################################
}
AddressBook::ErrorCode KabAPI::getEntryByName(const QString&,
list<AddressBook::Entry>&, const int)
{
// ############################################################################
return AddressBook::NotImplemented;
// ############################################################################
}
AddressBook::ErrorCode KabAPI::getEntryByName(const AddressBook::Entry&,
list<AddressBook::Entry>&, const int)
{
// ############################################################################
return AddressBook::NotImplemented;
// ############################################################################
}
AddressBook::ErrorCode KabAPI::getEntries(list<AddressBook::Entry>& entries)
{
kdDebug(KAB_KDEBUG_AREA) << "KabAPI::getEntries: called." << endl;
// ############################################################################
if(book->noOfEntries()==0)
{ // ----- database is valid, but empty:
kdDebug(KAB_KDEBUG_AREA) << "KabAPI::getEntries: no entries." << endl;
return AddressBook::NoEntry;
}
if(!book->getEntries(entries))
{
kdDebug(KAB_KDEBUG_AREA) << "KabAPI::getEntries: intern error." << endl;
return AddressBook::InternError;
} else {
kdDebug(KAB_KDEBUG_AREA) << "KabAPI::getEntries: done." << endl;
return AddressBook::NoError;
}
// ############################################################################
}
kdelibs'KabAPI::addressbook() (./kdelibs/kab/kabapi.cc:194)
AddressBook* KabAPI::addressbook()
{
// ############################################################################
return book;
// ############################################################################
}
AddressBook::ErrorCode KabAPI::save(bool force)
{
// ############################################################################
if(book->save("", force)!=AddressBook::NoError)
{
return AddressBook::PermDenied;
} else {
return AddressBook::NoError;
}
// ############################################################################
}
kdelibs'KabAPI::entrySelected() (./kdelibs/kab/kabapi.cc:213)
void KabAPI::entrySelected(int index)
{
kdDebug(KAB_KDEBUG_AREA) << "KabAPI::entrySelected: entry " << index
<<"selected." << endl;
selection=index;
}
kdelibs'KabAPI::setStatusSlot() (./kdelibs/kab/kabapi.cc:220)
void KabAPI::setStatusSlot(const QString& text)
{
emit(setStatus(text));
}