2 * Copyright (C) 2010 Collabora Ltd.
3 * Copyright (C) 2011 Philip Withnall
5 * This library is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU Lesser General Public License as published by
7 * the Free Software Foundation, either version 2.1 of the License, or
8 * (at your option) any later version.
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
13 * GNU Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General Public License
16 * along with this library. If not, see <http://www.gnu.org/licenses/>.
19 * Marco Barisione <marco.barisione@collabora.co.uk>
20 * Raul Gutierrez Segales <raul.gutierrez.segales@collabora.co.uk>
21 * Philip Withnall <philip@tecnocode.co.uk>
28 * Object representing a postal mail address.
29 * The components of the address are never null, an empty string
30 * indicates that a property is not set.
32 public class Folks.PostalAddress : Object
34 private string _po_box = "";
38 * The PO Box (also known as Postal office box or Postal box).
42 get { return _po_box; }
43 construct set { _po_box = (value != null ? value : ""); }
46 private string _extension = "";
48 * The address extension.
50 * Any additional part of the address, for instance a flat number.
52 public string extension
54 get { return _extension; }
55 construct set { _extension = (value != null ? value : ""); }
58 private string _street = "";
60 * The street name and number.
62 * The street name including the optional building number.
63 * The number can be before or after the street name based on the
64 * language and country.
68 get { return _street; }
69 construct set { _street = (value != null ? value : ""); }
72 private string _locality = "";
76 * The locality, for instance the city name.
78 public string locality
80 get { return _locality; }
81 construct set { _locality = (value != null ? value : ""); }
84 private string _region = "";
88 * The region, for instance the name of the state or province.
92 get { return _region; }
93 construct set { _region = (value != null ? value : ""); }
96 private string _postal_code = "";
100 * The postal code (also known as post code, postcode or ZIP code).
102 public string postal_code
104 get { return _postal_code; }
105 construct set { _postal_code = (value != null ? value : ""); }
108 private string _country = "";
112 * The name of the country.
114 public string country
116 get { return _country; }
117 construct set { _country = (value != null ? value : ""); }
120 private string _address_format = "";
122 * The address format.
124 * The two letter country code that determines the format or exact
125 * meaning of the other fields.
127 public string address_format
129 get { return _address_format; }
130 construct set { _address_format = (value != null ? value : ""); }
133 private string _uid = "";
135 * The UID of the Postal Address (if any).
137 [Deprecated (since = "0.6.5", replacement = "AbstractFieldDetails.id")]
141 construct set { _uid = (value != null ? value : ""); }
145 * Create a PostalAddress.
147 * You can pass `null` if a component is not set.
149 * @param po_box the PO Box
150 * @param extension the address extension
151 * @param street the street name and number
152 * @param locality the locality (city, town or village) name
153 * @param region the region (state or province) name
154 * @param postal_code the postal code
155 * @param country the country name
156 * @param address_format the address format
157 * @param types set of types for the address (such as "personal" or "work")
158 * @param uid external UID for the address instance
161 public PostalAddress (string? po_box, string? extension, string? street,
162 string? locality, string? region, string? postal_code, string? country,
163 string? address_format, string? uid)
165 Object (po_box: po_box,
166 extension: extension,
170 postal_code: postal_code,
172 address_format: address_format,
177 * Whether none of the components is set.
179 * @return `true` if all the components are the empty string, `false`
184 public bool is_empty ()
186 return this.po_box == "" &&
187 this.extension == "" &&
189 this.locality == "" &&
191 this.postal_code == "" &&
192 this.country == "" &&
193 this.address_format == "";
197 * Compare if two postal addresses are equal. Addresses are equal if all their
198 * components are equal (where `null` compares equal only with `null`) and
199 * they have the same set of types (or both have no types).
201 * This does not factor in the {@link PostalAddress.uid}.
203 * @param with another postal address to compare with
204 * @return `true` if the addresses are equal, `false` otherwise
206 public bool equal (PostalAddress with)
208 if (this.po_box != with.po_box ||
209 this.extension != with.extension ||
210 this.street != with.street ||
211 this.locality != with.locality ||
212 this.region != with.region ||
213 this.postal_code != with.postal_code ||
214 this.country != with.country ||
215 this.address_format != with.address_format)
222 * Get a formatted version of the address. The format is localised, and by
223 * default is comma-separated.
225 * @return a formatted address.
229 public string to_string ()
231 var str = _("%s, %s, %s, %s, %s, %s, %s");
232 return str.printf (this.po_box, this.extension, this.street,
233 this.locality, this.region, this.postal_code, this.country);
238 * Object representing a PostalAddress value that can have some parameters
239 * associated with it.
241 * See {@link Folks.AbstractFieldDetails} for details on common parameter names
246 public class Folks.PostalAddressFieldDetails :
247 AbstractFieldDetails<PostalAddress>
253 public override string id
255 get { return this._id; }
258 this._id = (value != null ? value : "");
260 /* Keep the PostalAddress.uid sync'd from our id */
261 if (this._id != this.value.uid)
262 this.value.uid = this._id;
267 * Create a new PostalAddressFieldDetails.
269 * @param value the value of the field, a non-empty {@link PostalAddress}
270 * @param parameters initial parameters. See
271 * {@link AbstractFieldDetails.parameters}. A `null` value is equivalent to an
272 * empty map of parameters.
275 * @return a new PostalAddressFieldDetails
279 public PostalAddressFieldDetails (PostalAddress value,
280 MultiMap<string, string>? parameters = null)
282 if (value.is_empty ())
284 warning ("Empty postal address passed to PostalAddressFieldDetails.");
287 /* We keep id and value.uid synchronised in both directions. */
288 Object (value: value,
289 parameters: parameters,
295 /* Keep the PostalAddress.uid sync'd to our id */
296 this.value.notify["uid"].connect ((s, p) =>
298 if (this.id != this.value.uid)
299 this.id = this.value.uid;
308 public override bool equal (AbstractFieldDetails<PostalAddress> that)
310 if (!base.parameters_equal (that))
313 /* This is fairly-dumb but smart matching is an i10n nightmare. */
314 return this.value.to_string () == that.value.to_string ();
322 public override uint hash ()
324 /* This is basic because smart matching is very hard (see equal()). */
325 return str_hash (this.value.to_string ());
330 * Interface for classes that can provide postal addresses, such as
331 * {@link Persona} and {@link Individual}.
333 public interface Folks.PostalAddressDetails : Object
336 * The postal addresses of the contact.
338 * A list of postal addresses associated to the contact.
342 public abstract Set<PostalAddressFieldDetails> postal_addresses { get; set; }
345 * Change the contact's postal addresses.
347 * It's preferred to call this rather than setting
348 * {@link PostalAddressDetails.postal_addresses} directly, as this method
349 * gives error notification and will only return once the addresses have been
350 * written to the relevant backing store (or the operation's failed).
352 * @param postal_addresses the set of postal addresses
353 * @throws PropertyError if setting the addresses failed
356 public virtual async void change_postal_addresses (
357 Set<PostalAddressFieldDetails> postal_addresses) throws PropertyError
359 /* Default implementation. */
360 throw new PropertyError.NOT_WRITEABLE (
361 _("Postal addresses are not writeable on this contact."));