/*
Dialog widget using the addressbook ,
provided for inclusion in other programs .
the TDE 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 TDEListBox ;
/**
* 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
{
// ############################################################################
TQ_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 .
*/
TDEListBox * 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