File indexing completed on 2024-02-18 03:55:20

0001 /*
0002     This file is part of the KContacts framework.
0003     SPDX-FileCopyrightText: 2001 Cornelius Schumacher <schumacher@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef KCONTACTS_ADDRESS_H
0009 #define KCONTACTS_ADDRESS_H
0010 
0011 #include "geo.h"
0012 #include "kcontacts_export.h"
0013 #include "namespace.h"
0014 
0015 #include <QList>
0016 #include <QMetaType>
0017 #include <QSharedDataPointer>
0018 #include <QString>
0019 #include <QUrl>
0020 
0021 namespace KContacts
0022 {
0023 class Geo;
0024 /**
0025   @brief
0026   Postal address information.
0027 
0028   This class represents information about a postal address.
0029 */
0030 class KCONTACTS_EXPORT Address
0031 {
0032     friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &s, const Address &addr);
0033     friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &s, Address &addr);
0034 
0035     Q_GADGET
0036     Q_PROPERTY(QString id READ id WRITE setId)
0037     Q_PROPERTY(bool isEmpty READ isEmpty)
0038     Q_PROPERTY(Type type READ type WRITE setType)
0039     Q_PROPERTY(QString typeLabel READ typeLabel)
0040     Q_PROPERTY(QString postOfficeBox READ postOfficeBox WRITE setPostOfficeBox)
0041     Q_PROPERTY(QString extended READ extended WRITE setExtended)
0042     Q_PROPERTY(QString street READ street WRITE setStreet)
0043     Q_PROPERTY(QString locality READ locality WRITE setLocality)
0044     Q_PROPERTY(QString region READ region WRITE setRegion)
0045     Q_PROPERTY(QString postalCode READ postalCode WRITE setPostalCode)
0046     Q_PROPERTY(QString country READ country WRITE setCountry)
0047     Q_PROPERTY(QString label READ label WRITE setLabel)
0048     Q_PROPERTY(KContacts::Geo geo READ geo WRITE setGeo)
0049 
0050     // TODO KF6: ideally this would be deprecated as it doesn't specify the formatting style
0051     // we cannot do that yet though due to Grantlee themes needing this (which cannot call
0052     // the invokable methods instead). The KF6::TextTemplate port might bring new options there,
0053     // otherwise we can at least switch this from postal to the multi-line style for KF6
0054     /**
0055      * Country-specific formatted address without an addressee using postal address style.
0056      * This is the same as calling formatted(AddressFormatStyle::Postal) with empty arguments.
0057      * @see formatted()
0058      * @since 5.12
0059      */
0060     Q_PROPERTY(QString formattedAddress READ formattedPostalAddress)
0061 
0062     /** geo: URI for this address.
0063      *  @see Address::geoUri()
0064      *  @since 5.106
0065      */
0066     Q_PROPERTY(QUrl geoUri READ geoUri)
0067 
0068 public:
0069     /**
0070       List of addresses.
0071     */
0072     typedef QList<Address> List;
0073 
0074     /**
0075       Address types:
0076       @see Type
0077     */
0078     enum TypeFlag {
0079         Dom = 1, /**< domestic */
0080         Intl = 2, /**< international */
0081         Postal = 4, /**< postal */
0082         Parcel = 8, /**< parcel */
0083         Home = 16, /**< home address */
0084         Work = 32, /**< address at work */
0085         Pref = 64, /**< preferred address */
0086     };
0087 
0088     /**
0089      * Stores a combination of #TypeFlag values.
0090      */
0091     Q_DECLARE_FLAGS(Type, TypeFlag)
0092     Q_FLAG(Type)
0093 
0094     /**
0095       List of address types.
0096     */
0097     typedef QList<TypeFlag> TypeList;
0098 
0099     /**
0100       Creates an empty address.
0101     */
0102     Address();
0103 
0104     /**
0105       Creates an address of the given @p type.
0106     */
0107     Address(Type type);
0108 
0109     /**
0110       Copy constructor.
0111     */
0112     Address(const Address &address);
0113 
0114     /**
0115       Destroys the address.
0116     */
0117     ~Address();
0118 
0119     /**
0120       Equality operator.
0121 
0122       @param addr the address to compare to
0123       @return @c true if @c this and @p addr are equal, otherwise @c false
0124     */
0125     Q_REQUIRED_RESULT bool operator==(const Address &other) const;
0126 
0127     /**
0128       Not-equal operator.
0129 
0130       @param addr the address to compare to
0131       @return @c true if @c this and @p addr are not equal, otherwise @c false
0132     */
0133     Q_REQUIRED_RESULT bool operator!=(const Address &other) const;
0134 
0135     /**
0136       Assignment operator.
0137 
0138       @param addr the address data to assign to @c this
0139       @return a reference to @c this
0140     */
0141     Address &operator=(const Address &other);
0142 
0143     /**
0144       Returns true, if the address is empty.
0145     */
0146     Q_REQUIRED_RESULT bool isEmpty() const;
0147 
0148     /**
0149       Clears all entries of the address.
0150     */
0151     void clear();
0152 
0153     /**
0154       Sets the unique @p identifier.
0155     */
0156     void setId(const QString &identifier);
0157 
0158     /**
0159       Returns the unique identifier.
0160     */
0161     Q_REQUIRED_RESULT QString id() const;
0162 
0163     /**
0164       Sets the type of address. See enum for definition of types.
0165 
0166       @param type type, can be a bitwise or of multiple types.
0167     */
0168     void setType(Type type);
0169 
0170     /**
0171       Returns the type of address. Can be a bitwise or of multiple types.
0172     */
0173     Q_REQUIRED_RESULT Type type() const;
0174 
0175     /**
0176       Returns a translated string of all types the address has.
0177     */
0178     Q_REQUIRED_RESULT QString typeLabel() const;
0179 
0180     /**
0181       Sets the post office box.
0182     */
0183     void setPostOfficeBox(const QString &postOfficeBox);
0184 
0185     /**
0186       Returns the post office box.
0187     */
0188     Q_REQUIRED_RESULT QString postOfficeBox() const;
0189 
0190     /**
0191       Returns the translated label for post office box field.
0192     */
0193     static QString postOfficeBoxLabel();
0194 
0195     /**
0196       Sets the @p extended address information.
0197     */
0198     void setExtended(const QString &extended);
0199 
0200     /**
0201       Returns the extended address information.
0202     */
0203     Q_REQUIRED_RESULT QString extended() const;
0204 
0205     /**
0206       Returns the translated label for extended field.
0207     */
0208     static QString extendedLabel();
0209 
0210     /**
0211       Sets the @p street (including house number).
0212     */
0213     void setStreet(const QString &street);
0214 
0215     /**
0216       Returns the street.
0217     */
0218     Q_REQUIRED_RESULT QString street() const;
0219 
0220     /**
0221       Returns the translated label for street field.
0222     */
0223     static QString streetLabel();
0224 
0225     /**
0226       Sets the @p locality, e.g. city.
0227 
0228       @param locality the locality of the address, e.g. city
0229     */
0230     void setLocality(const QString &locality);
0231 
0232     /**
0233       Returns the locality.
0234     */
0235     Q_REQUIRED_RESULT QString locality() const;
0236 
0237     /**
0238       Returns the translated label for locality field.
0239     */
0240     static QString localityLabel();
0241 
0242     /**
0243       Sets the @p region, e.g. state.
0244 
0245       @param region the region the address falls into, e.g. state
0246     */
0247     void setRegion(const QString &region);
0248 
0249     /**
0250       Returns the region.
0251     */
0252     Q_REQUIRED_RESULT QString region() const;
0253 
0254     /**
0255       Returns the translated label for region field.
0256     */
0257     static QString regionLabel();
0258 
0259     /**
0260       Sets the postal @p code.
0261     */
0262     void setPostalCode(const QString &code);
0263 
0264     /**
0265       Returns the postal code.
0266     */
0267     Q_REQUIRED_RESULT QString postalCode() const;
0268 
0269     /**
0270       Returns the translated label for postal code field.
0271     */
0272     static QString postalCodeLabel();
0273 
0274     /**
0275       Sets the @p country.
0276     */
0277     void setCountry(const QString &country);
0278 
0279     /**
0280       Returns the country.
0281     */
0282     Q_REQUIRED_RESULT QString country() const;
0283 
0284     /**
0285       Returns the translated label for country field.
0286     */
0287     static QString countryLabel();
0288 
0289     /**
0290       Sets the delivery @p label. This is the literal text to be used as label.
0291 
0292       @param label the string to use for delivery labels
0293     */
0294     void setLabel(const QString &label);
0295 
0296     /**
0297       Returns the delivery label.
0298     */
0299     Q_REQUIRED_RESULT QString label() const;
0300 
0301     /**
0302       Returns the translated label for delivery label field.
0303     */
0304     static QString labelLabel();
0305 
0306     /**
0307       Returns the list of available types.
0308     */
0309     static TypeList typeList();
0310 
0311     /**
0312       Returns the translated label for the given @p type.
0313     */
0314     static QString typeLabel(Type type);
0315 
0316     /**
0317       Returns a string representation of the address.
0318     */
0319     Q_REQUIRED_RESULT QString toString() const;
0320 
0321     // note: cannot be called "formattedAddress" due to a collision
0322     // with the property of that name in QML
0323     /**
0324       Returns this address formatted according to the country-specific
0325       address formatting rules. The formatting rules applied depend on
0326       either the addresses {@link #country country} field, or (if the
0327       latter is empty) on the system country setting.
0328 
0329       @param style      the formatting style variant to use
0330       @param realName   the formatted name of the contact
0331       @param orgaName   the name of the organization or company
0332       @return           the formatted address
0333       @since 5.92
0334     */
0335     Q_REQUIRED_RESULT Q_INVOKABLE QString formatted(KContacts::AddressFormatStyle style,
0336                                                     const QString &realName = QString(),
0337                                                     const QString &orgaName = QString()) const;
0338 
0339     static QString typeFlagLabel(TypeFlag type);
0340 
0341     /**
0342       Set geographic position.
0343      */
0344     void setGeo(const Geo &geo);
0345 
0346     /**
0347       Return geographic position.
0348      */
0349     Q_REQUIRED_RESULT Geo geo() const;
0350 
0351     /**
0352      * Returns a geo: URI representing this address.
0353      * This contains either the geographic coordinate if set, or the address as query term.
0354      * This can be used to show the address in the default map view.
0355      * @since 5.106
0356      */
0357     Q_REQUIRED_RESULT QUrl geoUri() const;
0358 
0359 private:
0360     KCONTACTS_NO_EXPORT QString formattedPostalAddress() const;
0361 
0362     class Private;
0363     QSharedDataPointer<Private> d;
0364 };
0365 
0366 Q_DECLARE_OPERATORS_FOR_FLAGS(Address::Type)
0367 
0368 /**
0369   Serializes the @p address object into the @p stream.
0370 */
0371 KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Address &address);
0372 
0373 /**
0374   Initializes the @p address object from the @p stream.
0375 */
0376 KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Address &address);
0377 }
0378 
0379 #endif