KContacts

address.h
1 /*
2  This file is part of the KContacts framework.
3  SPDX-FileCopyrightText: 2001 Cornelius Schumacher <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KCONTACTS_ADDRESS_H
9 #define KCONTACTS_ADDRESS_H
10 
11 #include "geo.h"
12 #include "kcontacts_export.h"
13 #include "namespace.h"
14 
15 #include <QMetaType>
16 #include <QSharedDataPointer>
17 #include <QString>
18 #include <QUrl>
19 #include <QVector>
20 
21 namespace KContacts
22 {
23 class Geo;
24 /**
25  @brief
26  Postal address information.
27 
28  This class represents information about a postal address.
29 */
30 class KCONTACTS_EXPORT Address
31 {
32  friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &s, const Address &addr);
33  friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &s, Address &addr);
34 
35  Q_GADGET
36  Q_PROPERTY(QString id READ id WRITE setId)
37  Q_PROPERTY(bool isEmpty READ isEmpty)
38  Q_PROPERTY(Type type READ type WRITE setType)
39  Q_PROPERTY(QString typeLabel READ typeLabel)
40  Q_PROPERTY(QString postOfficeBox READ postOfficeBox WRITE setPostOfficeBox)
41  Q_PROPERTY(QString extended READ extended WRITE setExtended)
42  Q_PROPERTY(QString street READ street WRITE setStreet)
43  Q_PROPERTY(QString locality READ locality WRITE setLocality)
44  Q_PROPERTY(QString region READ region WRITE setRegion)
45  Q_PROPERTY(QString postalCode READ postalCode WRITE setPostalCode)
46  Q_PROPERTY(QString country READ country WRITE setCountry)
47  Q_PROPERTY(QString label READ label WRITE setLabel)
48  Q_PROPERTY(KContacts::Geo geo READ geo WRITE setGeo)
49 
50  // TODO KF6: ideally this would be deprecated as it doesn't specify the formatting style
51  // we cannot do that yet though due to Grantlee themes needing this (which cannot call
52  // the invokable methods instead). The KF6::TextTemplate port might bring new options there,
53  // otherwise we can at least switch this from postal to the multi-line style for KF6
54  /**
55  * Country-specific formatted address without an addressee using postal address style.
56  * This is the same as calling formatted(AddressFormatStyle::Postal) with empty arguments.
57  * @see formatted()
58  * @since 5.12
59  */
60  Q_PROPERTY(QString formattedAddress READ formattedPostalAddress)
61 
62  /** geo: URI for this address.
63  * @see Address::geoUri()
64  * @since 5.106
65  */
66  Q_PROPERTY(QUrl geoUri READ geoUri)
67 
68 public:
69  /**
70  List of addresses.
71  */
72  typedef QVector<Address> List;
73 
74  /**
75  Address types:
76  @see Type
77  */
78  enum TypeFlag {
79  Dom = 1, /**< domestic */
80  Intl = 2, /**< international */
81  Postal = 4, /**< postal */
82  Parcel = 8, /**< parcel */
83  Home = 16, /**< home address */
84  Work = 32, /**< address at work */
85  Pref = 64, /**< preferred address */
86  };
87 
88  /**
89  * Stores a combination of #TypeFlag values.
90  */
91  Q_DECLARE_FLAGS(Type, TypeFlag)
92  Q_FLAG(Type)
93 
94  /**
95  List of address types.
96  */
98 
99  /**
100  Creates an empty address.
101  */
102  Address();
103 
104  /**
105  Creates an address of the given @p type.
106  */
107  Address(Type type);
108 
109  /**
110  Copy constructor.
111  */
112  Address(const Address &address);
113 
114  /**
115  Destroys the address.
116  */
117  ~Address();
118 
119  /**
120  Equality operator.
121 
122  @param addr the address to compare to
123  @return @c true if @c this and @p addr are equal, otherwise @c false
124  */
125  Q_REQUIRED_RESULT bool operator==(const Address &other) const;
126 
127  /**
128  Not-equal operator.
129 
130  @param addr the address to compare to
131  @return @c true if @c this and @p addr are not equal, otherwise @c false
132  */
133  Q_REQUIRED_RESULT bool operator!=(const Address &other) const;
134 
135  /**
136  Assignment operator.
137 
138  @param addr the address data to assign to @c this
139  @return a reference to @c this
140  */
141  Address &operator=(const Address &other);
142 
143  /**
144  Returns true, if the address is empty.
145  */
146  Q_REQUIRED_RESULT bool isEmpty() const;
147 
148  /**
149  Clears all entries of the address.
150  */
151  void clear();
152 
153  /**
154  Sets the unique @p identifier.
155  */
156  void setId(const QString &identifier);
157 
158  /**
159  Returns the unique identifier.
160  */
161  Q_REQUIRED_RESULT QString id() const;
162 
163  /**
164  Sets the type of address. See enum for definition of types.
165 
166  @param type type, can be a bitwise or of multiple types.
167  */
168  void setType(Type type);
169 
170  /**
171  Returns the type of address. Can be a bitwise or of multiple types.
172  */
173  Q_REQUIRED_RESULT Type type() const;
174 
175  /**
176  Returns a translated string of all types the address has.
177  */
178  Q_REQUIRED_RESULT QString typeLabel() const;
179 
180  /**
181  Sets the post office box.
182  */
183  void setPostOfficeBox(const QString &postOfficeBox);
184 
185  /**
186  Returns the post office box.
187  */
188  Q_REQUIRED_RESULT QString postOfficeBox() const;
189 
190  /**
191  Returns the translated label for post office box field.
192  */
193  static QString postOfficeBoxLabel();
194 
195  /**
196  Sets the @p extended address information.
197  */
198  void setExtended(const QString &extended);
199 
200  /**
201  Returns the extended address information.
202  */
203  Q_REQUIRED_RESULT QString extended() const;
204 
205  /**
206  Returns the translated label for extended field.
207  */
208  static QString extendedLabel();
209 
210  /**
211  Sets the @p street (including house number).
212  */
213  void setStreet(const QString &street);
214 
215  /**
216  Returns the street.
217  */
218  Q_REQUIRED_RESULT QString street() const;
219 
220  /**
221  Returns the translated label for street field.
222  */
223  static QString streetLabel();
224 
225  /**
226  Sets the @p locality, e.g. city.
227 
228  @param locality the locality of the address, e.g. city
229  */
230  void setLocality(const QString &locality);
231 
232  /**
233  Returns the locality.
234  */
235  Q_REQUIRED_RESULT QString locality() const;
236 
237  /**
238  Returns the translated label for locality field.
239  */
240  static QString localityLabel();
241 
242  /**
243  Sets the @p region, e.g. state.
244 
245  @param region the region the address falls into, e.g. state
246  */
247  void setRegion(const QString &region);
248 
249  /**
250  Returns the region.
251  */
252  Q_REQUIRED_RESULT QString region() const;
253 
254  /**
255  Returns the translated label for region field.
256  */
257  static QString regionLabel();
258 
259  /**
260  Sets the postal @p code.
261  */
262  void setPostalCode(const QString &code);
263 
264  /**
265  Returns the postal code.
266  */
267  Q_REQUIRED_RESULT QString postalCode() const;
268 
269  /**
270  Returns the translated label for postal code field.
271  */
272  static QString postalCodeLabel();
273 
274  /**
275  Sets the @p country.
276  */
277  void setCountry(const QString &country);
278 
279  /**
280  Returns the country.
281  */
282  Q_REQUIRED_RESULT QString country() const;
283 
284  /**
285  Returns the translated label for country field.
286  */
287  static QString countryLabel();
288 
289  /**
290  Sets the delivery @p label. This is the literal text to be used as label.
291 
292  @param label the string to use for delivery labels
293  */
294  void setLabel(const QString &label);
295 
296  /**
297  Returns the delivery label.
298  */
299  Q_REQUIRED_RESULT QString label() const;
300 
301  /**
302  Returns the translated label for delivery label field.
303  */
304  static QString labelLabel();
305 
306  /**
307  Returns the list of available types.
308  */
309  static TypeList typeList();
310 
311  /**
312  Returns the translated label for the given @p type.
313  */
314  static QString typeLabel(Type type);
315 
316  /**
317  Returns a string representation of the address.
318  */
319  Q_REQUIRED_RESULT QString toString() const;
320 
321 #if KCONTACTS_ENABLE_DEPRECATED_SINCE(5, 92)
322  /**
323  Returns this address formatted according to the country-specific
324  postal address formatting rules. The formatting rules applied depend on
325  either the addresses {@link #country country} field, or (if the
326  latter is empty) on the system country setting. If companyName is
327  provided, an available business address format will be preferred.
328 
329  @param realName the formatted name of the contact
330  @param orgaName the name of the organization or company
331  @return the formatted address (containing newline characters)
332  @deprecated since 5.92, use formatted() instead, using AddressFormatStyle::Postal
333  to obtain the identical result.
334  */
335  Q_REQUIRED_RESULT
336  KCONTACTS_DEPRECATED_VERSION(5, 92, "Use KContacts::Address::formatted() instead")
337  QString formattedAddress(const QString &realName = QString(), const QString &orgaName = QString()) const;
338 #endif
339 
340  // note: cannot be called "formattedAddress" due to a collision
341  // with the property of that name in QML
342  /**
343  Returns this address formatted according to the country-specific
344  address formatting rules. The formatting rules applied depend on
345  either the addresses {@link #country country} field, or (if the
346  latter is empty) on the system country setting.
347 
348  @param style the formatting style variant to use
349  @param realName the formatted name of the contact
350  @param orgaName the name of the organization or company
351  @return the formatted address
352  @since 5.92
353  */
354  Q_REQUIRED_RESULT Q_INVOKABLE QString formatted(KContacts::AddressFormatStyle style,
355  const QString &realName = QString(),
356  const QString &orgaName = QString()) const;
357 
358 #if KCONTACTS_ENABLE_DEPRECATED_SINCE(5, 89)
359  /**
360  Returns ISO code for a localized country name. Only localized country
361  names will be understood.
362  @param cname name of the country
363  @return two digit ISO code, empty string if the country was not
364  recognized
365  @deprecated since 5.88, use KCountry::fromName() instead.
366  Note that this function returned the ISO code incorrectly in lower case,
367  while KCountry does not do that.
368  */
369  KCONTACTS_DEPRECATED_VERSION(5, 89, "Use KCountry::fromName()")
370  static QString countryToISO(const QString &cname);
371 #endif
372 
373 #if KCONTACTS_ENABLE_DEPRECATED_SINCE(5, 89)
374  /**
375  Returns a localized country name for a ISO code.
376  This might be replaced by a KLocale method in the future.
377  @param ISOname two digit ISO code
378  @return localized name of the country
379  @deprecated since 5.88, use KCountry::fromAlpha2() instead.
380  Note that this function returns @p ISOname if that is not a valid country code,
381  while KCountry will need an explicit check for that case.
382  */
383  KCONTACTS_DEPRECATED_VERSION(5, 89, "Use KCountry::fromAlpha2()")
384  static QString ISOtoCountry(const QString &ISOname);
385 #endif
386 
387  static QString typeFlagLabel(TypeFlag type);
388 
389  /**
390  Set geographic position.
391  */
392  void setGeo(const Geo &geo);
393 
394  /**
395  Return geographic position.
396  */
397  Q_REQUIRED_RESULT Geo geo() const;
398 
399  /**
400  * Returns a geo: URI representing this address.
401  * This contains either the geographic coordinate if set, or the address as query term.
402  * This can be used to show the address in the default map view.
403  * @since 5.106
404  */
405  Q_REQUIRED_RESULT QUrl geoUri() const;
406 
407 private:
408  KCONTACTS_NO_EXPORT QString formattedPostalAddress() const;
409 
410  class Private;
412 };
413 
414 Q_DECLARE_OPERATORS_FOR_FLAGS(Address::Type)
415 
416 /**
417  Serializes the @p address object into the @p stream.
418 */
419 KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Address &address);
420 
421 /**
422  Initializes the @p address object from the @p stream.
423 */
424 KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Address &address);
425 }
426 
427 Q_DECLARE_METATYPE(KContacts::Address)
428 
429 #endif
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
AddressFormatStyle
Address formatting styles.
Definition: namespace.h:25
KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &in, const KCalendarCore::Alarm::Ptr &)
Postal address information.
Definition: address.h:30
Geographic position.
Definition: geo.h:24
TypeFlag
Address types:
Definition: address.h:78
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Dec 10 2023 03:49:09 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.