File indexing completed on 2024-07-14 14:27:48

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