-rw-r--r-- | kabc/addresseelist.h | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/kabc/addresseelist.h b/kabc/addresseelist.h new file mode 100644 index 0000000..2df252c --- a/dev/null +++ b/kabc/addresseelist.h | |||
@@ -0,0 +1,218 @@ | |||
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., 59 Temple Place - Suite 330, | ||
19 | Boston, MA 02111-1307, USA. | ||
20 | */ | ||
21 | |||
22 | /* | ||
23 | Enhanced Version of the file for platform independent KDE tools. | ||
24 | Copyright (c) 2004 Ulf Schenk | ||
25 | |||
26 | $Id$ | ||
27 | */ | ||
28 | |||
29 | #ifndef KABC_ADDRESSEELIST_H | ||
30 | #define KABC_ADDRESSEELIST_H | ||
31 | |||
32 | #include <qvaluelist.h> | ||
33 | |||
34 | #include "addressee.h" | ||
35 | |||
36 | namespace KABC { | ||
37 | |||
38 | class Field; | ||
39 | |||
40 | /** | ||
41 | * Each trait must implement one static function for equality, one for "less | ||
42 | * than". Class name should be the field name. A trait does not necessarily | ||
43 | * have to stick to just one field: a trait sorting by family name can e.g. | ||
44 | * sort addressees with equal family name by given name. | ||
45 | * | ||
46 | * If you want to implement reverse sorting, you do not have to write another | ||
47 | * trait, as AddresseeList takes care of that. | ||
48 | */ | ||
49 | namespace SortingTraits | ||
50 | { | ||
51 | |||
52 | class Uid | ||
53 | { | ||
54 | public: | ||
55 | static bool eq( const Addressee &, const Addressee & ); | ||
56 | static bool lt( const Addressee &, const Addressee & ); | ||
57 | }; | ||
58 | |||
59 | class Name | ||
60 | { | ||
61 | public: | ||
62 | static bool eq( const Addressee &, const Addressee & ); | ||
63 | static bool lt( const Addressee &, const Addressee & ); | ||
64 | }; | ||
65 | |||
66 | class FormattedName | ||
67 | { | ||
68 | public: | ||
69 | static bool eq( const Addressee &, const Addressee & ); | ||
70 | static bool lt( const Addressee &, const Addressee & ); | ||
71 | }; | ||
72 | |||
73 | class FamilyName // fallback to given name | ||
74 | { | ||
75 | public: | ||
76 | static bool eq( const Addressee &, const Addressee & ); | ||
77 | static bool lt( const Addressee &, const Addressee & ); | ||
78 | }; | ||
79 | |||
80 | class GivenName // fallback to family name | ||
81 | { | ||
82 | public: | ||
83 | static bool eq( const Addressee &, const Addressee & ); | ||
84 | static bool lt( const Addressee &, const Addressee & ); | ||
85 | }; | ||
86 | |||
87 | } | ||
88 | |||
89 | /** | ||
90 | * Addressee attribute used for sorting. | ||
91 | */ | ||
92 | typedef enum { Uid, Name, FormattedName, FamilyName, GivenName } SortingCriterion; | ||
93 | |||
94 | /** | ||
95 | * @short a QValueList of Addressee, with sorting functionality | ||
96 | * | ||
97 | * This class extends the functionality of QValueList with | ||
98 | * sorting methods specific to the Addressee class. It can be used | ||
99 | * just like any other QValueList but is no template class. | ||
100 | * | ||
101 | * An AddresseeList does not automatically keep sorted when addressees | ||
102 | * are added or removed or the sorting order is changed, as this would | ||
103 | * slow down larger operations by sorting after every step. So after | ||
104 | * such operations you have to call {@link #sort} or {@link #sortBy} to | ||
105 | * create a defined order again. | ||
106 | * | ||
107 | * Iterator usage is inherited by QValueList and extensively documented | ||
108 | * there. Please remember that the state of an iterator is undefined | ||
109 | * after any sorting operation. | ||
110 | * | ||
111 | * For the enumeration Type SortingCriterion, which specifies the | ||
112 | * field by the collection will be sorted, the following values exist: | ||
113 | * Uid, Name, FormattedName, FamilyName, GivenName. | ||
114 | * | ||
115 | * @author Jost Schenck jost@schenck.de | ||
116 | */ | ||
117 | class AddresseeList : public QValueList<Addressee> | ||
118 | { | ||
119 | public: | ||
120 | AddresseeList(); | ||
121 | ~AddresseeList(); | ||
122 | AddresseeList( const AddresseeList & ); | ||
123 | AddresseeList( const QValueList<Addressee> & ); | ||
124 | |||
125 | /** | ||
126 | * Debug output. | ||
127 | */ | ||
128 | void dump() const; | ||
129 | |||
130 | /** | ||
131 | * Determines the direction of sorting. On change, the list | ||
132 | * will <em>not</em> automatically be resorted. | ||
133 | * @param r <tt>true</tt> if sorting should be done reverse, <tt>false</tt> otherwise | ||
134 | */ | ||
135 | void setReverseSorting( bool r = true ) { mReverseSorting = r; } | ||
136 | |||
137 | /** | ||
138 | * Returns the direction of sorting. | ||
139 | * @return <tt>true</tt> if sorting is done reverse, <tt>false</tt> otherwise | ||
140 | */ | ||
141 | bool reverseSorting() const { return mReverseSorting; } | ||
142 | |||
143 | /** | ||
144 | * Sorts this list by a specific criterion. | ||
145 | * @param c the criterion by which should be sorted | ||
146 | */ | ||
147 | void sortBy( SortingCriterion c ); | ||
148 | |||
149 | /** | ||
150 | * Sorts this list by a specific field. If no parameter is given, the | ||
151 | * last used Field object will be used. | ||
152 | * @param field pointer to the Field object to be sorted by | ||
153 | */ | ||
154 | void sortByField( Field *field = 0 ); | ||
155 | |||
156 | /** | ||
157 | * Sorts this list by its active sorting criterion. This normally is the | ||
158 | * criterion of the last sortBy operation or <tt>FormattedName</tt> if up | ||
159 | * to now there has been no sortBy operation. | ||
160 | * | ||
161 | * Please note that the sorting trait of the last {@link #sortByTrait} | ||
162 | * method call is not remembered and thus the action can not be repeated | ||
163 | * by this method. | ||
164 | */ | ||
165 | void sort(); | ||
166 | |||
167 | /** | ||
168 | * Templated sort function. You normally will not want to use this but | ||
169 | * {@link #sortBy} and {@link #sort} instead as the existing sorting | ||
170 | * criteria completely suffice for most cases. | ||
171 | * | ||
172 | * However, if you do want to use some special sorting criterion, you can | ||
173 | * write a trait class that will be provided to this templated method. | ||
174 | * This trait class has to have a class declaration like the following: | ||
175 | * <pre> | ||
176 | * class MySortingTrait { | ||
177 | * public: | ||
178 | * // eq returns true if a1 and a2 are equal | ||
179 | * static bool eq(KABC::Addressee a1, KABC::Addressee a2); | ||
180 | * // lt returns true is a1 is "less than" a2 | ||
181 | * static bool lt(KABC::Addressee a1, KABC::Addressee a2); | ||
182 | * }; | ||
183 | * </pre> | ||
184 | * You can then pass this class to the sortByTrait method like this: | ||
185 | * <pre> | ||
186 | * myAddresseelist.sortByTrait<MySortingTrait>(); | ||
187 | * </pre> | ||
188 | * Please note that the {@link #sort} method can not be used to repeat the | ||
189 | * sorting of the last <tt>sortByTrait</tt> action. | ||
190 | * | ||
191 | * Right now this method uses the bubble sort algorithm. This should be | ||
192 | * replaced for a better one when I have time. | ||
193 | */ | ||
194 | template<class Trait> void sortByTrait(); | ||
195 | |||
196 | /** | ||
197 | * Returns the active sorting criterion, ie the sorting criterion that | ||
198 | * will be used by a {@link #sort} call. | ||
199 | */ | ||
200 | SortingCriterion sortingCriterion() const { return mActiveSortingCriterion; } | ||
201 | |||
202 | /** | ||
203 | * Returns the active sorting field, ie a pointer to the Field object | ||
204 | * which was used for the last {@link #sortByField} operation. | ||
205 | */ | ||
206 | Field* sortingField() const { return mActiveSortingField; } | ||
207 | |||
208 | private: | ||
209 | void quickSortByField( int, int ); | ||
210 | |||
211 | bool mReverseSorting; | ||
212 | SortingCriterion mActiveSortingCriterion; | ||
213 | Field* mActiveSortingField; | ||
214 | }; | ||
215 | |||
216 | } | ||
217 | |||
218 | #endif | ||