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 
14 #include <QMetaType>
15 #include <QSharedDataPointer>
16 #include <QString>
17 #include <QVector>
18 
19 namespace KContacts
20 {
21 class Geo;
22 /**
23  @brief
24  Postal address information.
25 
26  This class represents information about a postal address.
27 */
28 class KCONTACTS_EXPORT Address
29 {
30  friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &s, const Address &addr);
31  friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &s, Address &addr);
32 
33  Q_GADGET
34  Q_PROPERTY(QString id READ id WRITE setId)
35  Q_PROPERTY(bool isEmpty READ isEmpty)
36  Q_PROPERTY(Type type READ type WRITE setType)
37  Q_PROPERTY(QString typeLabel READ typeLabel)
38  Q_PROPERTY(QString postOfficeBox READ postOfficeBox WRITE setPostOfficeBox)
39  Q_PROPERTY(QString extended READ extended WRITE setExtended)
40  Q_PROPERTY(QString street READ street WRITE setStreet)
41  Q_PROPERTY(QString locality READ locality WRITE setLocality)
42  Q_PROPERTY(QString region READ region WRITE setRegion)
43  Q_PROPERTY(QString postalCode READ postalCode WRITE setPostalCode)
44  Q_PROPERTY(QString country READ country WRITE setCountry)
45  Q_PROPERTY(QString label READ label WRITE setLabel)
46  Q_PROPERTY(KContacts::Geo geo READ geo WRITE setGeo)
47  /**
48  * Country-specific formatted address without an addressee.
49  * This is the same as calling formattedAddress() with empty arguments.
50  * @see formattedAddress()
51  * @since 5.12
52  */
53  Q_PROPERTY(QString formattedAddress READ formattedAddress)
54 
55 public:
56  /**
57  List of addresses.
58  */
59  typedef QVector<Address> List;
60 
61  /**
62  Address types:
63  @see Type
64  */
65  enum TypeFlag {
66  Dom = 1, /**< domestic */
67  Intl = 2, /**< international */
68  Postal = 4, /**< postal */
69  Parcel = 8, /**< parcel */
70  Home = 16, /**< home address */
71  Work = 32, /**< address at work */
72  Pref = 64, /**< preferred address */
73  };
74 
75  /**
76  * Stores a combination of #TypeFlag values.
77  */
78  Q_DECLARE_FLAGS(Type, TypeFlag)
79  Q_FLAG(Type)
80 
81  /**
82  List of address types.
83  */
85 
86  /**
87  Creates an empty address.
88  */
89  Address();
90 
91  /**
92  Creates an address of the given @p type.
93  */
94  Address(Type type);
95 
96  /**
97  Copy constructor.
98  */
99  Address(const Address &address);
100 
101  /**
102  Destroys the address.
103  */
104  ~Address();
105 
106  /**
107  Equality operator.
108 
109  @param addr the address to compare to
110  @return @c true if @c this and @p addr are equal, otherwise @c false
111  */
112  Q_REQUIRED_RESULT bool operator==(const Address &other) const;
113 
114  /**
115  Not-equal operator.
116 
117  @param addr the address to compare to
118  @return @c true if @c this and @p addr are not equal, otherwise @c false
119  */
120  Q_REQUIRED_RESULT bool operator!=(const Address &other) const;
121 
122  /**
123  Assignment operator.
124 
125  @param addr the address data to assign to @c this
126  @return a reference to @c this
127  */
128  Address &operator=(const Address &other);
129 
130  /**
131  Returns true, if the address is empty.
132  */
133  Q_REQUIRED_RESULT bool isEmpty() const;
134 
135  /**
136  Clears all entries of the address.
137  */
138  void clear();
139 
140  /**
141  Sets the unique @p identifier.
142  */
143  void setId(const QString &identifier);
144 
145  /**
146  Returns the unique identifier.
147  */
148  Q_REQUIRED_RESULT QString id() const;
149 
150  /**
151  Sets the type of address. See enum for definiton of types.
152 
153  @param type type, can be a bitwise or of multiple types.
154  */
155  void setType(Type type);
156 
157  /**
158  Returns the type of address. Can be a bitwise or of multiple types.
159  */
160  Q_REQUIRED_RESULT Type type() const;
161 
162  /**
163  Returns a translated string of all types the address has.
164  */
165  Q_REQUIRED_RESULT QString typeLabel() const;
166 
167  /**
168  Sets the post office box.
169  */
170  void setPostOfficeBox(const QString &postOfficeBox);
171 
172  /**
173  Returns the post office box.
174  */
175  Q_REQUIRED_RESULT QString postOfficeBox() const;
176 
177  /**
178  Returns the translated label for post office box field.
179  */
180  static QString postOfficeBoxLabel();
181 
182  /**
183  Sets the @p extended address information.
184  */
185  void setExtended(const QString &extended);
186 
187  /**
188  Returns the extended address information.
189  */
190  Q_REQUIRED_RESULT QString extended() const;
191 
192  /**
193  Returns the translated label for extended field.
194  */
195  static QString extendedLabel();
196 
197  /**
198  Sets the @p street (including house number).
199  */
200  void setStreet(const QString &street);
201 
202  /**
203  Returns the street.
204  */
205  Q_REQUIRED_RESULT QString street() const;
206 
207  /**
208  Returns the translated label for street field.
209  */
210  static QString streetLabel();
211 
212  /**
213  Sets the @p locality, e.g. city.
214 
215  @param locality the locality of the address, e.g. city
216  */
217  void setLocality(const QString &locality);
218 
219  /**
220  Returns the locality.
221  */
222  Q_REQUIRED_RESULT QString locality() const;
223 
224  /**
225  Returns the translated label for locality field.
226  */
227  static QString localityLabel();
228 
229  /**
230  Sets the @p region, e.g. state.
231 
232  @param region the region the address falls into, e.g. state
233  */
234  void setRegion(const QString &region);
235 
236  /**
237  Returns the region.
238  */
239  Q_REQUIRED_RESULT QString region() const;
240 
241  /**
242  Returns the translated label for region field.
243  */
244  static QString regionLabel();
245 
246  /**
247  Sets the postal @p code.
248  */
249  void setPostalCode(const QString &code);
250 
251  /**
252  Returns the postal code.
253  */
254  Q_REQUIRED_RESULT QString postalCode() const;
255 
256  /**
257  Returns the translated label for postal code field.
258  */
259  static QString postalCodeLabel();
260 
261  /**
262  Sets the @p country.
263  */
264  void setCountry(const QString &country);
265 
266  /**
267  Returns the country.
268  */
269  Q_REQUIRED_RESULT QString country() const;
270 
271  /**
272  Returns the translated label for country field.
273  */
274  static QString countryLabel();
275 
276  /**
277  Sets the delivery @p label. This is the literal text to be used as label.
278 
279  @param label the string to use for delivery labels
280  */
281  void setLabel(const QString &label);
282 
283  /**
284  Returns the delivery label.
285  */
286  Q_REQUIRED_RESULT QString label() const;
287 
288  /**
289  Returns the translated label for delivery label field.
290  */
291  static QString labelLabel();
292 
293  /**
294  Returns the list of available types.
295  */
296  static TypeList typeList();
297 
298  /**
299  Returns the translated label for the given @p type.
300  */
301  static QString typeLabel(Type type);
302 
303  /**
304  Returns a string representation of the address.
305  */
306  Q_REQUIRED_RESULT QString toString() const;
307 
308  /**
309  Returns this address formatted according to the country-specific
310  address formatting rules. The formatting rules applied depend on
311  either the addresses {@link #country country} field, or (if the
312  latter is empty) on the system country setting. If companyName is
313  provided, an available business address format will be preferred.
314 
315  @param realName the formatted name of the contact
316  @param orgaName the name of the organization or company
317  @return the formatted address (containing newline characters)
318  */
319  Q_REQUIRED_RESULT QString formattedAddress(const QString &realName = QString(), const QString &orgaName = QString()) const;
320 
321  /**
322  Returns ISO code for a localized country name. Only localized country
323  names will be understood.
324  @param cname name of the country
325  @return two digit ISO code, empty string if the country was not
326  recognized
327  */
328  static QString countryToISO(const QString &cname);
329 
330  /**
331  Returns a localized country name for a ISO code.
332  This might be replaced by a KLocale method in the future.
333  @param ISOname two digit ISO code
334  @return localized name of the country
335  */
336  static QString ISOtoCountry(const QString &ISOname);
337 
338  static QString typeFlagLabel(TypeFlag type);
339 
340  /**
341  Set geographic position.
342  */
343  void setGeo(const Geo &geo);
344 
345  /**
346  Return geographic position.
347  */
348  Q_REQUIRED_RESULT Geo geo() const;
349 
350 private:
351  class Private;
352  QSharedDataPointer<Private> d;
353 };
354 
355 Q_DECLARE_OPERATORS_FOR_FLAGS(Address::Type)
356 
357 /**
358  Serializes the @p address object into the @p stream.
359 */
360 KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Address &address);
361 
362 /**
363  Initializes the @p address object from the @p stream.
364 */
365 KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Address &address);
366 }
367 
368 Q_DECLARE_METATYPE(KContacts::Address)
369 
370 #endif
QDataStream & operator>>(QDataStream &in, KDateTime::Spec &spec)
Geographic position.
Definition: geo.h:24
QDataStream & operator<<(QDataStream &out, const KDateTime::Spec &spec)
Postal address information.
Definition: address.h:28
TypeFlag
Address types:
Definition: address.h:65
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Wed Apr 14 2021 22:54:52 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.