1/*
2 SPDX-FileCopyrightText: 2022 Volker Krause <vkrause@kde.org>
3 SPDX-License-Identifier: LGPL-2.0-or-later
4*/
5
6#ifndef KCONTACTS_ADDRESSFORMAT_H
7#define KCONTACTS_ADDRESSFORMAT_H
8
9#include "kcontacts_export.h"
10#include "namespace.h"
11
12#include <QExplicitlySharedDataPointer>
13
14namespace KContacts
15{
16
17class Address;
18class AddressFormatElementPrivate;
19
20/** A single element in an address format.
21 *
22 * A format element can be one of three types:
23 * - a field from the address data
24 * - a literal string
25 * - a separator
26 *
27 * @since 5.92
28 * @see KContacts::AddressFormat
29 */
30class KCONTACTS_EXPORT AddressFormatElement
31{
32 Q_GADGET
33 Q_PROPERTY(bool isField READ isField)
34 Q_PROPERTY(KContacts::AddressFormatField field READ field)
35 Q_PROPERTY(bool isLiteral READ isLiteral)
36 Q_PROPERTY(QString literal READ literal)
37 Q_PROPERTY(bool isSeparator READ isSeparator)
38
39public:
40 explicit AddressFormatElement();
41 AddressFormatElement(const AddressFormatElement &);
42 ~AddressFormatElement();
43 AddressFormatElement &operator=(const AddressFormatElement &);
44
45 bool isField() const;
46 AddressFormatField field() const;
47
48 bool isLiteral() const;
49 QString literal() const;
50
51 bool isSeparator() const;
52
53private:
54 friend class AddressFormatElementPrivate;
55 QExplicitlySharedDataPointer<AddressFormatElementPrivate> d;
56};
57
58class AddressFormatPrivate;
59
60/** Information on how addresses are formatted in a specific country/language.
61 * This is primarily used for displaying or printing addresses, but is also
62 * useful for country specific adjustment in address edit forms, or for parsing
63 * textual addresses.
64 *
65 * @since 5.92
66 * @see AddressFormatRepository
67 */
68class KCONTACTS_EXPORT AddressFormat
69{
70 Q_GADGET
71 Q_PROPERTY(QString country READ country)
72 Q_PROPERTY(QList<KContacts::AddressFormatElement> elements READ elementsForQml)
73 Q_PROPERTY(KContacts::AddressFormatFields requiredFields READ requiredFields)
74 Q_PROPERTY(KContacts::AddressFormatFields usedFields READ usedFields)
75 Q_PROPERTY(KContacts::AddressFormatFields upperCaseFields READ upperCaseFields)
76 Q_PROPERTY(QString postalCodeRegularExpression READ postalCodeRegularExpression)
77
78public:
79 AddressFormat();
80 AddressFormat(const AddressFormat &);
81 ~AddressFormat();
82 AddressFormat &operator=(const AddressFormat &);
83
84 /** ISO 3166-1 alpha2 code of the country this format is for. */
85 QString country() const;
86
87 /** A sequence of field/literal/separator elements for this address format. */
88 const std::vector<AddressFormatElement> &elements() const;
89
90 /** The address fields that are required by this format for a valid address.
91 * @note This information is not available for all formats.
92 */
93 AddressFormatFields requiredFields() const;
94
95 /** The address fields that are used by this format.
96 * This is a superset of requiredFields(), and this information is
97 * available for all formats.
98 */
99 AddressFormatFields usedFields() const;
100
101 /** Fields that should be printed in upper case regardless
102 * of the input casing.
103 */
104 AddressFormatFields upperCaseFields() const;
105
106 /** Regular expression matching the postal codes of this format. */
107 QString postalCodeRegularExpression() const;
108
109private:
110 KCONTACTS_NO_EXPORT QList<AddressFormatElement> elementsForQml() const;
111
112 friend class AddressFormatPrivate;
113 QExplicitlySharedDataPointer<AddressFormatPrivate> d;
114};
115
116/** Provides address format information for a given country.
117 *
118 * @since 5.92
119 */
120class KCONTACTS_EXPORT AddressFormatRepository
121{
122 Q_GADGET
123public:
124 /** Look up format data for a country.
125 * @param countryCode ISO 3166-1 alpha 2 country code.
126 */
127 static Q_INVOKABLE KContacts::AddressFormat formatForCountry(const QString &countryCode,
128 KContacts::AddressFormatScriptPreference scriptPref,
129 KContacts::AddressFormatPreference formatPref = AddressFormatPreference::Generic);
130
131 /** Look up format data for a given address.
132 * The preferred script is determined from the script used in the address object.
133 * If the address object has no country information set, the local country is assumed.
134 */
135 static KContacts::AddressFormat formatForAddress(const Address &address, AddressFormatPreference formatPref = AddressFormatPreference::Generic);
136};
137
138}
139
140#endif // KCONTACTS_ADDRESSFORMAT_H
141

source code of kcontacts/src/addressformat.h