1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
/* -*- 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 QPushButton;
class QFrame;
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 QWidget pointer to the parent widget.
* @param name The widgets name (used for debugging)
*/
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 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 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&);
void slotDoubleClicked ( QListBoxItem * );
signals:
/**
* Send status messages.
*/
void setStatus(const QString&);
// ############################################################################
private:
class KAbAPIPrivate;
KAbAPIPrivate *d;
};
#endif // KABAPI_H
|
