address.h

/*
    This file is part of the KContacts framework.
    SPDX-FileCopyrightText: 2001 Cornelius Schumacher <[email protected]>
 
    SPDX-License-Identifier: LGPL-2.0-or-later
*/
 
#ifndef KCONTACTS_ADDRESS_H
#define KCONTACTS_ADDRESS_H
 
#include "geo.h"
#include "kcontacts_export.h"
#include "namespace.h"
 
#include <QMetaType>
#include <QSharedDataPointer>
#include <QString>
#include <QUrl>
#include <QVector>
 
namespace KContacts
{
class Geo;
/**
  @brief
  Postal address information.
 
  This class represents information about a postal address.
*/
class KCONTACTS_EXPORT Address
{
    friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &s, const Address &addr);
    friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &s, Address &addr);
 
    Q_GADGET
    Q_PROPERTY(QString id READ id WRITE setId)
    Q_PROPERTY(bool isEmpty READ isEmpty)
    Q_PROPERTY(Type type READ type WRITE setType)
    Q_PROPERTY(QString typeLabel READ typeLabel)
    Q_PROPERTY(QString postOfficeBox READ postOfficeBox WRITE setPostOfficeBox)
    Q_PROPERTY(QString extended READ extended WRITE setExtended)
    Q_PROPERTY(QString street READ street WRITE setStreet)
    Q_PROPERTY(QString locality READ locality WRITE setLocality)
    Q_PROPERTY(QString region READ region WRITE setRegion)
    Q_PROPERTY(QString postalCode READ postalCode WRITE setPostalCode)
    Q_PROPERTY(QString country READ country WRITE setCountry)
    Q_PROPERTY(QString label READ label WRITE setLabel)
    Q_PROPERTY(KContacts::Geo geo READ geo WRITE setGeo)
 
    // TODO KF6: ideally this would be deprecated as it doesn't specify the formatting style
    // we cannot do that yet though due to Grantlee themes needing this (which cannot call
    // the invokable methods instead). The KF6::TextTemplate port might bring new options there,
    // otherwise we can at least switch this from postal to the multi-line style for KF6
    /**
     * Country-specific formatted address without an addressee using postal address style.
     * This is the same as calling formatted(AddressFormatStyle::Postal) with empty arguments.
     * @see formatted()
     * @since 5.12
     */
    Q_PROPERTY(QString formattedAddress READ formattedPostalAddress)
 
    /** geo: URI for this address.
     *  @see Address::geoUri()
     *  @since 5.106
     */
    Q_PROPERTY(QUrl geoUri READ geoUri)
 
public:
    /**
      List of addresses.
    */
    typedef QVector<Address> List;
 
    /**
      Address types:
      @see Type
    */
    enum TypeFlag {
        Dom = 1, /**< domestic */
        Intl = 2, /**< international */
        Postal = 4, /**< postal */
        Parcel = 8, /**< parcel */
        Home = 16, /**< home address */
        Work = 32, /**< address at work */
        Pref = 64, /**< preferred address */
    };
 
    /**
     * Stores a combination of #TypeFlag values.
     */
    Q_DECLARE_FLAGS(Type, TypeFlag)
    Q_FLAG(Type)
 
    /**
      List of address types.
    */
    typedef QList<TypeFlag> TypeList;
 
    /**
      Creates an empty address.
    */
    Address();
 
    /**
      Creates an address of the given @p type.
    */
    Address(Type type);
 
    /**
      Copy constructor.
    */
    Address(const Address &address);
 
    /**
      Destroys the address.
    */
    ~Address();
 
    /**
      Equality operator.
 
      @param addr the address to compare to
      @return @c true if @c this and @p addr are equal, otherwise @c false
    */
    Q_REQUIRED_RESULT bool operator==(const Address &other) const;
 
    /**
      Not-equal operator.
 
      @param addr the address to compare to
      @return @c true if @c this and @p addr are not equal, otherwise @c false
    */
    Q_REQUIRED_RESULT bool operator!=(const Address &other) const;
 
    /**
      Assignment operator.
 
      @param addr the address data to assign to @c this
      @return a reference to @c this
    */
    Address &operator=(const Address &other);
 
    /**
      Returns true, if the address is empty.
    */
    Q_REQUIRED_RESULT bool isEmpty() const;
 
    /**
      Clears all entries of the address.
    */
    void clear();
 
    /**
      Sets the unique @p identifier.
    */
    void setId(const QString &identifier);
 
    /**
      Returns the unique identifier.
    */
    Q_REQUIRED_RESULT QString id() const;
 
    /**
      Sets the type of address. See enum for definition of types.
 
      @param type type, can be a bitwise or of multiple types.
    */
    void setType(Type type);
 
    /**
      Returns the type of address. Can be a bitwise or of multiple types.
    */
    Q_REQUIRED_RESULT Type type() const;
 
    /**
      Returns a translated string of all types the address has.
    */
    Q_REQUIRED_RESULT QString typeLabel() const;
 
    /**
      Sets the post office box.
    */
    void setPostOfficeBox(const QString &postOfficeBox);
 
    /**
      Returns the post office box.
    */
    Q_REQUIRED_RESULT QString postOfficeBox() const;
 
    /**
      Returns the translated label for post office box field.
    */
    static QString postOfficeBoxLabel();
 
    /**
      Sets the @p extended address information.
    */
    void setExtended(const QString &extended);
 
    /**
      Returns the extended address information.
    */
    Q_REQUIRED_RESULT QString extended() const;
 
    /**
      Returns the translated label for extended field.
    */
    static QString extendedLabel();
 
    /**
      Sets the @p street (including house number).
    */
    void setStreet(const QString &street);
 
    /**
      Returns the street.
    */
    Q_REQUIRED_RESULT QString street() const;
 
    /**
      Returns the translated label for street field.
    */
    static QString streetLabel();
 
    /**
      Sets the @p locality, e.g. city.
 
      @param locality the locality of the address, e.g. city
    */
    void setLocality(const QString &locality);
 
    /**
      Returns the locality.
    */
    Q_REQUIRED_RESULT QString locality() const;
 
    /**
      Returns the translated label for locality field.
    */
    static QString localityLabel();
 
    /**
      Sets the @p region, e.g. state.
 
      @param region the region the address falls into, e.g. state
    */
    void setRegion(const QString &region);
 
    /**
      Returns the region.
    */
    Q_REQUIRED_RESULT QString region() const;
 
    /**
      Returns the translated label for region field.
    */
    static QString regionLabel();
 
    /**
      Sets the postal @p code.
    */
    void setPostalCode(const QString &code);
 
    /**
      Returns the postal code.
    */
    Q_REQUIRED_RESULT QString postalCode() const;
 
    /**
      Returns the translated label for postal code field.
    */
    static QString postalCodeLabel();
 
    /**
      Sets the @p country.
    */
    void setCountry(const QString &country);
 
    /**
      Returns the country.
    */
    Q_REQUIRED_RESULT QString country() const;
 
    /**
      Returns the translated label for country field.
    */
    static QString countryLabel();
 
    /**
      Sets the delivery @p label. This is the literal text to be used as label.
 
      @param label the string to use for delivery labels
    */
    void setLabel(const QString &label);
 
    /**
      Returns the delivery label.
    */
    Q_REQUIRED_RESULT QString label() const;
 
    /**
      Returns the translated label for delivery label field.
    */
    static QString labelLabel();
 
    /**
      Returns the list of available types.
    */
    static TypeList typeList();
 
    /**
      Returns the translated label for the given @p type.
    */
    static QString typeLabel(Type type);
 
    /**
      Returns a string representation of the address.
    */
    Q_REQUIRED_RESULT QString toString() const;
 
#if KCONTACTS_ENABLE_DEPRECATED_SINCE(5, 92)
    /**
      Returns this address formatted according to the country-specific
      postal address formatting rules. The formatting rules applied depend on
      either the addresses {@link #country country} field, or (if the
      latter is empty) on the system country setting. If companyName is
      provided, an available business address format will be preferred.
 
      @param realName   the formatted name of the contact
      @param orgaName   the name of the organization or company
      @return           the formatted address (containing newline characters)
      @deprecated since 5.92, use formatted() instead, using AddressFormatStyle::Postal
                  to obtain the identical result.
    */
    Q_REQUIRED_RESULT
    KCONTACTS_DEPRECATED_VERSION(5, 92, "Use KContacts::Address::formatted() instead")
    QString formattedAddress(const QString &realName = QString(), const QString &orgaName = QString()) const;
#endif
 
    // note: cannot be called "formattedAddress" due to a collision
    // with the property of that name in QML
    /**
      Returns this address formatted according to the country-specific
      address formatting rules. The formatting rules applied depend on
      either the addresses {@link #country country} field, or (if the
      latter is empty) on the system country setting.
 
      @param style      the formatting style variant to use
      @param realName   the formatted name of the contact
      @param orgaName   the name of the organization or company
      @return           the formatted address
      @since 5.92
    */
    Q_REQUIRED_RESULT Q_INVOKABLE QString formatted(KContacts::AddressFormatStyle style,
                                                    const QString &realName = QString(),
                                                    const QString &orgaName = QString()) const;
 
#if KCONTACTS_ENABLE_DEPRECATED_SINCE(5, 89)
    /**
      Returns ISO code for a localized country name. Only localized country
      names will be understood.
      @param cname  name of the country
      @return       two digit ISO code, empty string if the country was not
                    recognized
      @deprecated since 5.88, use KCountry::fromName() instead.
                  Note that this function returned the ISO code incorrectly in lower case,
                  while KCountry does not do that.
    */
    KCONTACTS_DEPRECATED_VERSION(5, 89, "Use KCountry::fromName()")
    static QString countryToISO(const QString &cname);
#endif
 
#if KCONTACTS_ENABLE_DEPRECATED_SINCE(5, 89)
    /**
      Returns a localized country name for a ISO code.
      This might be replaced by a KLocale method in the future.
      @param ISOname two digit ISO code
      @return        localized name of the country
      @deprecated since 5.88, use KCountry::fromAlpha2() instead.
                  Note that this function returns @p ISOname if that is not a valid country code,
                  while KCountry will need an explicit check for that case.
    */
    KCONTACTS_DEPRECATED_VERSION(5, 89, "Use KCountry::fromAlpha2()")
    static QString ISOtoCountry(const QString &ISOname);
#endif
 
    static QString typeFlagLabel(TypeFlag type);
 
    /**
      Set geographic position.
     */
    void setGeo(const Geo &geo);
 
    /**
      Return geographic position.
     */
    Q_REQUIRED_RESULT Geo geo() const;
 
    /**
     * Returns a geo: URI representing this address.
     * This contains either the geographic coordinate if set, or the address as query term.
     * This can be used to show the address in the default map view.
     * @since 5.106
     */
    Q_REQUIRED_RESULT QUrl geoUri() const;
 
private:
    KCONTACTS_NO_EXPORT QString formattedPostalAddress() const;
 
    class Private;
    QSharedDataPointer<Private> d;
};
 
Q_DECLARE_OPERATORS_FOR_FLAGS(Address::Type)
 
/**
  Serializes the @p address object into the @p stream.
*/
KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Address &address);
 
/**
  Initializes the @p address object from the @p stream.
*/
KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Address &address);
}
 
Q_DECLARE_METATYPE(KContacts::Address)
 
#endif