1 /*
2     This file is part of the KDE libraries
3     SPDX-FileCopyrightText: 2003 Carsten Pfeiffer <pfeiffer@kde.org>
4 
5     This SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KCONTACTS_ADDRESSEEHELPER_H
9 #define KCONTACTS_ADDRESSEEHELPER_H
10 
11 #include "kcontacts_export.h"
12 
13 #include <QObject>
14 
15 namespace KContacts
16 {
17 class AddresseeHelperPrivate;
18 
19 // TODO KF6: unexport and turn into an implementation detail
20 // this is unused externally, both as code as well as via the config file
21 // so we only need this internally and can probably also drop the config
22 // file access
23 
24 /**
25  * This singleton class stores static data, which is shared
26  * by all Addressee objects. It maintains three lists of
27  * strings, which can be queried using this class:
28  *
29  * - a list of honoric prefixes, like "Mrs.", "Prof." etc,
30  *   see containsTitle()
31  * - a list of inclusions, such as "van" or "de", see
32  *   containsPrefix()
33  * - a list of honoric suffixes, such as "I" or "Jr.", see
34  *   containsSuffix()
35  *
36  * All of these lists have a hardcoded and a configurable
37  * part. The configurable part is found in @c kabcrc, group
38  * @c General, fields @c Prefixes, @c Inclusions, and
39  * @c Suffixes.
40  *
41  * In addition to the above, this class stores one conveniece
42  * setting: it stores whether or not a single name component
43  * should be interpreted as a family name (see
44  * treatAsFamilyName()). The corresponding configuration
45  * field is @c TreatAsFamilyName.
46  *
47  * @warning Do not use, to be removed from the public interface in KF6.
48  */
49 class KCONTACTS_EXPORT KCONTACTS_DEPRECATED_VERSION(5, 89, "unused externally") AddresseeHelper : public QObject
50 {
51     Q_OBJECT
52 
53 public:
54     /**
55      * Singleton interface to this class
56      *
57      * @return a pointer to the unique instance of this class.
58      */
59     static AddresseeHelper *self();
60 
61     /**
62      * Queries the list of honoric prefixes.
63      *
64      * @param title the honoric prefix to search for
65      * @return @c true, if @p title was found in the list,
66      *         @c false otherwise
67      */
68     Q_REQUIRED_RESULT bool containsTitle(const QString &title) const;
69 
70     /**
71      * Queries the list of inclusions.
72      *
73      * @param prefix the inclusion to search for
74      * @return @c true, if @p prefix was found in the list,
75      *         @c false otherwise
76      */
77     Q_REQUIRED_RESULT bool containsPrefix(const QString &prefix) const;
78 
79     /**
80      * Queries the list of honoric suffixes.
81      *
82      * @param suffix the honoric suffix to search for
83      * @return @c true, if @p suffix was found in the list,
84      *         @c false otherwise
85      */
86     Q_REQUIRED_RESULT bool containsSuffix(const QString &suffix) const;
87 
88     /**
89      * Returns whether or not a single name component should
90      * be interpreted as a family name.
91      *
92      * @return @c true if single name component is a family name,
93      *         @c false otherwise.
94      */
95     Q_REQUIRED_RESULT bool treatAsFamilyName() const;
96 
97     /** @internal */
98     AddresseeHelper();
99 
100     ~AddresseeHelper() override;
101 
102 public Q_SLOTS:
103     /**
104      * Recreates the static data and reparses the configuration.
105      */
106     void initSettings();
107 
108 private:
109     QScopedPointer<AddresseeHelperPrivate> d;
110 };
111 }
112 
113 #endif
114