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 | |
29 | namespace KABC { |
30 | |
31 | /** |
32 | @brief |
33 | Postal address information. |
34 | |
35 | This class represents information about a postal address. |
36 | */ |
37 | class 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 ®ion ); |
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 | |
326 | Q_DECLARE_OPERATORS_FOR_FLAGS( Address::Type ) |
327 | |
328 | /** |
329 | Serializes the @p address object into the @p stream. |
330 | */ |
331 | KABC_EXPORT QDataStream &operator<<( QDataStream &stream, const Address &address ); |
332 | |
333 | /** |
334 | Initializes the @p address object from the @p stream. |
335 | */ |
336 | KABC_EXPORT QDataStream &operator>>( QDataStream &stream, Address &address ); |
337 | |
338 | } |
339 | |
340 | #endif |
341 | |