1/*
2 This file is part of libkabc.
3 Copyright (c) 2002 Jost Schenck <jost@schenck.de>
4 2003 Tobias Koenig <tokoe@kde.org>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef KABC_ADDRESSEELIST_H
23#define KABC_ADDRESSEELIST_H
24
25#include "kabc_export.h"
26#include <QtCore/QSharedDataPointer>
27#include <QtCore/QList>
28
29namespace KABC {
30
31class Field;
32class SortMode;
33class Addressee;
34
35/**
36 * Each trait must implement one static function for equality, one for "less
37 * than". Class name should be the field name. A trait does not necessarily
38 * have to stick to just one field: a trait sorting by family name can e.g.
39 * sort addressees with equal family name by given name.
40 *
41 * If you want to implement reverse sorting, you do not have to write another
42 * trait, as AddresseeList takes care of that.
43 */
44namespace SortingTraits {
45
46class KABC_EXPORT Uid
47{
48 public:
49 /**
50 * Creates an instance.
51 */
52 Uid();
53
54 /**
55 * Destroys the instance.
56 */
57 ~Uid();
58
59 /**
60 * "Equal" compare method
61 *
62 * @return @c true if the first parameter is equal to the second
63 * when comparing the uid attribute.
64 *
65 * @see Addressee::uid()
66 * @see QString::compare()
67 */
68 static bool eq( const Addressee &, const Addressee & );
69
70 /**
71 * "Less-Than" compare method
72 *
73 * @return @c true if the first parameter is "less-than" the second
74 * when comparing the uid attribute.
75 *
76 * @see Addressee::uid()
77 * @see QString::compare()
78 */
79 static bool lt( const Addressee &, const Addressee & );
80
81 private:
82 class Private;
83 Private *const d;
84};
85
86class KABC_EXPORT Name
87{
88 public:
89 /**
90 * Creates an instance.
91 */
92 Name();
93
94 /**
95 * Destroys the instance.
96 */
97 ~Name();
98
99 /**
100 * "Equal" compare method
101 *
102 * @return @c true if the first parameter is equal to the second
103 * when comparing the name attribute.
104 *
105 * @see Addressee::name()
106 * @see QString::localeAwareCompare()
107 */
108 static bool eq( const Addressee &, const Addressee & );
109
110 /**
111 * "Less-Than" compare method
112 *
113 * @return @c true if the first parameter is "less-than" the second
114 * when comparing the name attribute.
115 *
116 * @see Addressee::name()
117 * @see QString::localeAwareCompare()
118 */
119 static bool lt( const Addressee &, const Addressee & );
120
121 private:
122 class Private;
123 Private *const d;
124};
125
126class KABC_EXPORT FormattedName
127{
128 public:
129 /**
130 * Creates an instance.
131 */
132 FormattedName();
133
134 /**
135 * Destroys the instance.
136 */
137 ~FormattedName();
138
139 /**
140 * "Equal" compare method
141 *
142 * @return @c true if the first parameter is equal to the second
143 * when comparing the formatted name attribute.
144 *
145 * @see Addressee::formattedName()
146 * @see QString::localeAwareCompare()
147 */
148 static bool eq( const Addressee &, const Addressee & );
149
150 /**
151 * "Less-Than" compare method
152 *
153 * @return @c true if the first parameter is "less-than" the second
154 * when comparing the formatted name attribute.
155 *
156 * @see Addressee::formattedName()
157 * @see QString::localeAwareCompare()
158 */
159 static bool lt( const Addressee &, const Addressee & );
160
161 private:
162 class Private;
163 Private *const d;
164};
165
166class KABC_EXPORT FamilyName // fallback to given name
167{
168 public:
169 /**
170 * Creates an instance.
171 */
172 FamilyName();
173
174 /**
175 * Destroys the instance.
176 */
177 ~FamilyName();
178
179 /**
180 * "Equal" compare method
181 *
182 * @return @c true if the first parameter is equal to the second
183 * when comparing the family name and given name attributes.
184 *
185 * @see Addressee::familyName()
186 * @see Addressee::givenName()
187 * @see QString::localeAwareCompare()
188 */
189 static bool eq( const Addressee &, const Addressee & );
190
191 /**
192 * "Less-Than" compare method
193 *
194 * Falls back to comparing given name if equal
195 *
196 * @return @c true if the first parameter is "less-than" the second
197 * when comparing the family name attribute.
198 *
199 * @see Addressee::familyName()
200 * @see QString::localeAwareCompare()
201 */
202 static bool lt( const Addressee &, const Addressee & );
203
204 private:
205 class Private;
206 Private *const d;
207};
208
209class KABC_EXPORT GivenName // fallback to family name
210{
211 public:
212 /**
213 * Creates an instance.
214 */
215 GivenName();
216
217 /**
218 * Destroys the instance.
219 */
220 ~GivenName();
221
222 /**
223 * "Equal" compare method
224 *
225 * @return @c true if the first parameter is equal to the second
226 * when comparing the given name and family name attributes.
227 *
228 * @see Addressee::givenName()
229 * @see Addressee::familyName()
230 * @see QString::localeAwareCompare()
231 */
232 static bool eq( const Addressee &, const Addressee & );
233
234 /**
235 * "Less-Than" compare method
236 *
237 * Falls back to comparing family name if equal
238 *
239 * @return @c true if the first parameter is "less-than" the second
240 * when comparing the given name attribute.
241 *
242 * @see Addressee::givenName()
243 * @see QString::localeAwareCompare()
244 */
245 static bool lt( const Addressee &, const Addressee & );
246
247 private:
248 class Private;
249 Private *const d;
250};
251
252}
253
254/**
255 * Addressee attribute used for sorting.
256 */
257typedef enum {
258 Uid,
259 Name,
260 FormattedName,
261 FamilyName,
262 GivenName
263} SortingCriterion;
264
265/**
266 * @short a QValueList of Addressee, with sorting functionality
267 *
268 * This class extends the functionality of QValueList with
269 * sorting methods specific to the Addressee class. It can be used
270 * just like any other QValueList but is no template class.
271 *
272 * An AddresseeList does not automatically keep sorted when addressees
273 * are added or removed or the sorting order is changed, as this would
274 * slow down larger operations by sorting after every step. So after
275 * such operations you have to call {@link #sort} or {@link #sortBy} to
276 * create a defined order again.
277 *
278 * Iterator usage is inherited from QList and extensively documented
279 * there. Please remember that the state of an iterator is undefined
280 * after any sorting operation.
281 *
282 * For the enumeration Type SortingCriterion, which specifies the
283 * field by the collection will be sorted, the following values exist:
284 * Uid, Name, FormattedName, FamilyName, GivenName.
285 *
286 * @author Jost Schenck jost@schenck.de
287 */
288class KABC_EXPORT AddresseeList : public QList<Addressee>
289{
290 public:
291 /**
292 * Creates a new addressee list.
293 */
294 AddresseeList();
295
296 /**
297 * Creates a new addressee list.
298 */
299 AddresseeList( const AddresseeList & );
300
301 /**
302 * Creates a new addressee list.
303 */
304 AddresseeList( const QList<Addressee> & );
305
306 /**
307 * Destroys the addressee list.
308 */
309 ~AddresseeList();
310
311 /**
312 * Assignment operator.
313 *
314 * @param other the list to assign from
315 * @return a reference to @c this
316 */
317 AddresseeList &operator=( const AddresseeList &other );
318
319 /**
320 * Determines the direction of sorting. On change, the list
321 * will <em>not</em> automatically be resorted.
322 * @param reverseSorting <tt>true</tt> if sorting should be done reverse,
323 * <tt>false</tt> otherwise
324 */
325 void setReverseSorting( bool reverseSorting = true );
326
327 /**
328 * Returns the direction of sorting.
329 * @return <tt>true</tt> if sorting is done reverse, <tt>false</tt> otherwise
330 */
331 bool reverseSorting() const;
332
333 /**
334 * Sorts this list by a specific criterion.
335 * @param c the criterion by which should be sorted
336 */
337 void sortBy( SortingCriterion c );
338
339 /**
340 * Sorts this list by a specific field. If no parameter is given, the
341 * last used Field object will be used.
342 * @param field pointer to the Field object to be sorted by
343 */
344 void sortByField( Field *field = 0 );
345
346 /**
347 * Sorts this list by a specific sorting mode.
348 * @param mode pointer to the sorting mode object to be sorted by
349 */
350 void sortByMode( SortMode *mode = 0 );
351
352 /**
353 * Sorts this list by its active sorting criterion. This normally is the
354 * criterion of the last sortBy operation or <tt>FormattedName</tt> if up
355 * to now there has been no sortBy operation.
356 *
357 * Please note that the sorting trait of the last {@link #sortByTrait}
358 * method call is not remembered and thus the action can not be repeated
359 * by this method.
360 */
361 void sort();
362
363 /**
364 * Templated sort function. You normally will not want to use this but
365 * {@link #sortBy} and {@link #sort} instead as the existing sorting
366 * criteria completely suffice for most cases.
367 *
368 * However, if you do want to use some special sorting criterion, you can
369 * write a trait class that will be provided to this templated method.
370 * This trait class has to have a class declaration like the following:
371 * \code
372 * class MySortingTrait {
373 * public:
374 * // eq returns true if a1 and a2 are equal
375 * static bool eq(KABC::Addressee a1, KABC::Addressee a2);
376 * // lt returns true is a1 is "less than" a2
377 * static bool lt(KABC::Addressee a1, KABC::Addressee a2);
378 * };
379 * \endcode
380 * You can then pass this class to the sortByTrait method like this:
381 * \code
382 * myAddresseelist.sortByTrait&lt;MySortingTrait&gt;();
383 * \endcode
384 * Please note that the {@link #sort} method can not be used to repeat the
385 * sorting of the last <tt>sortByTrait</tt> action.
386 *
387 * Right now this method uses the bubble sort algorithm. This should be
388 * replaced for a better one when I have time.
389 */
390 template<class Trait> void sortByTrait();
391
392 /**
393 * Returns the active sorting criterion, ie the sorting criterion that
394 * will be used by a {@link #sort} call.
395 */
396 SortingCriterion sortingCriterion() const;
397
398 /**
399 * Returns the active sorting field, ie a pointer to the Field object
400 * which was used for the last {@link #sortByField} operation.
401 * This function returns the last GLOBAL sorting field, not
402 * the class specific one.
403 * You're a lot better off by keeping track of this locally.
404 */
405 Field *sortingField() const;
406
407 /**
408 * Returns a string representation of the addressee list.
409 */
410 QString toString() const;
411
412 private:
413 class Private;
414 QSharedDataPointer<Private> d;
415};
416
417}
418
419#endif
420