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 @brief
26 Postal address information.
27
28 This class represents information about a postal address.
29*/
30class 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
68public:
69 /**
70 List of addresses.
71 */
72 typedef QList<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 */
97 typedef QList<TypeFlag> TypeList;
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 // note: cannot be called "formattedAddress" due to a collision
322 // with the property of that name in QML
323 /**
324 Returns this address formatted according to the country-specific
325 address formatting rules. The formatting rules applied depend on
326 either the addresses {@link #country country} field, or (if the
327 latter is empty) on the system country setting.
328
329 @param style the formatting style variant to use
330 @param realName the formatted name of the contact
331 @param orgaName the name of the organization or company
332 @return the formatted address
333 @since 5.92
334 */
335 Q_REQUIRED_RESULT Q_INVOKABLE QString formatted(KContacts::AddressFormatStyle style,
336 const QString &realName = QString(),
337 const QString &orgaName = QString()) const;
338
339 static QString typeFlagLabel(TypeFlag type);
340
341 /**
342 Set geographic position.
343 */
344 void setGeo(const Geo &geo);
345
346 /**
347 Return geographic position.
348 */
349 Q_REQUIRED_RESULT Geo geo() const;
350
351 /**
352 * Returns a geo: URI representing this address.
353 * This contains either the geographic coordinate if set, or the address as query term.
354 * This can be used to show the address in the default map view.
355 * @since 5.106
356 */
357 Q_REQUIRED_RESULT QUrl geoUri() const;
358
359private:
360 KCONTACTS_NO_EXPORT QString formattedPostalAddress() const;
361
362 class Private;
363 QSharedDataPointer<Private> d;
364};
365
366Q_DECLARE_OPERATORS_FOR_FLAGS(Address::Type)
367
368/**
369 Serializes the @p address object into the @p stream.
370*/
371KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Address &address);
372
373/**
374 Initializes the @p address object from the @p stream.
375*/
376KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Address &address);
377}
378
379#endif
380

source code of kcontacts/src/address.h