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.

addressbook.h 29KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734
  1. /* -*- C++ -*-
  2. This file declares the basic personal information management class
  3. used in the TDE addressbook.
  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 ADDRESSBOOK_H
  15. #define ADDRESSBOOK_H
  16. class KeyValueMap;
  17. class QConfigDB;
  18. class Section;
  19. class StringKabKeyMap; /* The type of the mirror map. */
  20. class TQStringList;
  21. /* Used to implement field lookup accoording to
  22. keys. */
  23. class KeyNameMap;
  24. #include <list>
  25. #include <tqframe.h>
  26. #include <tqdatetime.h>
  27. #include <tqstring.h>
  28. #include <tqsize.h>
  29. #include <tqvariant.h>
  30. #include <tqmap.h>
  31. /**
  32. * The class KabKey is used to select entries out of the database file.
  33. * In future, keys might become more complex.
  34. */
  35. class KabKey
  36. {
  37. public:
  38. /**
  39. * The comparison operator
  40. */
  41. bool operator==(const KabKey&) const;
  42. /**
  43. * Get the key as a QCString
  44. */
  45. TQCString getKey() const;
  46. /**
  47. * Set this key
  48. */
  49. void setKey(const TQCString&);
  50. protected:
  51. /**
  52. * The key of the in this database
  53. */
  54. TQCString key;
  55. class KabKeyPrivate;
  56. KabKeyPrivate *d;
  57. };
  58. class CategoriesMap : public TQMap<int, TQString>
  59. {
  60. };
  61. // -----------------------------------------------------------------------------
  62. // this will be incremented when kab's file format changes significantly:
  63. #if defined KAB_FILE_FORMAT
  64. #undef KAB_FILE_FORMAT
  65. #endif
  66. /*
  67. 0: all formats before the email list was implemented
  68. 1: format enhanced for unlimited number of email addresses
  69. 2: format enhanced by more address fields
  70. 10: format of kab 2
  71. 11: added categories
  72. */
  73. #define KAB_FILE_FORMAT 11
  74. // -----------------------------------------------------------------------------
  75. // this defines will contain the program version used for different purposes:
  76. #ifdef KAB_VERSION
  77. #undef KAB_VERSION
  78. #endif
  79. #ifdef KAB_MINOR
  80. #undef KAB_MINOR
  81. #endif
  82. #ifdef KAB_PATCH
  83. #undef KAB_PATCH
  84. #endif
  85. #ifdef KAB_STATE
  86. #undef KAB_STATE
  87. #endif
  88. #define KAB_VERSION 2
  89. #define KAB_MINOR 2
  90. #define KAB_PATCH 0
  91. #define KAB_STATE "final"
  92. // -----------------------------------------------------------------------------
  93. /** The class AddressBook implements the base class for the TDE addressbook.
  94. * \par Overview
  95. * It
  96. * is used by the KabAPI to make the interface to kab files available to
  97. * application programmers. <BR>
  98. * Unlike in the first kab version, the configuration file and the data file are
  99. * different objects of QConfigDB. This way, the data file is no more limited
  100. * to the one in the users KDE directory, multiple files may be used. Different
  101. * instances of the program may use different data files. Read-only addressbook
  102. * files are possible. <BR>
  103. * Only one configuration file per user is used, it is <BR>
  104. * <TT> ~/.trinity/share/apps/kab/kab.config </TT> <BR>
  105. * A standard user file will automatically be created as <BR>
  106. * <TT> ~/.trinity/share/apps/kab/addressbook.kab </TT> <BR>
  107. * File changes are watched by the program, so every instance will automatically
  108. * update its database on a change of the opened file.
  109. *
  110. * \par The TDE addressbook database system
  111. * kab manages entries in address databases based on a key system where the
  112. * program assigns keys to added entries. These keys are not reused in one file,
  113. * so API users can rely on a key to be unique and identifying until the entry
  114. * is deleted by the user (this is a change to kab 1 that reused freed entry
  115. * keys). Of course, in different files a key might be used twice. <BR>
  116. * The keys are objects of the type KabKey and define the section in the
  117. * addressbook database where the entry is stored (see QConfigDB
  118. * reference). Keys invalidate on file changes, so keep track of the
  119. * signal ::changed. <BR>
  120. * kab watches file changes. If the opened file changes on disk, it is
  121. * automatically reloaded and ::changed() is emitted.
  122. *
  123. * \par The users standard personal information database
  124. * kab assumes that it is able to read and write the users standard database.
  125. * This way, the kab application itselfes and applications using the KabAPI can
  126. * rely on the possibility to add entries to this database (from a browser, for
  127. * example). Usually, this file is opened automatically by the constructor.
  128. * If - for what reason ever - the file cannot be either created or read, kab
  129. * will still start up, but no database operation will work until the user
  130. * opened a file. In this case, the method ::getState will return
  131. * ::PermDenied. In general it is a good idea to check the return value of the
  132. * ::getState method before using KabAPI operations.
  133. *
  134. * \par The mirror map
  135. * The entries are stored in the QConfigDB object ::data which represents the
  136. * currently opened file. In every file there is a section with the name
  137. * <TT> entries </TT> that contains a subsection for every entry. The name of
  138. * the subsection is the key of the entry. <BR>
  139. * When retrieving the sections, they are ordered alphabetically by their keys.
  140. * This is not what users expect, since the keys show the insertion order of
  141. * the entries, not more and not less. Additionally the displaying order should
  142. * be configurable. <BR>
  143. * That is why kab uses a STL map to map its entry keys to user
  144. * (at least programmer...) defined descriptors. Usually, the descriptors are
  145. * created as a combination of the entry data, and then displayed in aphabetical
  146. * order in the selector combobox. This map is called the mirror map throughout
  147. * the documentation. It is created or updated every time the database changes.
  148. * Thus the way to find a special entry is: <OL>
  149. * <LI> the user selects an item in the selector combo box, returning its
  150. * index, </LI>
  151. * <LI> the index is used to find the key of the entry in the mirror map, </LI>
  152. * <LI> and finally the entry is retrieved by its key from the database. </LI>
  153. * </OL>
  154. * To modify the sorting order, the way to create the entry descriptors in the
  155. * mirror map nedds to be changed.
  156. *
  157. * \par The view
  158. * If you display an AddressBook object (that is a derived TQFrame),
  159. * it may show an entry
  160. * of the database that you might select. The entry you hand over to the method
  161. * ::displayEntry does not need to be contained in the currently loaded file.
  162. * This way you may integrate views of
  163. * the users addressbook database in your own application as a simple widget
  164. * type. To allow the user to
  165. * navigate through the database, you might want to show kab's own toolbar in
  166. * your mainwindow (or whereever). (The toolbar is not implemented by now). <BR>
  167. * Some parts of the AddressBook widget are \e interactive, that means they are
  168. * displayed as transparent KURLLabels that react when the user clicks on it.
  169. * These interactive parts have to be enabled by calling setInteractiveMode().
  170. */
  171. class AddressBook : public TQFrame
  172. {
  173. // ############################################################################
  174. Q_OBJECT
  175. // ----------------------------------------------------------------------------
  176. public:
  177. /**
  178. * The return values of some AddressBook member functions are #ErrorCode
  179. * values.
  180. */
  181. enum ErrorCode {
  182. NoError, /** No error, the operation did not fail. */
  183. PermDenied, /**< Access permissions for the operation are not available. */
  184. Locked, /**< An writing operation on a locked file was requested. */
  185. Rejected, /**< The requested operation has been rejected by the user. */
  186. NoSuchEntry, /**< An entry has been referenced using a unknown key. */
  187. NoEntry, /**< You tried to retrieve an entry but there is none. */
  188. NoFile, /**< No file has been loaded by now. */
  189. NoSuchFile, /**< A filename could not be found on the filesystem. */
  190. InternError, /**< A error in kab's internal logic occurred. */
  191. OutOfRange, /**< An index value was out of the allowed range. */
  192. NoSuchField, /**< You queried a field that does not exist. */
  193. NotImplemented /**< The requested operation is not implemented. */
  194. };
  195. /**
  196. * Some predefined telephone types. More are possible, but these are
  197. * provided and thus, for example, translated.
  198. */
  199. enum Telephone {
  200. NoTelephone,
  201. Fixed,
  202. Mobile,
  203. Fax,
  204. Modem,
  205. User1,
  206. User2,
  207. User3,
  208. NoOfTelephoneTypes
  209. };
  210. /** Each entry in a loaded database has its own ::Entry object.
  211. *
  212. * \par The structure of the address database
  213. * As you might have read, kab uses the QConfigDB class to manage its
  214. * data files. This class is intended to handle hierarchical structures.
  215. * Thus, kab is able to create human readable but still deep and complex
  216. * data files. This paragraph describes the overall structure of the
  217. * files, the next two deal with special parts of it. <BR>
  218. * First of all, kab II data files (that usually end with \c .kab, while in
  219. * kab 1 the fixed file name was \c addressbook.database) have two main
  220. * sections (see the documentation of the QConfigDB and Section classes),
  221. * one is called \c config, it contains different file specific
  222. * configuration settings like the last displayed entry, and one section
  223. * called \c entries that in turn contains a subsection for each entry in
  224. * the database file. The keys of this subsections are the literal strings
  225. * that are used in the KabKey class in the member KabKey::key. Each entry
  226. * subsection has some key-value-pairs described below and another
  227. * subsection "addresses" with one or more addresses in it. See the
  228. * following example for a kab II data file (without any key-value-pairs):
  229. * <BR> <PRE>
  230. * [config]
  231. * [END]
  232. * [entries]
  233. * [1] (the first entry with literal key "1")
  234. * [addresses]
  235. * [1] (the first address, addresses are enumerated)
  236. * [END]
  237. * [2] (the second address)
  238. * [END]
  239. * ... (more addresses may follow)
  240. * [END]
  241. * [END]
  242. * [2] (the second entry)
  243. * [addresses]
  244. * [1]
  245. * [END]
  246. * [END]
  247. * [END]
  248. * ... (more entries may follow)
  249. * [END] </PRE> <BR>
  250. *
  251. * \par The fields an entry contains
  252. * An entry contains all settings that are expected to be unique for all
  253. * addresses directly as key-value-pairs. Everything that is part of a
  254. * specific address of this person is part of an object of the member list
  255. * \c addresses referenced in the next paragraph. <BR>
  256. * The keys defined directly in the entry sections are: <DL>
  257. * <DT>title<DT><DD> The title of that person. </DD>
  258. * <DT>rank<DT><DD>A possible military rank of that person. </DD>
  259. * <DT>fn<DT><DD>The formatted name. If it is not empty, it replaces the
  260. * standard combination of the other name fields in the address
  261. * display. </DD>
  262. * <DT>nameprefix<DT><DD>A possible name prefix. </DD>
  263. * <DT>firstname<DT><DD>The first name. </DD>
  264. * <DT>middlename<DT><DD>The middle name. </DD>
  265. * <DT>lastname<DT><DD>The last name. </DD>
  266. * <DT>birthday<DT><DD>The birthday (a TQDate). </DD>
  267. * <DT>comment<DT><DD>A free form comment. </DD>
  268. * <DT>talk<DT><DD>The talk addresses (a string list). </DD>
  269. * <DT>emails<DT><DD>The email addresses (a string list). </DD>
  270. * <DT>keywords<DT><DD>A list of free-form keywords. </DD>
  271. * <DT>telephone<DT><DD>A list of telephone numbers in a special format. </DD>
  272. * <DT>URLs<DT><DD>A list of internet addresses. </DD>
  273. * <DT>user_1<DT><DD>The first user-declared data field. </DD>
  274. * <DT>user_2<DT><DD>The second user-declared data field. </DD>
  275. * <DT>user_3<DT><DD>The third user-declared data field. </DD>
  276. * <DT>user_4<DT><DD>The fourth user-declared data field. </DD>
  277. * </DL>
  278. * See the next section for a description of the addresses subsections.
  279. *
  280. * \par The fields of the addresses subsections
  281. * The section for each entry contains a subsection \c addresses with
  282. * in turn a subsection for each address. The addresses are enumerated
  283. * in the order they are inserted, their keys are the numbers of
  284. * inserting converted to a string. <BR>
  285. * The keys defined in an address subsection are: <DL>
  286. * <DT>headline</DT><DD> A headline shown for the address. </DD>
  287. * <DT>position</DT><DD> The position of the person. </DD>
  288. * <DT>org</DT><DD> The organization. </DD>
  289. * <DT>orgunit</DT><DD> The organizational unit. </DD>
  290. * <DT>orgsubunit</DT><DD> The organizational subunit. </DD>
  291. * <DT>role</DT><DD> The role of the person. </DD>
  292. * <DT>deliverylabel</DT><DD> A label for delivering to this address. </DD>
  293. * <DT>address</DT><DD> The street, house no., flat etc line. </DD>
  294. * <DT>zip</DT><DD> A zip or postal code. </DD>
  295. * <DT>town</DT><DD> The town the person lives in in this address. </DD>
  296. * <DT>country</DT><DD> The country for federal states. </DD>
  297. * <DT>state</DT><DD> The state for federal states. </DD>
  298. * </DL>
  299. *
  300. * \par The local configuration section
  301. * For each kab II database file there are some settings that apply
  302. * only to the file itselfes, not to all kab databases the user works
  303. * with. These settings are called the local configuration. The settings
  304. * are stored in the \c config section of the local file. The following
  305. * keys are declared in this section: <DL>
  306. * <DT>user_1</DT><DD>The \e name of the first user-declared field. </DD>
  307. * <DT>user_2</DT><DD>The \e name of the second user-declared field. </DD>
  308. * <DT>user_3</DT><DD>The \e name of the third user-declared field. </DD>
  309. * <DT>user_4</DT><DD>The \e name of the fourth user-declared field. </DD>
  310. * </DL>
  311. * More fields will surely follow.
  312. **/
  313. class Entry {
  314. public:
  315. // types:
  316. /** Since an entry may have different addresses, we need a type for them.
  317. * Multiple addresses are used to distinguish between addresses at home
  318. * and work, for example. */
  319. class Address {
  320. public:
  321. /** A constructor. */
  322. Address();
  323. // ----- This aggregates are used to access the fields by
  324. // keywords. We use char* here to be able to initialize the keys
  325. // in code as statics without initializing Qt etc. :
  326. /** An aggregat containing the keys of all declared fields:
  327. */
  328. static const char* Fields[];
  329. /** The number of elements in Fields.
  330. */
  331. static const int NoOfFields;
  332. /** Query the literal, translated name of the field given by its
  333. key.
  334. @return false if key is not defined */
  335. static bool nameOfField(const char* key, TQString& value);
  336. /** Get a field by its field name. Field names are defined in
  337. @see Fields. Since there are different file types a field
  338. may be represented with, a TQVariant is returned. */
  339. ErrorCode get(const char* key, TQVariant&);
  340. // ----- the following members represent the fields:
  341. /** The headline for this address. */
  342. TQString headline;
  343. /** The position of the person at this address. */
  344. TQString position;
  345. /** The organization of the person at this address. */
  346. TQString org;
  347. /** The org unit of the person at this address. */
  348. TQString orgUnit;
  349. /** The org subunit of the person at this address. */
  350. TQString orgSubUnit;
  351. /** The description for delivering. */
  352. TQString deliveryLabel;
  353. /** Street, with house number. */
  354. TQString address;
  355. /** Zip or postal code. */
  356. TQString zip;
  357. /** The town. */
  358. TQString town;
  359. /** The country for federal states. */
  360. TQString country;
  361. /** The state for federal states. */
  362. TQString state;
  363. protected:
  364. static KeyNameMap *fields;
  365. };
  366. /** Contains one or more Address objects. */
  367. std::list<AddressBook::Entry::Address> addresses;
  368. // ----- This aggregates are used to access the fields by
  369. // keywords. We use char* here to be able to initialize the keys
  370. // in code as statics without initializing Qt etc. :
  371. /** An aggregat containing the keys of all declared fields:
  372. */
  373. static const char* Fields[];
  374. /** The number of elements in Fields.
  375. */
  376. static const int NoOfFields;
  377. // methods:
  378. /** Use this method to retrieve the address at the given \a index.
  379. * The method is provided for convenience. The address data is
  380. * returned in \a address. */
  381. AddressBook::ErrorCode getAddress(int index, Address& address) const;
  382. /** Returns the number of addresses of this entry. */
  383. int noOfAddresses() const;
  384. /** Query the literal, translated name of the field given by its
  385. key.
  386. @return false if key is not defined */
  387. static bool nameOfField(const char* key, TQString& value);
  388. /** Get a field by its field name. Field names are defined in
  389. @see Fields. Since there are different file types a field
  390. may be represented with, a TQVariant is returned. */
  391. ErrorCode get(const char* key, TQVariant&);
  392. // members:
  393. // this parts are assumed to be unique for every entry:
  394. TQString title; /**< The title of the person. */
  395. TQString rank; /**< The rank of the person. */
  396. TQString fn; /**< The formatted name of the person. */
  397. TQString nameprefix; /**< A possibly name prefix for that person. */
  398. TQString firstname; /**< The first name of the person. */
  399. TQString middlename; /**< The middle name of the person. */
  400. TQString lastname; /**< The last name of the person. */
  401. TQDate birthday; /**< The birthday of this person. */
  402. TQString comment; /**< The comment. */
  403. TQStringList talk; /**< The talk addresses. */
  404. TQStringList emails; /**< The email addresses. */
  405. TQStringList keywords; /**< The user defined keywords for searching. */
  406. /**
  407. * Telephon numbers and types. This list contains combinations of telephone
  408. * numbers and the types of the phones, in this order. See enum
  409. * Telephone above.
  410. */
  411. TQStringList telephone;
  412. TQStringList URLs; /**< The home or related web pages of this person. */
  413. TQString user1; /**< The first user-declared field. */
  414. TQString user2; /**< The second user-declared field. */
  415. TQString user3; /**< The third user-declared field. */
  416. TQString user4; /**< The fourth user-declared field. */
  417. TQStringList custom;
  418. TQStringList categories; /**< The categories this entry is assigned to. */
  419. protected:
  420. static KeyNameMap *fields;
  421. };
  422. /**
  423. * The constructor. If \e load is true, the user standard file will
  424. * automatically be loaded into the object.
  425. */
  426. AddressBook(TQWidget* parent=0, const char* name=0, bool load=true);
  427. ~AddressBook(); /**< The destructor. */
  428. /**
  429. * Get the internal state of the object.
  430. * If no problem occurred, it returns ::NoError.
  431. * If the standard or the latest opened file could not be loaded,
  432. * it returns ::PermDenied
  433. */
  434. ErrorCode getState();
  435. /**
  436. * Load the file with the given path. An empty file name reloads the
  437. * currently opened file.
  438. */
  439. ErrorCode load(const TQString& filename=TQString::null);
  440. /**
  441. * Save the file to the given path and file name. An empty file name saves
  442. * to the file where the database has been read from.
  443. * If force is true, the method will switch to r/w mode for saving and
  444. * back.
  445. */
  446. ErrorCode save(const TQString& filename=TQString::null, bool force=false);
  447. /**
  448. * Close this file.
  449. * ::closeFile assures sure that the ::data object is reset no matter of the
  450. * state of the assigned file.
  451. * If \a save is true, it will not close the file if it could not be
  452. * saved.
  453. */
  454. ErrorCode closeFile(bool saveit=true);
  455. /**
  456. * Retrieve an entry from the database by its key.
  457. */
  458. ErrorCode getEntry(const KabKey& key, Entry&);
  459. /**
  460. * Retrieve the Section of the entry directly, returning a section object.
  461. */
  462. ErrorCode getEntry(const KabKey& key, Section*&);
  463. /**
  464. * Get all entries in displaying order. This method might be slow (O(n)).
  465. */
  466. ErrorCode getEntries(std::list<Entry>&);
  467. /**
  468. * Add an ::Entry, \a return the new key for further operations.
  469. * If update is false, the mirror map will not be affected, if it is true,
  470. * the mirror map gets updated, too.
  471. */
  472. ErrorCode add(const Entry&, KabKey& key, bool update=true);
  473. /**
  474. * Set the entry with the given key to the new contents. Be aware of
  475. * #PermDenied for read-only databases or file sharing conflicts. You cannot
  476. * change entries in a database for which you do not have write access.
  477. */
  478. ErrorCode change(const KabKey& key, const Entry&);
  479. /**
  480. * Remove the entry with the given key. Returns #NoSuchEntry if there is no
  481. * entry with this key, #PermDenied for read only databases.
  482. */
  483. ErrorCode remove(const KabKey& key);
  484. /**
  485. * Returns the number of entries in the loaded database.
  486. */
  487. unsigned int noOfEntries();
  488. /**
  489. * This method returns the literal name for the entry,
  490. * containing either the formatted name (if given) or a
  491. * combination of the first, additional and last name.
  492. * The name is returned in \a text.
  493. * If \a reverse is false, the text looks like
  494. * firstname (add. name) last name,
  495. * if it is true,
  496. + last name, first name (add. name).
  497. * If \a initials is true, the text contains initials only:
  498. * f. a. name [with reverse==false] or
  499. * name, f. a. [with reverse==true].
  500. * If there is no entry with this key, the method returns ::NoSuchEntry.
  501. */
  502. ErrorCode literalName(const KabKey& key, TQString& text,
  503. bool reverse=false, bool initials=false);
  504. /**
  505. * This is an overloaded method that differs only in the arguments it takes.
  506. */
  507. ErrorCode literalName(const Entry& entry, TQString& text,
  508. bool reverse=false, bool initials=false);
  509. /**
  510. * Get the key of the item in the selector with the given index.
  511. */
  512. ErrorCode getKey(int index, KabKey&);
  513. /**
  514. * Get the index of this key in the selector. This is the reverse
  515. * functionality to getKey().
  516. */
  517. ErrorCode getIndex(const KabKey&, int&);
  518. /**
  519. * Fill the string list with name lines. If your application shows a combobox
  520. * containing an overview over the currently loaded KabAPI database, then
  521. * call this method when receiving the signal ::changed and display the list
  522. * in the combo.
  523. */
  524. ErrorCode getListOfNames(TQStringList*, bool reverse=true, bool initials=true);
  525. /**
  526. * Hand over the configuration database. Careful!
  527. */
  528. QConfigDB* getConfig();
  529. /**
  530. * This method returns the QConfigDB section where the configuration of the
  531. * currently opened file is stored. It might be used to retrieve or to modify
  532. * these settings. The file-specific settings are saved along with
  533. * the open file.
  534. * Do not confuse the configuration section of the opened file with
  535. * the configuration of the program. Each file might have its own
  536. * local configuration for some settings where it makes sense.
  537. * @ return Null if no file has been opened.
  538. */
  539. Section *configurationSection();
  540. /**
  541. * This method opens a dialog for configuring the file-specific settings
  542. * for the loaded file. The database is automatically saved if the user
  543. * accepts the changes.
  544. */
  545. // ErrorCode configureFile();
  546. /**
  547. * Creates a new database with the given file name. If the filename is
  548. * empty, it creates the users standard data file. The method does not load
  549. * the new database.
  550. */
  551. ErrorCode createNew(const TQString& filename=TQString::null);
  552. /**
  553. * Creates the local configuration file. The filename is fixed to
  554. * \c kab.config, it will be created in the local kab directory
  555. * (\c $HOME/.trinity/share/apps/kab). Adapt the global configuration template
  556. * file (\c $TDEDIR/share/apps/kab/template.config) for unusual site-specific
  557. * settings.
  558. * The method does not load the new config file.
  559. */
  560. ErrorCode createConfigFile();
  561. ErrorCode loadConfigFile(); /**< Load the local configuration file. */
  562. // ErrorCode configureKab(); /**< Open the configuration dialog for the KabAPI. */
  563. // TQSize sizeHint(); /**< The preferred (minimal) size of the view. */ // ni
  564. /**
  565. * This method parses a vCard and creates an Entry object from it.
  566. */
  567. ErrorCode makeEntryFromVCard(const TQString& card, Entry&);
  568. /**
  569. * This method creates a vCard string from an entry.
  570. */
  571. ErrorCode makeVCardFromEntry(const Entry& entry, const TQString& card);
  572. /**
  573. * Returns the complete path to the user standard file. An empty path
  574. * indicates an error, but this should not happen. It is NOT ensured
  575. * that the file exists.
  576. */
  577. TQString getStandardFileName();
  578. /**
  579. * Call this to get a telephone type translated to the locale.
  580. */
  581. static TQString phoneType(AddressBook::Telephone);
  582. /**
  583. * Query the entry categories defined for this address
  584. * book. Categories may differ between addressbooks.
  585. */
  586. ErrorCode categories(CategoriesMap& categories);
  587. /**
  588. * Modify the categories for this addressbook. The map given will replace the
  589. * previoulsy stored one.
  590. */
  591. ErrorCode setCategories(const CategoriesMap& categories);
  592. /**
  593. * Query the real name of a category by its index.
  594. */
  595. ErrorCode category(int index, TQString&);
  596. /**
  597. * Query the category section. This is the "raw" storage of the defined
  598. * categories. It is always defined (or will be created if you have an old
  599. * file that does not have categories).
  600. * @see Section
  601. */
  602. Section* categoriesSection();
  603. // ----------------------------------------------------------------------------
  604. #ifdef KDE_NO_COMPAT
  605. private:
  606. #endif
  607. TQString getStandardFilename() { return getStandardFileName(); };
  608. protected:
  609. QConfigDB *config; /**< The configuration database. */
  610. QConfigDB *data; /**< The currently open data files. */
  611. StringKabKeyMap *entries; /**< The mirror map. */
  612. ErrorCode state; /**< The internal state of the object. */
  613. /**
  614. * Get the next available entry key for this file. For internal use only.
  615. */
  616. KabKey nextAvailEntryKey();
  617. /**
  618. * Returns true if both pathes point to the same file.
  619. * The method resolves relative file names to find this out.
  620. */
  621. bool isSameFile(const TQString& a, const TQString& b);
  622. /**
  623. * Parse the section and copy its contents into \a entry.
  624. * The method expects a subsection called \e addresses that contains a
  625. * number of subsections each containing data for one Entry::Address object.
  626. * All other fields are copied directly into the members of \a entry.
  627. */
  628. ErrorCode makeEntryFromSection(Section*, Entry&); // nicht beendet
  629. /**
  630. * For internal use only. This parses one address subsection and puts its
  631. * contents in the Address object.
  632. */
  633. ErrorCode makeAddressFromMap(KeyValueMap*, Entry::Address&);
  634. /**
  635. * Create a section from the entries settings.
  636. */
  637. ErrorCode makeSectionFromEntry(const Entry&, Section&); // nicht beendet
  638. /**
  639. * Update the mirror map after changes of the database.
  640. */
  641. ErrorCode updateMirrorMap();
  642. /**
  643. * Get the entry section of the file. Maybe a NULL pointer if no file is
  644. * opened.
  645. */
  646. Section* entrySection();
  647. /**
  648. * Lock the file for changing.
  649. * Since all database files are opened read-only, they must be locked before
  650. * the files contents are changed. After changing the file must be saved and
  651. * unlocked. Returns ::PermDenied if the file could not be locked, ::NoError
  652. * if it was not locked and is now, and ::Locked if the file is already
  653. * locked.
  654. * @see unlock
  655. * @see QConfigDB::setFileName
  656. */
  657. ErrorCode lock();
  658. /**
  659. * Unlock the file after changes. Returns ::NoError if the file was locked
  660. * and could be unlocked, ::PermDenied if the file was not locked and
  661. * possibly ::InternError if anything fails.
  662. * @see ::lock
  663. * @see QConfigDB::setFileName
  664. */
  665. ErrorCode unlock();
  666. /**
  667. * Set the background image. Kab will store a deep copy of the image.
  668. * If the image is a null image nothing will be displayed.
  669. */
  670. // void setBackground(const TQImage&);
  671. /**
  672. * Enable or disable the background image.
  673. */
  674. // void setBackgroundEnabled(bool state);
  675. /**
  676. * Retrieve wether the background image is enabled or not.
  677. */
  678. // bool getBackgroundEnabled();
  679. /**
  680. * Set if the URL labels are interactive.
  681. */
  682. // void setInteractiveMode(bool state);
  683. /**
  684. * Get if the URL labels are interactive.
  685. */
  686. // bool getInteractiveMode();
  687. protected slots:
  688. /**
  689. * Called when ::data has been cleared or reloaded.
  690. */
  691. void reloaded(QConfigDB*);
  692. /**
  693. * Called when the \e file assigned to ::data has changed on disk.
  694. */
  695. void dataFileChanged();
  696. /**
  697. * Called when the \e file assigned to ::config has changed on disk.
  698. */
  699. void configFileChanged();
  700. // ----------------------------------------------------------------------------
  701. public slots:
  702. /**
  703. * This slot is called when an external object changed the database through
  704. * the kabapi.
  705. */
  706. void externalChange();
  707. // ----------------------------------------------------------------------------
  708. signals:
  709. void changed(); /**< The entries have changed, update the selector. */
  710. void setStatus(const TQString&); /**< This is kab radio with the news... */
  711. void newFile(const TQString&); /**< Notifies changes of the file name. */
  712. // ############################################################################
  713. private:
  714. class AddressBookPrivate;
  715. AddressBookPrivate *d;
  716. };
  717. #endif // ADDRESSBOOK_H