File indexing completed on 2025-02-16 09:56:45
0001 /* 0002 This file is part of the KContacts framework. 0003 SPDX-FileCopyrightText: 2002 Cornelius Schumacher <schumacher@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KCONTACTS_FIELD_H 0009 #define KCONTACTS_FIELD_H 0010 0011 #include "kcontacts_export.h" 0012 0013 #if KCONTACTS_ENABLE_DEPRECATED_SINCE(5, 88) 0014 #include "addressee.h" 0015 #include <QString> 0016 0017 class KConfigGroup; 0018 0019 namespace KContacts 0020 { 0021 /** 0022 * @short Represents a field in the Addressbook 0023 * 0024 * This class represents a field in the Addressbook database. 0025 * It provides methods for accessing meta-information about 0026 * the field (such as label() or category()) as well as 0027 * getting or setting the field's value in an instance of 0028 * Addressee (value(), setValue()). 0029 * 0030 * Furthermore, some static methods are provided for getting 0031 * a list of all fields (allFields(), defaultFields()), for 0032 * creating new fields (createCustomField()) and for saving 0033 * or loading fields to/from a config file (saveFields(), 0034 * restoreFields()). 0035 * 0036 * @deprecated since 5.88, class is unused 0037 */ 0038 class KCONTACTS_EXPORT KCONTACTS_DEPRECATED_VERSION(5, 88, "class is unused") Field 0039 { 0040 public: 0041 /** 0042 * This type is used for a list of fields. 0043 */ 0044 typedef QList<Field *> List; 0045 0046 /** 0047 * Represents the category a field belongs to. 0048 */ 0049 enum FieldCategory { 0050 /** 0051 * All fields 0052 */ 0053 All = 0x0, 0054 /** 0055 * Frequently used fields 0056 */ 0057 Frequent = 0x01, 0058 /** 0059 * Fields which belong to the address, such as Street, City, Zip, etc. 0060 */ 0061 Address = 0x02, 0062 /** 0063 * Fields which store information about the e-mail contact, such as 0064 * e-mail address or mail client 0065 */ 0066 Email = 0x04, 0067 /** 0068 * Personal fields, such as Birthday, Home Address fields, IM Address, etc. 0069 */ 0070 Personal = 0x08, 0071 /** 0072 * Fields about the organization, such as Business Address fields, Department, 0073 * Profession, etc. 0074 */ 0075 Organization = 0x10, 0076 /** 0077 * Custom (user-defined) fields 0078 */ 0079 CustomCategory = 0x20, 0080 }; 0081 0082 /** 0083 * Returns the translated label for this field. 0084 */ 0085 Q_REQUIRED_RESULT virtual QString label(); 0086 0087 /** 0088 * Returns the ored categories the field belongs to. 0089 */ 0090 Q_REQUIRED_RESULT virtual int category(); 0091 0092 /** 0093 * Returns the translated label for @p category. 0094 * 0095 * @param category the category of type FieldCategory 0096 * @return the translated label 0097 */ 0098 static QString categoryLabel(int category); 0099 0100 /** 0101 * Returns a string representation of the value the field has in the given 0102 * Addressee. 0103 * 0104 * @return the string representation of the value or QString(), if it 0105 * is not possible to convert the value to a string. 0106 */ 0107 Q_REQUIRED_RESULT virtual QString value(const KContacts::Addressee &addressee); 0108 0109 /** 0110 * Sets the value of the field in the given Addressee. 0111 * 0112 * @return @c true on success or @c false, if the given string couldn't 0113 * be converted to a valid value. 0114 */ 0115 Q_REQUIRED_RESULT virtual bool setValue(KContacts::Addressee &addressee, const QString &value); 0116 0117 /** 0118 * Returns a string, that can be used for sorting. 0119 */ 0120 Q_REQUIRED_RESULT QString sortKey(const KContacts::Addressee &addressee); 0121 0122 /** 0123 * Returns, if the field is a user-defined field. 0124 * 0125 * @return @c true if this is a custom field, @c false otherwise 0126 */ 0127 Q_REQUIRED_RESULT virtual bool isCustom(); 0128 0129 /** 0130 * Returns, if the field is equal with @p field. 0131 * 0132 * @param field the field to compare this field to 0133 * @return @c true if the fields are equal, @c false otherwise 0134 */ 0135 Q_REQUIRED_RESULT virtual bool equals(Field *field); 0136 0137 /** 0138 * Returns a list of all fields. 0139 */ 0140 static Field::List allFields(); 0141 0142 /** 0143 * Returns a list of the default fields. 0144 */ 0145 Q_REQUIRED_RESULT static Field::List defaultFields(); 0146 0147 /** 0148 * Creates a custom field. 0149 * 0150 * @param label The label for this field 0151 * @param category The category of this field 0152 * @param key Unique key for this field 0153 * @param app Unique app name for this field 0154 */ 0155 static Field *createCustomField(const QString &label, int category, const QString &key, const QString &app); 0156 0157 /** 0158 * Delete all fields from list. 0159 */ 0160 static void deleteFields(); 0161 0162 /** 0163 * Save the field settings to a config file. 0164 * 0165 * @param cfg The config file object 0166 * @param identifier The unique identifier 0167 * @param fields The list of the fields 0168 */ 0169 static void saveFields(KConfigGroup &cfg, const QString &identifier, const Field::List &fields); 0170 /** 0171 * @overload 0172 * 0173 * Here, the list is stored in KSharedConfig::openConfig() in group "KABCFields". 0174 * 0175 * @param identifier The unique identifier 0176 * @param fields The list of the fields 0177 */ 0178 static void saveFields(const QString &identifier, const Field::List &fields); 0179 0180 /** 0181 * Load the field settings from a config file. 0182 * 0183 * @param cfg The config file object 0184 * @param identifier The unique identifier 0185 */ 0186 static Field::List restoreFields(const KConfigGroup &cfg, const QString &identifier); 0187 0188 /** 0189 * @overload 0190 * 0191 * Here, the list is loaded from KSharedConfig::openConfig() from group "KABCFields". 0192 * 0193 * @param identifier The unique identifier 0194 */ 0195 static Field::List restoreFields(const QString &identifier); 0196 0197 protected: 0198 /** 0199 * @internal 0200 * 0201 * Creates a field and appends it to the general list of fields. 0202 * 0203 * @param id The identifier for the field 0204 * @param category The optional category for the field 0205 */ 0206 static void createField(int id, int category = 0); 0207 0208 /** 0209 * @internal 0210 * 0211 * Creates a field and appends it to the list of default fields. 0212 * 0213 * @param id The identifier for the field 0214 * @param category The optional category for the field 0215 */ 0216 static void createDefaultField(int id, int category = 0); 0217 0218 private: 0219 class Private; 0220 0221 Field(Private *p); 0222 virtual ~Field(); 0223 0224 Private *const d; 0225 }; 0226 } 0227 #endif 0228 #endif