1/*
2 This file is part of libkabc.
3 Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KABC_ADDRESS_H
22#define KABC_ADDRESS_H
23
24#include <QtCore/QSharedDataPointer>
25#include <QtCore/QString>
26
27#include "kabc_export.h"
28
29namespace KABC {
30
31/**
32 @brief
33 Postal address information.
34
35 This class represents information about a postal address.
36*/
37class KABC_EXPORT Address
38{
39 friend KABC_EXPORT QDataStream &operator<<( QDataStream &s, const Address &addr );
40 friend KABC_EXPORT QDataStream &operator>>( QDataStream &s, Address &addr );
41
42 public:
43 /**
44 List of addresses.
45 */
46 typedef QList<Address> List;
47
48 /**
49 Address types:
50 */
51 enum TypeFlag {
52 Dom = 1, /**< domestic */
53 Intl = 2, /**< international */
54 Postal = 4, /**< postal */
55 Parcel = 8, /**< parcel */
56 Home = 16, /**< home address */
57 Work = 32, /**< address at work */
58 Pref = 64 /**< preferred address */
59 };
60
61 Q_DECLARE_FLAGS( Type, TypeFlag )
62
63 /**
64 List of address types.
65 */
66 typedef QList<TypeFlag> TypeList;
67
68 /**
69 Creates an empty address.
70 */
71 Address();
72
73 /**
74 Creates an address of the given @p type.
75 */
76 Address( Type type );
77
78 /**
79 Copy constructor.
80 */
81 Address( const Address &address );
82
83 /**
84 Destroys the address.
85 */
86 ~Address();
87
88 /**
89 Equality operator.
90
91 @param addr the address to compare to
92 @return @c true if @c this and @p addr are equal, otherwise @c false
93 */
94 bool operator==( const Address &addr ) const;
95
96 /**
97 Not-equal operator.
98
99 @param addr the address to compare to
100 @return @c true if @c this and @p addr are not equal, otherwise @c false
101 */
102 bool operator!=( const Address &addr ) const;
103
104 /**
105 Assignment operator.
106
107 @param addr the address data to assign to @c this
108 @return a reference to @c this
109 */
110 Address &operator=( const Address &addr );
111
112 /**
113 Returns true, if the address is empty.
114 */
115 bool isEmpty() const;
116
117 /**
118 Clears all entries of the address.
119 */
120 void clear();
121
122 /**
123 Sets the unique @p identifier.
124 */
125 void setId( const QString &identifier );
126
127 /**
128 Returns the unique identifier.
129 */
130 QString id() const;
131
132 /**
133 Sets the type of address. See enum for definiton of types.
134
135 @param type type, can be a bitwise or of multiple types.
136 */
137 void setType( Type type );
138
139 /**
140 Returns the type of address. Can be a bitwise or of multiple types.
141 */
142 Type type() const;
143
144 /**
145 Returns a translated string of all types the address has.
146 */
147 QString typeLabel() const;
148
149 /**
150 Sets the post office box.
151 */
152 void setPostOfficeBox( const QString &postOfficeBox );
153
154 /**
155 Returns the post office box.
156 */
157 QString postOfficeBox() const;
158
159 /**
160 Returns the translated label for post office box field.
161 */
162 static QString postOfficeBoxLabel();
163
164 /**
165 Sets the @p extended address information.
166 */
167 void setExtended( const QString &extended );
168
169 /**
170 Returns the extended address information.
171 */
172 QString extended() const;
173
174 /**
175 Returns the translated label for extended field.
176 */
177 static QString extendedLabel();
178
179 /**
180 Sets the @p street (including house number).
181 */
182 void setStreet( const QString &street );
183
184 /**
185 Returns the street.
186 */
187 QString street() const;
188
189 /**
190 Returns the translated label for street field.
191 */
192 static QString streetLabel();
193
194 /**
195 Sets the @p locality, e.g. city.
196
197 @param locality the locality of the address, e.g. city
198 */
199 void setLocality( const QString &locality );
200
201 /**
202 Returns the locality.
203 */
204 QString locality() const;
205
206 /**
207 Returns the translated label for locality field.
208 */
209 static QString localityLabel();
210
211 /**
212 Sets the @p region, e.g. state.
213
214 @param region the region the address falls into, e.g. state
215 */
216 void setRegion( const QString &region );
217
218 /**
219 Returns the region.
220 */
221 QString region() const;
222
223 /**
224 Returns the translated label for region field.
225 */
226 static QString regionLabel();
227
228 /**
229 Sets the postal @p code.
230 */
231 void setPostalCode( const QString &code );
232
233 /**
234 Returns the postal code.
235 */
236 QString postalCode() const;
237
238 /**
239 Returns the translated label for postal code field.
240 */
241 static QString postalCodeLabel();
242
243 /**
244 Sets the @p country.
245 */
246 void setCountry( const QString &country );
247
248 /**
249 Returns the country.
250 */
251 QString country() const;
252
253 /**
254 Returns the translated label for country field.
255 */
256 static QString countryLabel();
257
258 /**
259 Sets the delivery @p label. This is the literal text to be used as label.
260
261 @param label the string to use for delivery labels
262 */
263 void setLabel( const QString &label );
264
265 /**
266 Returns the delivery label.
267 */
268 QString label() const;
269
270 /**
271 Returns the translated label for delivery label field.
272 */
273 static QString labelLabel();
274
275 /**
276 Returns the list of available types.
277 */
278 static TypeList typeList();
279
280 /**
281 Returns the translated label for the given @p type.
282 */
283 static QString typeLabel( Type type );
284
285 /**
286 Returns a string representation of the address.
287 */
288 QString toString() const;
289
290 /**
291 Returns this address formatted according to the country-specific
292 address formatting rules. The formatting rules applied depend on
293 either the addresses {@link #country country} field, or (if the
294 latter is empty) on the system country setting. If companyName is
295 provided, an available business address format will be preferred.
296
297 @param realName the formatted name of the contact
298 @param orgaName the name of the organization or company
299 @return the formatted address (containing newline characters)
300 */
301 QString formattedAddress( const QString &realName = QString(),
302 const QString &orgaName = QString() ) const;
303
304 /**
305 Returns ISO code for a localized country name. Only localized country
306 names will be understood. This might be replaced by a KLocale method in
307 the future.
308 @param cname name of the country
309 @return two digit ISO code
310 */
311 static QString countryToISO( const QString &cname );
312
313 /**
314 Returns a localized country name for a ISO code.
315 This might be replaced by a KLocale method in the future.
316 @param ISOname two digit ISO code
317 @return localized name of the country
318 */
319 static QString ISOtoCountry( const QString &ISOname );
320
321 private:
322 class Private;
323 QSharedDataPointer<Private> d;
324};
325
326Q_DECLARE_OPERATORS_FOR_FLAGS( Address::Type )
327
328/**
329 Serializes the @p address object into the @p stream.
330*/
331KABC_EXPORT QDataStream &operator<<( QDataStream &stream, const Address &address );
332
333/**
334 Initializes the @p address object from the @p stream.
335*/
336KABC_EXPORT QDataStream &operator>>( QDataStream &stream, Address &address );
337
338}
339
340#endif
341