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/*!
21 * \class KContacts::AddressFormatElement
22 * \inheaderfile KContacts/AddressFormat
23 * \inmodule KContacts
24 *
25 * \brief A single element in an address format.
26 *
27 * A format element can be one of three types:
28 * \list
29 * \li a field from the address data
30 * \li a literal string
31 * \li a separator
32 * \endlist
33 *
34 * \since 5.92
35 * \sa KContacts::AddressFormat
36 */
37class KCONTACTS_EXPORT AddressFormatElement
38{
39 Q_GADGET
40
41 /*!
42 * \property KContacts::AddressFormatElement::isField
43 */
44 Q_PROPERTY(bool isField READ isField)
45
46 /*!
47 * \property KContacts::AddressFormatElement::field
48 */
49 Q_PROPERTY(KContacts::AddressFormatField field READ field)
50
51 /*!
52 * \property KContacts::AddressFormatElement::isLiteral
53 */
54 Q_PROPERTY(bool isLiteral READ isLiteral)
55
56 /*!
57 * \property KContacts::AddressFormatElement::literal
58 */
59 Q_PROPERTY(QString literal READ literal)
60
61 /*!
62 * \property KContacts::AddressFormatElement::isSeparator
63 */
64 Q_PROPERTY(bool isSeparator READ isSeparator)
65
66public:
67 /*!
68 *
69 */
70 explicit AddressFormatElement();
71 AddressFormatElement(const AddressFormatElement &);
72 ~AddressFormatElement();
73 AddressFormatElement &operator=(const AddressFormatElement &);
74
75 bool isField() const;
76 AddressFormatField field() const;
77
78 bool isLiteral() const;
79 QString literal() const;
80
81 bool isSeparator() const;
82
83private:
84 friend class AddressFormatElementPrivate;
85 QExplicitlySharedDataPointer<AddressFormatElementPrivate> d;
86};
87
88class AddressFormatPrivate;
89
90/*!
91 * \class KContacts::AddressFormat
92 * \inheaderfile KContacts/AddressFormat
93 * \inmodule KContacts
94 *
95 * \brief Information on how addresses are formatted in a specific country/language.
96 *
97 * This is primarily used for displaying or printing addresses, but is also
98 * useful for country specific adjustment in address edit forms, or for parsing
99 * textual addresses.
100 *
101 * \since 5.92
102 * \sa AddressFormatRepository
103 */
104class KCONTACTS_EXPORT AddressFormat
105{
106 Q_GADGET
107
108 /*!
109 * \property KContacts::AddressFormat::country
110 */
111 Q_PROPERTY(QString country READ country)
112
113 /*!
114 * \property KContacts::AddressFormat::elements
115 */
116 Q_PROPERTY(QList<KContacts::AddressFormatElement> elements READ elementsForQml)
117
118 /*!
119 * \property KContacts::AddressFormat::requiredFields
120 */
121 Q_PROPERTY(KContacts::AddressFormatFields requiredFields READ requiredFields)
122
123 /*!
124 * \property KContacts::AddressFormat::usedFields
125 */
126 Q_PROPERTY(KContacts::AddressFormatFields usedFields READ usedFields)
127
128 /*!
129 * \property KContacts::AddressFormat::upperCaseFields
130 */
131 Q_PROPERTY(KContacts::AddressFormatFields upperCaseFields READ upperCaseFields)
132
133 /*!
134 * \property KContacts::AddressFormat::postalCodeRegularExpression
135 */
136 Q_PROPERTY(QString postalCodeRegularExpression READ postalCodeRegularExpression)
137
138public:
139 /*!
140 *
141 */
142 AddressFormat();
143 AddressFormat(const AddressFormat &);
144 ~AddressFormat();
145 AddressFormat &operator=(const AddressFormat &);
146
147 /*! ISO 3166-1 alpha2 code of the country this format is for. */
148 QString country() const;
149
150 /*! A sequence of field/literal/separator elements for this address format. */
151 const std::vector<AddressFormatElement> &elements() const;
152
153 /*! The address fields that are required by this format for a valid address.
154 * \note This information is not available for all formats.
155 */
156 AddressFormatFields requiredFields() const;
157
158 /*! The address fields that are used by this format.
159 * This is a superset of requiredFields(), and this information is
160 * available for all formats.
161 */
162 AddressFormatFields usedFields() const;
163
164 /*! Fields that should be printed in upper case regardless
165 * of the input casing.
166 */
167 AddressFormatFields upperCaseFields() const;
168
169 /*! Regular expression matching the postal codes of this format. */
170 QString postalCodeRegularExpression() const;
171
172private:
173 KCONTACTS_NO_EXPORT QList<AddressFormatElement> elementsForQml() const;
174
175 friend class AddressFormatPrivate;
176 QExplicitlySharedDataPointer<AddressFormatPrivate> d;
177};
178
179/*!
180 * \class KContacts::AddressFormatRepository
181 * \inheaderfile KContacts/AddressFormat
182 * \inmodule KContacts
183 *
184 * \brief Provides address format information for a given country.
185 *
186 * \since 5.92
187 */
188class KCONTACTS_EXPORT AddressFormatRepository
189{
190 Q_GADGET
191public:
192 /*!
193 * Look up format data for a country.
194 * \a countryCode ISO 3166-1 alpha 2 country code.
195 */
196 static Q_INVOKABLE KContacts::AddressFormat formatForCountry(const QString &countryCode,
197 KContacts::AddressFormatScriptPreference scriptPref,
198 KContacts::AddressFormatPreference formatPref = AddressFormatPreference::Generic);
199
200 /*!
201 * Look up format data for a given address.
202 * The preferred script is determined from the script used in the address object.
203 * If the address object has no country information set, the local country is assumed.
204 */
205 static KContacts::AddressFormat formatForAddress(const Address &address, AddressFormatPreference formatPref = AddressFormatPreference::Generic);
206};
207
208}
209
210#endif // KCONTACTS_ADDRESSFORMAT_H
211

source code of kcontacts/src/addressformat.h