1/*
2 This file is part of the KContacts framework.
3 SPDX-FileCopyrightText: 2001 Cornelius Schumacher <schumacher@kde.org>
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 <QList>
16#include <QMetaType>
17#include <QSharedDataPointer>
18#include <QString>
19#include <QUrl>
20
21namespace KContacts
22{
23class Geo;
24
25/*!
26 * \qmlvaluetype address
27 * \inqmlmodule org.kde.contacts
28 * \nativetype KContacts::Address
29 * \brief Postal address information.
30 *
31 * This class represents information about a postal address.
32 */
33
34/*!
35 \class KContacts::Address
36 \inheaderfile KContacts/Address
37 \inmodule KContacts
38
39 \brief Postal address information.
40
41 This class represents information about a postal address.
42*/
43class KCONTACTS_EXPORT Address
44{
45 friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &s, const Address &addr);
46 friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &s, Address &addr);
47
48 Q_GADGET
49
50 /*!
51 * \qmlproperty string address::id
52 */
53
54 /*!
55 * \property KContacts::Address::id
56 */
57 Q_PROPERTY(QString id READ id WRITE setId)
58
59 /*!
60 * \qmlproperty bool address::isEmpty
61 */
62
63 /*!
64 * \property KContacts::Address::isEmpty
65 */
66 Q_PROPERTY(bool isEmpty READ isEmpty)
67
68 /*!
69 * \qmlproperty enumeration address::type
70 * \qmlenumeratorsfrom KContacts::Address::TypeFlag
71 */
72
73 /*!
74 * \property KContacts::Address::type
75 */
76 Q_PROPERTY(Type type READ type WRITE setType)
77
78 /*!
79 * \qmlproperty string address::typeLabel
80 */
81
82 /*!
83 * \property KContacts::Address::typeLabel
84 */
85 Q_PROPERTY(QString typeLabel READ typeLabel)
86
87 /*!
88 * \qmlproperty string address::postOfficeBox
89 */
90
91 /*!
92 * \property KContacts::Address::postOfficeBox
93 */
94 Q_PROPERTY(QString postOfficeBox READ postOfficeBox WRITE setPostOfficeBox)
95
96 /*!
97 * \qmlproperty string address::extended
98 */
99
100 /*!
101 * \property KContacts::Address::extended
102 */
103 Q_PROPERTY(QString extended READ extended WRITE setExtended)
104
105 /*!
106 * \qmlproperty string address::street
107 */
108
109 /*!
110 * \property KContacts::Address::street
111 */
112 Q_PROPERTY(QString street READ street WRITE setStreet)
113
114 /*!
115 * \qmlproperty string address::locality
116 */
117
118 /*!
119 * \property KContacts::Address::locality
120 */
121 Q_PROPERTY(QString locality READ locality WRITE setLocality)
122
123 /*!
124 * \qmlproperty string address::region
125 */
126
127 /*!
128 * \property KContacts::Address::region
129 */
130 Q_PROPERTY(QString region READ region WRITE setRegion)
131
132 /*!
133 * \qmlproperty string address::postalCode
134 */
135
136 /*!
137 * \property KContacts::Address::postalCode
138 */
139 Q_PROPERTY(QString postalCode READ postalCode WRITE setPostalCode)
140
141 /*!
142 * \qmlproperty string address::country
143 */
144
145 /*!
146 * \property KContacts::Address::country
147 */
148 Q_PROPERTY(QString country READ country WRITE setCountry)
149
150 /*!
151 * \qmlproperty string address::label
152 */
153
154 /*!
155 * \property KContacts::Address::label
156 */
157 Q_PROPERTY(QString label READ label WRITE setLabel)
158
159 /*!
160 * \qmlproperty geo address::geo
161 */
162
163 /*!
164 * \property KContacts::Address::geo
165 */
166 Q_PROPERTY(KContacts::Geo geo READ geo WRITE setGeo)
167
168 // TODO KF6: ideally this would be deprecated as it doesn't specify the formatting style
169 // we cannot do that yet though due to Grantlee themes needing this (which cannot call
170 // the invokable methods instead). The KF6::TextTemplate port might bring new options there,
171 // otherwise we can at least switch this from postal to the multi-line style for KF6
172
173 /*!
174 * \qmlproperty string address::formattedAddress
175 */
176
177 /*!
178 * \property KContacts::Address::formattedAddress
179 *
180 * Country-specific formatted address without an addressee using postal address style.
181 * This is the same as calling formatted(AddressFormatStyle::Postal) with empty arguments.
182 * \sa formatted()
183 * \since 5.12
184 */
185 Q_PROPERTY(QString formattedAddress READ formattedPostalAddress)
186
187 /*!
188 * \qmlproperty url address::geoUri
189 */
190
191 /*!
192 * \property KContacts::Address::geo
193 * geo: URI for this address.
194 * \sa Address::geoUri()
195 * \since 5.106
196 */
197 Q_PROPERTY(QUrl geoUri READ geoUri)
198
199public:
200 /*!
201 * \typedef KContacts::Address::List
202 * List of addresses.
203 */
204 typedef QList<Address> List;
205
206 /*!
207 Address types:
208 \value Dom domestic
209 \value Intl international
210 \value Postal postal
211 \value Parcel parcel
212 \value Home home address
213 \value Work address at work
214 \value Pref preferred address
215 */
216 enum TypeFlag {
217 Dom = 1,
218 Intl = 2,
219 Postal = 4,
220 Parcel = 8,
221 Home = 16,
222 Work = 32,
223 Pref = 64,
224 };
225
226 Q_DECLARE_FLAGS(Type, TypeFlag)
227 Q_FLAG(Type)
228
229 /*!
230 * \typedef KContacts::Address::TypeList
231 * List of address types.
232 */
233 typedef QList<TypeFlag> TypeList;
234
235 /*!
236 Creates an empty address.
237 */
238 Address();
239
240 /*!
241 Creates an address of the given \a type.
242 */
243 Address(Type type);
244
245 /*!
246 Copy constructor.
247 */
248 Address(const Address &address);
249
250 /*!
251 Destroys the address.
252 */
253 ~Address();
254
255 /*!
256 Equality operator.
257
258 \a other the address to compare to
259
260 Returns \c true if \c this and \a other are equal, otherwise \c false
261 */
262 Q_REQUIRED_RESULT bool operator==(const Address &other) const;
263
264 /*!
265 Not-equal operator.
266
267 \a other the address to compare to
268
269 Returns \c true if \c this and \a other are not equal, otherwise \c false
270 */
271 Q_REQUIRED_RESULT bool operator!=(const Address &other) const;
272
273 /*!
274 Assignment operator.
275
276 \a other the address data to assign to \c this
277 Returns a reference to \c this
278 */
279 Address &operator=(const Address &other);
280
281 /*!
282 Returns \c true, if the address is empty.
283 */
284 Q_REQUIRED_RESULT bool isEmpty() const;
285
286 /*!
287 Clears all entries of the address.
288 */
289 void clear();
290
291 /*!
292 Sets the unique \a identifier.
293 */
294 void setId(const QString &identifier);
295
296 /*!
297 Returns the unique identifier.
298 */
299 Q_REQUIRED_RESULT QString id() const;
300
301 /*!
302 Sets the type of address. See enum for definition of types.
303
304 \a type type, can be a bitwise or of multiple types.
305 */
306 void setType(Type type);
307
308 /*!
309 Returns the type of address. Can be a bitwise or of multiple types.
310 */
311 Q_REQUIRED_RESULT Type type() const;
312
313 /*!
314 Returns a translated string of all types the address has.
315 */
316 Q_REQUIRED_RESULT QString typeLabel() const;
317
318 /*!
319 Sets the post office box.
320 */
321 void setPostOfficeBox(const QString &postOfficeBox);
322
323 /*!
324 Returns the post office box.
325 */
326 Q_REQUIRED_RESULT QString postOfficeBox() const;
327
328 /*!
329 Returns the translated label for post office box field.
330 */
331 static QString postOfficeBoxLabel();
332
333 /*!
334 Sets the \a extended address information.
335 */
336 void setExtended(const QString &extended);
337
338 /*!
339 Returns the extended address information.
340 */
341 Q_REQUIRED_RESULT QString extended() const;
342
343 /*!
344 Returns the translated label for extended field.
345 */
346 static QString extendedLabel();
347
348 /*!
349 Sets the \a street (including house number).
350 */
351 void setStreet(const QString &street);
352
353 /*!
354 Returns the street.
355 */
356 Q_REQUIRED_RESULT QString street() const;
357
358 /*!
359 Returns the translated label for street field.
360 */
361 static QString streetLabel();
362
363 /*!
364 Sets the \a locality, e.g. city.
365
366 \a locality the locality of the address, e.g. city
367 */
368 void setLocality(const QString &locality);
369
370 /*!
371 Returns the locality.
372 */
373 Q_REQUIRED_RESULT QString locality() const;
374
375 /*!
376 Returns the translated label for locality field.
377 */
378 static QString localityLabel();
379
380 /*!
381 Sets the \a region, e.g. state.
382
383 \a region the region the address falls into, e.g. state
384 */
385 void setRegion(const QString &region);
386
387 /*!
388 Returns the region.
389 */
390 Q_REQUIRED_RESULT QString region() const;
391
392 /*!
393 Returns the translated label for region field.
394 */
395 static QString regionLabel();
396
397 /*!
398 Sets the postal \a code.
399 */
400 void setPostalCode(const QString &code);
401
402 /*!
403 Returns the postal code.
404 */
405 Q_REQUIRED_RESULT QString postalCode() const;
406
407 /*!
408 Returns the translated label for postal code field.
409 */
410 static QString postalCodeLabel();
411
412 /*!
413 Sets the \a country.
414 */
415 void setCountry(const QString &country);
416
417 /*!
418 Returns the country.
419 */
420 Q_REQUIRED_RESULT QString country() const;
421
422 /*!
423 Returns the translated label for country field.
424 */
425 static QString countryLabel();
426
427 /*!
428 Sets the delivery \a label. This is the literal text to be used as label.
429
430 \a label the string to use for delivery labels
431 */
432 void setLabel(const QString &label);
433
434 /*!
435 Returns the delivery label.
436 */
437 Q_REQUIRED_RESULT QString label() const;
438
439 /*!
440 Returns the translated label for delivery label field.
441 */
442 static QString labelLabel();
443
444 /*!
445 Returns the list of available types.
446 */
447 static TypeList typeList();
448
449 /*!
450 Returns the translated label for the given \a type.
451 */
452 static QString typeLabel(Type type);
453
454 /*!
455 Returns a string representation of the address.
456 */
457 Q_REQUIRED_RESULT QString toString() const;
458
459 // note: cannot be called "formattedAddress" due to a collision
460 // with the property of that name in QML
461
462 /*!
463 * \qmlmethod QString address::formatted(enumeration style, string realName = "", string orgaName = "")
464 */
465
466 /*!
467 Returns this address formatted according to the country-specific
468 address formatting rules. The formatting rules applied depend on
469 either the addresses country field, or (if the
470 latter is empty) on the system country setting.
471
472 \a style the formatting style variant to use
473
474 \a realName the formatted name of the contact
475
476 \a orgaName the name of the organization or company
477
478 Returns the formatted address
479 \since 5.92
480 */
481 Q_REQUIRED_RESULT Q_INVOKABLE QString formatted(KContacts::AddressFormatStyle style,
482 const QString &realName = QString(),
483 const QString &orgaName = QString()) const;
484
485 /*!
486 */
487 static QString typeFlagLabel(TypeFlag type);
488
489 /*!
490 Set geographic position.
491 */
492 void setGeo(const Geo &geo);
493
494 /*!
495 Return geographic position.
496 */
497 Q_REQUIRED_RESULT Geo geo() const;
498
499 /*!
500 * Returns a geo: URI representing this address.
501 *
502 * This contains either the geographic coordinate if set, or the address as query term.
503 * This can be used to show the address in the default map view.
504 * \since 5.106
505 */
506 Q_REQUIRED_RESULT QUrl geoUri() const;
507
508private:
509 KCONTACTS_NO_EXPORT QString formattedPostalAddress() const;
510
511 class Private;
512 QSharedDataPointer<Private> d;
513};
514
515Q_DECLARE_OPERATORS_FOR_FLAGS(Address::Type)
516
517/*!
518 Serializes the \a address object into the \a stream.
519 \relates KContacts::Address
520*/
521KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Address &address);
522
523/*!
524 Initializes the \a address object from the \a stream.
525 \relates KContacts::Address
526*/
527KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Address &address);
528}
529
530#endif
531

source code of kcontacts/src/address.h