File indexing completed on 2023-09-24 07:59:46

0001 /*
0002     SPDX-FileCopyrightText: 2022 Volker Krause <vkrause@kde.org>
0003     SPDX-License-Identifier: LGPL-2.0-or-later
0004 */
0005 
0006 #ifndef KCONTACTS_ADDRESSFORMAT_H
0007 #define KCONTACTS_ADDRESSFORMAT_H
0008 
0009 #include "kcontacts_export.h"
0010 #include "namespace.h"
0011 
0012 #include <QExplicitlySharedDataPointer>
0013 
0014 namespace KContacts
0015 {
0016 
0017 class Address;
0018 class AddressFormatElementPrivate;
0019 
0020 /** A single element in an address format.
0021  *
0022  *  A format element can be one of three types:
0023  *  - a field from the address data
0024  *  - a literal string
0025  *  - a separator
0026  *
0027  *  @since 5.92
0028  *  @see KContacts::AddressFormat
0029  */
0030 class KCONTACTS_EXPORT AddressFormatElement
0031 {
0032     Q_GADGET
0033     Q_PROPERTY(bool isField READ isField)
0034     Q_PROPERTY(KContacts::AddressFormatField field READ field)
0035     Q_PROPERTY(bool isLiteral READ isLiteral)
0036     Q_PROPERTY(QString literal READ literal)
0037     Q_PROPERTY(bool isSeparator READ isSeparator)
0038 
0039 public:
0040     explicit AddressFormatElement();
0041     AddressFormatElement(const AddressFormatElement &);
0042     ~AddressFormatElement();
0043     AddressFormatElement &operator=(const AddressFormatElement &);
0044 
0045     bool isField() const;
0046     AddressFormatField field() const;
0047 
0048     bool isLiteral() const;
0049     QString literal() const;
0050 
0051     bool isSeparator() const;
0052 
0053 private:
0054     friend class AddressFormatElementPrivate;
0055     QExplicitlySharedDataPointer<AddressFormatElementPrivate> d;
0056 };
0057 
0058 class AddressFormatPrivate;
0059 
0060 /** Information on how addresses are formatted in a specific country/language.
0061  *  This is primarily used for displaying or printing addresses, but is also
0062  *  useful for country specific adjustment in address edit forms, or for parsing
0063  *  textual addresses.
0064  *
0065  *  @since 5.92
0066  *  @see AddressFormatRepository
0067  */
0068 class KCONTACTS_EXPORT AddressFormat
0069 {
0070     Q_GADGET
0071     Q_PROPERTY(QString country READ country)
0072     Q_PROPERTY(QList<KContacts::AddressFormatElement> elements READ elementsForQml)
0073     Q_PROPERTY(KContacts::AddressFormatFields requiredFields READ requiredFields)
0074     Q_PROPERTY(KContacts::AddressFormatFields usedFields READ usedFields)
0075     Q_PROPERTY(KContacts::AddressFormatFields upperCaseFields READ upperCaseFields)
0076     Q_PROPERTY(QString postalCodeRegularExpression READ postalCodeRegularExpression)
0077 
0078 public:
0079     AddressFormat();
0080     AddressFormat(const AddressFormat &);
0081     ~AddressFormat();
0082     AddressFormat &operator=(const AddressFormat &);
0083 
0084     /** ISO 3166-1 alpha2 code of the country this format is for. */
0085     QString country() const;
0086 
0087     /** A sequence of field/literal/separator elements for this address format. */
0088     const std::vector<AddressFormatElement> &elements() const;
0089 
0090     /** The address fields that are required by this format for a valid address.
0091      *  @note This information is not available for all formats.
0092      */
0093     AddressFormatFields requiredFields() const;
0094 
0095     /** The address fields that are used by this format.
0096      *  This is a superset of requiredFields(), and this information is
0097      *  available for all formats.
0098      */
0099     AddressFormatFields usedFields() const;
0100 
0101     /** Fields that should be printed in upper case regardless
0102      *  of the input casing.
0103      */
0104     AddressFormatFields upperCaseFields() const;
0105 
0106     /** Regular expression matching the postal codes of this format. */
0107     QString postalCodeRegularExpression() const;
0108 
0109 private:
0110     KCONTACTS_NO_EXPORT QList<AddressFormatElement> elementsForQml() const;
0111 
0112     friend class AddressFormatPrivate;
0113     QExplicitlySharedDataPointer<AddressFormatPrivate> d;
0114 };
0115 
0116 /** Provides address format information for a given country.
0117  *
0118  *  @since 5.92
0119  */
0120 class KCONTACTS_EXPORT AddressFormatRepository
0121 {
0122     Q_GADGET
0123 public:
0124     /** Look up format data for a country.
0125      *  @param countryCode ISO 3166-1 alpha 2 country code.
0126      */
0127     static Q_INVOKABLE KContacts::AddressFormat formatForCountry(const QString &countryCode,
0128                                                                  KContacts::AddressFormatScriptPreference scriptPref,
0129                                                                  KContacts::AddressFormatPreference formatPref = AddressFormatPreference::Generic);
0130 
0131     /** Look up format data for a given address.
0132      *  The preferred script is determined from the script used in the address object.
0133      *  If the address object has no country information set, the local country is assumed.
0134      */
0135     static KContacts::AddressFormat formatForAddress(const Address &address, AddressFormatPreference formatPref = AddressFormatPreference::Generic);
0136 };
0137 
0138 }
0139 
0140 Q_DECLARE_METATYPE(KContacts::AddressFormat)
0141 Q_DECLARE_METATYPE(KContacts::AddressFormatElement)
0142 Q_DECLARE_METATYPE(KContacts::AddressFormatRepository)
0143 
0144 #endif // KCONTACTS_ADDRESSFORMAT_H