KContacts

addressformat.h
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();
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;
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:
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;
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,
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
A single element in an address format.
Provides address format information for a given country.
Information on how addresses are formatted in a specific country/language.
Postal address information.
Definition address.h:31
Everything that needs to go in to the KContacts Q_NAMESPACE meta object.
AddressFormatPreference
Indicate whether to prefer an address format for (postal) business address or a generic one.
Definition namespace.h:82
AddressFormatScriptPreference
Indicate whether to use a address format in the local script or a Latin transliteration.
Definition namespace.h:72
AddressFormatField
Address field types.
Definition namespace.h:44
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:01:26 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.