KContacts

field.h
1 /*
2  This file is part of the KContacts framework.
3  SPDX-FileCopyrightText: 2002 Cornelius Schumacher <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KCONTACTS_FIELD_H
9 #define KCONTACTS_FIELD_H
10 
11 #include "addressee.h"
12 #include <QString>
13 
14 class KConfigGroup;
15 
16 namespace KContacts
17 {
18 /**
19  * @short Represents a field in the Addressbook
20  *
21  * This class represents a field in the Addressbook database.
22  * It provides methods for accessing meta-information about
23  * the field (such as label() or category()) as well as
24  * getting or setting the field's value in an instance of
25  * Addressee (value(), setValue()).
26  *
27  * Furthermore, some static methods are provided for getting
28  * a list of all fields (allFields(), defaultFields()), for
29  * creating new fields (createCustomField()) and for saving
30  * or loading fields to/from a config file (saveFields(),
31  * restoreFields()).
32  */
33 class KCONTACTS_EXPORT Field
34 {
35 public:
36  /**
37  * This type is used for a list of fields.
38  */
40 
41  /**
42  * Represents the category a field belongs to.
43  */
45  /**
46  * All fields
47  */
48  All = 0x0,
49  /**
50  * Frequently used fields
51  */
52  Frequent = 0x01,
53  /**
54  * Fields which belong to the address, such as Street, City, Zip, etc.
55  */
56  Address = 0x02,
57  /**
58  * Fields which store information about the e-mail contact, such as
59  * e-mail address or mail client
60  */
61  Email = 0x04,
62  /**
63  * Personal fields, such as Birthday, Home Address fields, IM Address, etc.
64  */
65  Personal = 0x08,
66  /**
67  * Fields about the organization, such as Business Address fields, Department,
68  * Profession, etc.
69  */
70  Organization = 0x10,
71  /**
72  * Custom (user-defined) fields
73  */
74  CustomCategory = 0x20,
75  };
76 
77  /**
78  * Returns the translated label for this field.
79  */
80  Q_REQUIRED_RESULT virtual QString label();
81 
82  /**
83  * Returns the ored categories the field belongs to.
84  */
85  Q_REQUIRED_RESULT virtual int category();
86 
87  /**
88  * Returns the translated label for @p category.
89  *
90  * @param category the category of type FieldCategory
91  * @return the translated label
92  */
93  static QString categoryLabel(int category);
94 
95  /**
96  * Returns a string representation of the value the field has in the given
97  * Addressee.
98  *
99  * @return the string representation of the value or QString(), if it
100  * is not possible to convert the value to a string.
101  */
102  Q_REQUIRED_RESULT virtual QString value(const KContacts::Addressee &addressee);
103 
104  /**
105  * Sets the value of the field in the given Addressee.
106  *
107  * @return @c true on success or @c false, if the given string couldn't
108  * be converted to a valid value.
109  */
110  Q_REQUIRED_RESULT virtual bool setValue(KContacts::Addressee &addressee, const QString &value);
111 
112  /**
113  * Returns a string, that can be used for sorting.
114  */
115  Q_REQUIRED_RESULT QString sortKey(const KContacts::Addressee &addressee);
116 
117  /**
118  * Returns, if the field is a user-defined field.
119  *
120  * @return @c true if this is a custom field, @c false otherwise
121  */
122  Q_REQUIRED_RESULT virtual bool isCustom();
123 
124  /**
125  * Returns, if the field is equal with @p field.
126  *
127  * @param field the field to compare this field to
128  * @return @c true if the fields are equal, @c false otherwise
129  */
130  Q_REQUIRED_RESULT virtual bool equals(Field *field);
131 
132  /**
133  * Returns a list of all fields.
134  */
135  static Field::List allFields();
136 
137  /**
138  * Returns a list of the default fields.
139  */
140  Q_REQUIRED_RESULT static Field::List defaultFields();
141 
142  /**
143  * Creates a custom field.
144  *
145  * @param label The label for this field
146  * @param category The category of this field
147  * @param key Unique key for this field
148  * @param app Unique app name for this field
149  */
150  static Field *createCustomField(const QString &label, int category, const QString &key, const QString &app);
151 
152  /**
153  * Delete all fields from list.
154  */
155  static void deleteFields();
156 
157  /**
158  * Save the field settings to a config file.
159  *
160  * @param cfg The config file object
161  * @param identifier The unique identifier
162  * @param fields The list of the fields
163  */
164  static void saveFields(KConfigGroup &cfg, const QString &identifier, const Field::List &fields);
165  /**
166  * @overload
167  *
168  * Here, the list is stored in KSharedConfig::openConfig() in group "KABCFields".
169  *
170  * @param identifier The unique identifier
171  * @param fields The list of the fields
172  */
173  static void saveFields(const QString &identifier, const Field::List &fields);
174 
175  /**
176  * Load the field settings from a config file.
177  *
178  * @param cfg The config file object
179  * @param identifier The unique identifier
180  */
181  static Field::List restoreFields(const KConfigGroup &cfg, const QString &identifier);
182 
183  /**
184  * @overload
185  *
186  * Here, the list is loaded from KSharedConfig::openConfig() from group "KABCFields".
187  *
188  * @param identifier The unique identifier
189  */
190  static Field::List restoreFields(const QString &identifier);
191 
192 protected:
193  /**
194  * @internal
195  *
196  * Creates a field and appends it to the general list of fields.
197  *
198  * @param id The identifier for the field
199  * @param category The optional category for the field
200  */
201  static void createField(int id, int category = 0);
202 
203  /**
204  * @internal
205  *
206  * Creates a field and appends it to the list of default fields.
207  *
208  * @param id The identifier for the field
209  * @param category The optional category for the field
210  */
211  static void createDefaultField(int id, int category = 0);
212 
213 private:
214  class Private;
215 
216  Field(Private *p);
217  virtual ~Field();
218 
219  Private *const d;
220 };
221 }
222 #endif
Class that holds a Email for a contact.
Definition: email.h:23
Organization
Postal address information.
Definition: address.h:28
QList< Field * > List
This type is used for a list of fields.
Definition: field.h:39
address book entry
Definition: addressee.h:69
Represents a field in the Addressbook.
Definition: field.h:33
FieldCategory
Represents the category a field belongs to.
Definition: field.h:44
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Wed Jun 23 2021 22:55:18 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.