1/*
2 This file is part of libkabc.
3 Copyright (c) 2002 Cornelius Schumacher <schumacher@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KABC_FIELD_H
22#define KABC_FIELD_H
23
24#include "addressee.h"
25#include <QtCore/QString>
26
27class KConfigGroup;
28
29namespace KABC {
30
31/**
32 * @short Represents a field in the Addressbook
33 *
34 * This class represents a field in the Addressbook database.
35 * It provides methods for accessing meta-information about
36 * the field (such as label() or category()) as well as
37 * getting or setting the field's value in an instance of
38 * Addressee (value(), setValue()).
39 *
40 * Furthermore, some static methods are provided for getting
41 * a list of all fields (allFields(), defaultFields()), for
42 * creating new fields (createCustomField()) and for saving
43 * or loading fields to/from a config file (saveFields(),
44 * restoreFields()).
45 */
46class KABC_EXPORT Field
47{
48 public:
49 /**
50 * This type is used for a list of fields.
51 */
52 typedef QList<Field *> List;
53
54 /**
55 * Represents the category a field belongs to.
56 */
57 enum FieldCategory {
58 /**
59 * All fields
60 */
61 All = 0x0,
62 /**
63 * Frequently used fields
64 */
65 Frequent = 0x01,
66 /**
67 * Fields which belong to the address, such as Street, City, Zip, etc.
68 */
69 Address = 0x02,
70 /**
71 * Fields which store information about the e-mail contact, such as
72 * e-mail address or mail client
73 */
74 Email = 0x04,
75 /**
76 * Personal fields, such as Birthday, Home Address fields, IM Address, etc.
77 */
78 Personal = 0x08,
79 /**
80 * Fields about the organization, such as Business Address fields, Department,
81 * Profession, etc.
82 */
83 Organization = 0x10,
84 /**
85 * Custom (user-defined) fields
86 */
87 CustomCategory = 0x20
88 };
89
90 /**
91 * Returns the translated label for this field.
92 */
93 virtual QString label();
94
95 /**
96 * Returns the ored categories the field belongs to.
97 */
98 virtual int category();
99
100 /**
101 * Returns the translated label for @p category.
102 *
103 * @param category the category of type FieldCategory
104 * @return the translated label
105 */
106 static QString categoryLabel( int category );
107
108 /**
109 * Returns a string representation of the value the field has in the given
110 * Addressee.
111 *
112 * @return the string representation of the value or QString(), if it
113 * is not possible to convert the value to a string.
114 */
115 virtual QString value( const KABC::Addressee & );
116
117 /**
118 * Sets the value of the field in the given Addressee.
119 *
120 * @return @c true on success or @c false, if the given string couldn't
121 * be converted to a valid value.
122 */
123 virtual bool setValue( KABC::Addressee &, const QString & );
124
125 /**
126 * Returns a string, that can be used for sorting.
127 */
128 QString sortKey( const KABC::Addressee & );
129
130 /**
131 * Returns, if the field is a user-defined field.
132 *
133 * @return @c true if this is a custom field, @c false otherwise
134 */
135 virtual bool isCustom();
136
137 /**
138 * Returns, if the field is equal with @p field.
139 *
140 * @param field the field to compare this field to
141 * @return @c true if the fields are equal, @c false otherwise
142 */
143 virtual bool equals( Field *field );
144
145 /**
146 * Returns a list of all fields.
147 */
148 static Field::List allFields();
149
150 /**
151 * Returns a list of the default fields.
152 */
153 static Field::List defaultFields();
154
155 /**
156 * Creates a custom field.
157 *
158 * @param label The label for this field
159 * @param category The category of this field
160 * @param key Unique key for this field
161 * @param app Unique app name for this field
162 */
163 static Field *createCustomField( const QString &label, int category,
164 const QString &key, const QString &app );
165
166 /**
167 * Delete all fields from list.
168 */
169 static void deleteFields();
170
171 /**
172 * Save the field settings to a config file.
173 *
174 * @param cfg The config file object
175 * @param identifier The unique identifier
176 * @param fields The list of the fields
177 */
178 static void saveFields( KConfigGroup &cfg, const QString &identifier,
179 const Field::List &fields );
180 /**
181 * @overload
182 *
183 * Here, the list is stored in KGlobal::config() in group "KABCFields".
184 *
185 * @param identifier The unique identifier
186 * @param fields The list of the fields
187 */
188 static void saveFields( const QString &identifier,
189 const Field::List &fields );
190
191 /**
192 * Load the field settings from a config file.
193 *
194 * @param cfg The config file object
195 * @param identifier The unique identifier
196 */
197 static Field::List restoreFields( const KConfigGroup &cfg, const QString &identifier );
198
199 /**
200 * @overload
201 *
202 * Here, the list is loaded from KGlobal::config() from group "KABCFields".
203 *
204 * @param identifier The unique identifier
205 */
206 static Field::List restoreFields( const QString &identifier );
207
208 protected:
209 /**
210 * @internal
211 *
212 * Creates a field and appends it to the general list of fields.
213 *
214 * @param id The identifier for the field
215 * @param category The optional category for the field
216 */
217 static void createField( int id, int category = 0 );
218
219 /**
220 * @internal
221 *
222 * Creates a field and appends it to the list of default fields.
223 *
224 * @param id The identifier for the field
225 * @param category The optional category for the field
226 */
227 static void createDefaultField( int id, int category = 0 );
228
229 private:
230 class Private;
231
232 Field( Private * );
233 virtual ~Field();
234
235 Private *const d;
236};
237
238}
239#endif
240