folks/name-details.vala

   1 /*
   2  * Copyright (C) 2011 Collabora Ltd.
   3  * Copyright (C) 2011 Philip Withnall
   4  *
   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.
   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
  13  * GNU Lesser General Public License for more details.
  14  *
  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/>.
  17  *
  18  * Authors:
  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>
  22  */
  23
  24 using GLib;
  25
  26 /**
  27  * Object for a full name split in its constituent parts (given name,
  28  * family name, etc.). This structure corresponds to the "N" field in
  29  * VCards.  The parts of the name are never null, an empty string
  30  * indicates that a property is not set.
  31  *
  32  * @since 0.3.5
  33  */
  34 public class Folks.StructuredName : Object
  35 {
  36   private string _family_name = "";
  37   /**
  38    * The family name.
  39    *
  40    * The family name (also known as surname or last name) of a contact.
  41    *
  42    * @since 0.3.5
  43    */
  44   public string family_name
  45     {
  46       get { return this._family_name; }
  47       construct set { this._family_name = value != null ? value : ""; }
  48     }
  49
  50   private string _given_name = "";
  51   /**
  52    * The given name.
  53    *
  54    * The family name (also known as first name) of a contact.
  55    *
  56    * @since 0.3.5
  57    */
  58   public string given_name
  59     {
  60       get { return this._given_name; }
  61       construct set { this._given_name = value != null ? value : ""; }
  62     }
  63
  64   private string _additional_names = "";
  65   /**
  66    * Additional names.
  67    *
  68    * The additional names of a contact, for instance the contact's
  69    * middle name.
  70    *
  71    * @since 0.3.5
  72    */
  73   public string additional_names
  74     {
  75       get { return this._additional_names; }
  76       construct set { this._additional_names = value != null ? value : ""; }
  77     }
  78
  79   private string _prefixes = "";
  80   /**
  81    * The prefixes of a name.
  82    *
  83    * The prefixes used in front of the name (for instance "Mr", "Mrs",
  84    * "Doctor" or honorific titles).
  85    *
  86    * @since 0.3.5
  87    */
  88   public string prefixes
  89     {
  90       get { return this._prefixes; }
  91       construct set { this._prefixes = value != null ? value : ""; }
  92     }
  93
  94   private string _suffixes = "";
  95   /**
  96    * The suffixes of a name.
  97    *
  98    * The suffixes used after a name (for instance "PhD" or "Junior").
  99    *
 100    * @since 0.3.5
 101    */
 102   public string suffixes
 103     {
 104       get { return this._suffixes; }
 105       construct set { this._suffixes = value != null ? value : ""; }
 106     }
 107
 108   /**
 109    * Create a StructuredName.
 110    *
 111    * You can pass `null` if a component is not set.
 112    *
 113    * @param family_name the family (last) name
 114    * @param given_name the given (first) name
 115    * @param additional_names additional names
 116    * @param prefixes prefixes of the name
 117    * @param suffixes suffixes of the name
 118    * @return a new StructuredName
 119    *
 120    * @since 0.3.5
 121    */
 122   public StructuredName (string? family_name, string? given_name,
 123       string? additional_names, string? prefixes, string? suffixes)
 124     {
 125       Object (family_name:      family_name,
 126               given_name:       given_name,
 127               additional_names: additional_names,
 128               prefixes:         prefixes,
 129               suffixes:         suffixes);
 130     }
 131
 132   /**
 133    * Create a StructuredName.
 134    *
 135    * Shorthand for the common case of just having the family and given
 136    * name of a contact. It's equivalent to calling
 137    * {@link StructuredName.StructuredName} and passing `null` for all
 138    * the other components.
 139    *
 140    * @param family_name the family (last) name
 141    * @param given_name the given (first) name
 142    * @return a new StructuredName
 143    *
 144    * @since 0.3.5
 145    */
 146   public StructuredName.simple (string? family_name, string? given_name)
 147     {
 148       Object (family_name: family_name,
 149               given_name:  given_name);
 150     }
 151
 152   /**
 153    * Whether none of the components is set.
 154    *
 155    * @return `true` if all the components are the empty string, `false`
 156    * otherwise.
 157    *
 158    * @since 0.3.5
 159    */
 160   public bool is_empty ()
 161     {
 162       return this._family_name      == "" &&
 163              this._given_name       == "" &&
 164              this._additional_names == "" &&
 165              this._prefixes         == "" &&
 166              this._suffixes         == "";
 167     }
 168
 169   /**
 170    * Whether two StructuredNames are the same.
 171    *
 172    * @param other the other structured name to compare with
 173    * @return `true` if all the components are the same, `false`
 174    * otherwise.
 175    *
 176    * @since 0.5.0
 177    */
 178   public bool equal (StructuredName other)
 179     {
 180       return this._family_name      == other.family_name &&
 181              this._given_name       == other.given_name &&
 182              this._additional_names == other.additional_names &&
 183              this._prefixes         == other.prefixes &&
 184              this._suffixes         == other.suffixes;
 185     }
 186
 187   /**
 188    * Formatted version of the structured name.
 189    *
 190    * @since 0.4.0
 191    */
 192   public string to_string ()
 193     {
 194       /* Translators: format for the formatted structured name.
 195        * Parameters (in order) are: prefixes (for the name), given name,
 196        * family name, additional names and (name) suffixes */
 197       var str = "%s, %s, %s, %s, %s";
 198       return str.printf (this.prefixes,
 199           this.given_name,
 200           this.family_name,
 201           this.additional_names,
 202           this.suffixes);
 203     }
 204 }
 205
 206 /**
 207  * Interface for classes which represent contacts with names, such as
 208  * {@link Persona} and {@link Individual}.
 209  *
 210  * @since 0.3.5
 211  */
 212 public interface Folks.NameDetails : Object
 213 {
 214   /**
 215    * The contact name split in its constituent parts.
 216    *
 217    * Note that most of the time the structured name is not set (i.e.
 218    * it's `null`) or just some of the components are set.
 219    * The components are immutable. To get notification of changes of
 220    * the structured name, you just have to connect to the `notify` signal
 221    * of this property.
 222    *
 223    * @since 0.3.5
 224    */
 225   public abstract StructuredName? structured_name { get; set; }
 226
 227   /**
 228    * Change the contact's structured name.
 229    *
 230    * It's preferred to call this rather than setting
 231    * {@link NameDetails.structured_name} directly, as this method gives error
 232    * notification and will only return once the name has been written to the
 233    * relevant backing store (or the operation's failed).
 234    *
 235    * @param name the structured name (`null` to unset it)
 236    * @throws PropertyError if setting the structured name failed
 237    * @since 0.6.2
 238    */
 239   public virtual async void change_structured_name (StructuredName? name)
 240       throws PropertyError
 241     {
 242       /* Default implementation. */
 243       throw new PropertyError.NOT_WRITEABLE (
 244           _("Structured name is not writeable on this contact."));
 245     }
 246
 247   /**
 248    * The full name of the contact.
 249    *
 250    * The full name is the name of the contact written in the way the contact
 251    * prefers. For instance for English names this is usually the given name
 252    * followed by the family name, but Chinese names are usually the family
 253    * name followed by the given name.
 254    * The full name could or could not contain additional names (like a
 255    * middle name), prefixes or suffixes.
 256    *
 257    * The full name must not be `null`: the empty string represents an unset full
 258    * name.
 259    *
 260    * @since 0.3.5
 261    */
 262   public abstract string full_name { get; set; }
 263
 264   /**
 265    * Change the contact's full name.
 266    *
 267    * It's preferred to call this rather than setting
 268    * {@link NameDetails.full_name} directly, as this method gives error
 269    * notification and will only return once the name has been written to the
 270    * relevant backing store (or the operation's failed).
 271    *
 272    * @param full_name the full name (empty string to unset it)
 273    * @throws PropertyError if setting the full name failed
 274    * @since 0.6.2
 275    */
 276   public virtual async void change_full_name (string full_name)
 277       throws PropertyError
 278     {
 279       /* Default implementation. */
 280       throw new PropertyError.NOT_WRITEABLE (
 281           _("Full name is not writeable on this contact."));
 282     }
 283
 284   /**
 285    * The nickname of the contact.
 286    *
 287    * The nickname is the name that the contact chose for himself. This is
 288    * different from {@link AliasDetails.alias} as aliases can be chosen by
 289    * the user and not by the contacts themselves.
 290    *
 291    * Consequently, setting the nickname only makes sense in the context of an
 292    * address book when updating the information a contact has specified about
 293    * themselves.
 294    *
 295    * The nickname must not be `null`: the empty string represents an unset
 296    * nickname.
 297    *
 298    * @since 0.3.5
 299    */
 300   public abstract string nickname { get; set; }
 301
 302   /**
 303    * Change the contact's nickname.
 304    *
 305    * It's preferred to call this rather than setting
 306    * {@link NameDetails.nickname} directly, as this method gives error
 307    * notification and will only return once the name has been written to the
 308    * relevant backing store (or the operation's failed).
 309    *
 310    * @param nickname the nickname (empty string to unset it)
 311    * @throws PropertyError if setting the nickname failed
 312    * @since 0.6.2
 313    */
 314   public virtual async void change_nickname (string nickname)
 315       throws PropertyError
 316     {
 317       /* Default implementation. */
 318       throw new PropertyError.NOT_WRITEABLE (
 319           _("Nickname is not writeable on this contact."));
 320     }
 321 }