TDE core libraries
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.

kabapi.h 8.2KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220
  1. /* -*- C++ -*-
  2. Dialog widget using the addressbook,
  3. provided for inclusion in other programs.
  4. the TDE addressbook
  5. $ Author: Mirko Boehm $
  6. $ Copyright: (C) 1996-2001, Mirko Boehm $
  7. $ Contact: mirko@kde.org
  8. http://www.kde.org $
  9. $ License: GPL with the following explicit clarification:
  10. This code may be linked against any version of the Qt toolkit
  11. from Troll Tech, Norway. $
  12. $Id$
  13. */
  14. #ifndef KABAPI_H
  15. #define KABAPI_H
  16. #include "addressbook.h"
  17. #include <kdialogbase.h>
  18. class TQPushButton;
  19. class TQFrame;
  20. class TDEListBox;
  21. /**
  22. * The class KabAPI provides a public interface to access the
  23. * users address database created using kab. The complete
  24. * functionality regarding database operations provided by kab is
  25. * available using an object of this class.
  26. *
  27. * The class is derived from the class KDialogBase, thus objects
  28. * can be used as a KDE dialog where the user may select a person
  29. * out of the entries in his personal database.
  30. * The following code may be used to let the user select an address:
  31. * \code
  32. * KabAPI kabapi(this);
  33. * if(dialog.init()!=KabAPI::NoError)
  34. * {
  35. * ... error handling
  36. * }
  37. * AddressBook::Entry entry;
  38. * if(kabapi.exec())
  39. * {
  40. * if(!kabapi.getEntry(entry))
  41. * {
  42. * // ... the database is empty
  43. * } else {
  44. * // ... use the entry
  45. * }
  46. * }
  47. * ...
  48. * \endcode
  49. * Some methods declared here return keys of entries. The keys are of the
  50. * datatype KabKey. Every key
  51. * is (of course) unique and identifying. If you store it, you can access
  52. * the entry it represents with it. Be careful that the entry may have been
  53. * deleted by another program instance meanwhile!
  54. * <tt>Please be careful to test for the return code NotImplemented as
  55. * long the kab API is not completely finished.</tt>
  56. * @short The class KabAPI defines the API to access user address databases.
  57. * @author Mirko Boehm <mirko@kde.org>
  58. * @version $Id$
  59. * @see AddressBook #KDialogBase
  60. */
  61. class KabAPI : public KDialogBase
  62. {
  63. // ############################################################################
  64. Q_OBJECT
  65. // ----------------------------------------------------------------------------
  66. public:
  67. /**
  68. * The constructor creates a KabAPI object, but it does not load the
  69. * database itselfes, as you could not query if this could be done
  70. * without failures. Thus you have to call init before you can
  71. * use the database.
  72. * @param parent The TQWidget pointer to the parent widget.
  73. * @param name The widgets name (used for debugging)
  74. */
  75. KabAPI(TQWidget* parent=0, const char* name=0);
  76. /**
  77. * You must call init before accessing the database. init opens the
  78. * database file (usually $HOME/.trinity/share/apps/kab/addressbook.database)
  79. * and loads its contents.
  80. * @return NoError if all succeeded or a valid ErrorCode.
  81. * @see AddressBook::ErrorCode
  82. */
  83. AddressBook::ErrorCode init();
  84. /**
  85. * Get the addressbook object of this API. This is probably the most powerful
  86. * method in the KabAPI since it allows you to access the database backend
  87. * itselfes.
  88. * If the API has not been initialized (using #init) before, zero is returned.
  89. * @see init
  90. */
  91. AddressBook* addressbook();
  92. /**
  93. * Save the database to the file.
  94. * This method is used to force the database to save its contents.
  95. * If force is true, the method will try to get writing permissions to
  96. * the file if the database is opened readonly. After finishing saving,
  97. * the r/o state is reset. This allows easier file sharing, since by default,
  98. * all files are opened readonly aand closed after all read accesses.
  99. */
  100. AddressBook::ErrorCode save(bool force=false);
  101. /**
  102. * The method getEntry returns the selected entry.
  103. * @return NoError if all succeeded or a valid ErrorCode.
  104. * @see AddressBook::ErrorCode
  105. * @param entry Reference to an AddressBook::Entry -object.
  106. * @param key Reference to a KabKey where the key of the entry is stored.
  107. */
  108. AddressBook::ErrorCode getEntry(AddressBook::Entry& entry, KabKey& key);
  109. /**
  110. * Using the method getEntries, the caller will get a copy of all entries
  111. * in the database. This might seem unneeded, but the address database can be
  112. * used by multiple instances of the kab API at the same time, so that,
  113. * if the programmer wants, for example, print a letter header for all
  114. * persons, the database might change during the operation. That is why
  115. * she can retrieve the whole database in one operation.
  116. * It is required that the referenced list is empty.
  117. * Note that the function returns NoEntry if the database is empty.
  118. * @see AddressBook::ErrorCode
  119. * @short Retrieves all entries out of the database.
  120. * @param entries Reference to a list of entries.
  121. * @return NoError or a valid error code.
  122. */
  123. AddressBook::ErrorCode getEntries(std::list<AddressBook::Entry>& entries);
  124. /**
  125. * The method requires that the database is not opened readonly.
  126. * @short Adds an entry to the users default database.
  127. * @return NoError if all succeeded or a valid ErrorCode, especially PermDenied.
  128. * @param entry Reference to the entry to be added.
  129. * @param key Reference to a KabKey where the key of the new entry is stored.
  130. * @param update Whether to update the mirror map or not.
  131. * Note: The functionality to edit an entry herein has been removed.
  132. */
  133. AddressBook::ErrorCode add(const AddressBook::Entry& entry, KabKey& key,
  134. bool update=true);
  135. /**
  136. * If the preferences of kab say to query before deleting, the user has
  137. * to click "yes" on a message box that appeares.
  138. * If called for a read only database, the method will return
  139. * PermDenied.
  140. * @short Deletes an entry in the database by its key.
  141. * @param key The key of the entry to delete.
  142. * @return NoEntry if there is no entry with this key or another ErrorCode.
  143. */
  144. AddressBook::ErrorCode remove(const KabKey& key);
  145. /**
  146. * Use getEntryByName to find entries that look like the name given.
  147. * The name might be incomplete or diffuse.
  148. * @short This method delivers the closest matches to the given name.
  149. * @param name The name, containing "." for abbreviations.
  150. * @param entries Reference to a list of entries where matches are stored.
  151. * @param max Maximum number of returned entries.
  152. * @return NoError if an entry is found or NoEntry.
  153. */
  154. AddressBook::ErrorCode getEntryByName(const TQString& name,
  155. std::list<AddressBook::Entry>& entries,
  156. const int max=5);
  157. /**
  158. * This method also searches for close matches to the pattern,
  159. * but it compares the whole entry given. This way you can search for,
  160. * for example, nearly similar email addresses. Empty parts of the
  161. * entry are not considered as criteria.
  162. * @short This method delivers the closest matches to the given entry.
  163. * @param pattern The pattern, containing "." for abbreviations.
  164. * @param entries Reference to a list of entries where matches are stored.
  165. * @param max Maximum number of returned entries.
  166. * @return NoError if an entry is found or NoEntry.
  167. */
  168. AddressBook::ErrorCode getEntryByName(const AddressBook::Entry& pattern,
  169. std::list<AddressBook::Entry>& entries,
  170. const int max=5);
  171. /**
  172. * Execute this dialog. This overloads TQDialog::exec to fill the list box
  173. * before showing.
  174. */
  175. int exec();
  176. // ----------------------------------------------------------------------------
  177. protected:
  178. /**
  179. * This is our backend to the users address database.
  180. */
  181. AddressBook* book;
  182. /**
  183. * This displays the overview over the addresses in the dialog.
  184. */
  185. TDEListBox* listbox;
  186. /**
  187. * The index of the selected entry. This value is only valid after the
  188. * KabAPI dialog has been executed and accepted by the user.
  189. */
  190. int selection;
  191. protected slots:
  192. /**
  193. * Capture selections in the dialog (listbox).
  194. */
  195. void entrySelected(int);
  196. /**
  197. * Capture status messages from book.
  198. */
  199. void setStatusSlot(const TQString&);
  200. void slotDoubleClicked ( TQListBoxItem * );
  201. signals:
  202. /**
  203. * Send status messages.
  204. */
  205. void setStatus(const TQString&);
  206. // ############################################################################
  207. private:
  208. class KAbAPIPrivate;
  209. KAbAPIPrivate *d;
  210. };
  211. #endif // KABAPI_H