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 
14 namespace KContacts
15 {
16 
17 class Address;
18 class 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  */
30 class 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 
39 public:
40  explicit 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 
53 private:
54  friend class AddressFormatElementPrivate;
56 };
57 
58 class 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  */
68 class 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 
78 public:
79  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 
109 private:
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  */
120 class KCONTACTS_EXPORT AddressFormatRepository
121 {
122  Q_GADGET
123 public:
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
AddressFormatField
Address field types.
Definition: namespace.h:44
AddressFormatScriptPreference
Indicate whether to use a address format in the local script or a Latin transliteration.
Definition: namespace.h:72
Postal address information.
Definition: address.h:30
A single element in an address format.
Definition: addressformat.h:30
Provides address format information for a given country.
Information on how addresses are formatted in a specific country/language.
Definition: addressformat.h:68
AddressFormatPreference
Indicate whether to prefer an address format for (postal) business address or a generic one.
Definition: namespace.h:82
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Thu Feb 15 2024 03:50:13 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.