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

KDE's Doxygen guidelines are available online.