folks/name-details.vala

   1 /*
   2  * Copyright (C) 2011 Collabora Ltd.
   3  *
   4  * This library is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published by
   6  * the Free Software Foundation, either version 2.1 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Authors:
  18  *       Marco Barisione <marco.barisione@collabora.co.uk>
  19  *       Raul Gutierrez Segales <raul.gutierrez.segales@collabora.co.uk>
  20  */
  21
  22 using GLib;
  23
  24 /**
  25  * Object for a full name split in its constituent parts (given name,
  26  * family name, etc.). This structure corresponds to the "N" field in
  27  * VCards.  The parts of the name are never null, an empty string
  28  * indicates that a property is not set.
  29  *
  30  * @since 0.3.5
  31  */
  32 public class Folks.StructuredName : Object
  33 {
  34   private string _family_name = "";
  35   /**
  36    * The family name.
  37    *
  38    * The family name (also known as surname or last name) of a contact.
  39    *
  40    * @since 0.3.5
  41    */
  42   public string family_name
  43     {
  44       get { return this._family_name; }
  45       construct set { this._family_name = value != null ? value : ""; }
  46     }
  47
  48   private string _given_name = "";
  49   /**
  50    * The given name.
  51    *
  52    * The family name (also known as first name) of a contact.
  53    *
  54    * @since 0.3.5
  55    */
  56   public string given_name
  57     {
  58       get { return this._given_name; }
  59       construct set { this._given_name = value != null ? value : ""; }
  60     }
  61
  62   private string _additional_names = "";
  63   /**
  64    * Additional names.
  65    *
  66    * The additional names of a contact, for instance the contact's
  67    * middle name.
  68    *
  69    * @since 0.3.5
  70    */
  71   public string additional_names
  72     {
  73       get { return this._additional_names; }
  74       construct set { this._additional_names = value != null ? value : ""; }
  75     }
  76
  77   private string _prefixes = "";
  78   /**
  79    * The prefixes of a name.
  80    *
  81    * The prefixes used in front of the name (for instance "Mr", "Mrs",
  82    * "Doctor" or honorific titles).
  83    *
  84    * @since 0.3.5
  85    */
  86   public string prefixes
  87     {
  88       get { return this._prefixes; }
  89       construct set { this._prefixes = value != null ? value : ""; }
  90     }
  91
  92   private string _suffixes = "";
  93   /**
  94    * The suffixes of a name.
  95    *
  96    * The suffixes used after a name (for instance "PhD" or "Junior").
  97    *
  98    * @since 0.3.5
  99    */
 100   public string suffixes
 101     {
 102       get { return this._suffixes; }
 103       construct set { this._suffixes = value != null ? value : ""; }
 104     }
 105
 106   /**
 107    * Create a StructuredName.
 108    *
 109    * You can pass `null` if a component is not set.
 110    *
 111    * @param family_name the family (last) name
 112    * @param given_name the given (first) name
 113    * @param additional_names additional names
 114    * @param prefixes prefixes of the name
 115    * @param suffixes suffixes of the name
 116    * @return a new StructuredName
 117    *
 118    * @since 0.3.5
 119    */
 120   public StructuredName (string? family_name, string? given_name,
 121       string? additional_names, string? prefixes, string? suffixes)
 122     {
 123       Object (family_name:      family_name,
 124               given_name:       given_name,
 125               additional_names: additional_names,
 126               prefixes:         prefixes,
 127               suffixes:         suffixes);
 128     }
 129
 130   /**
 131    * Create a StructuredName.
 132    *
 133    * Shorthand for the common case of just having the family and given
 134    * name of a contact. It's equivalent to calling
 135    * {@link StructuredName.StructuredName} and passing `null` for all
 136    * the other components.
 137    *
 138    * @param family_name the family (last) name
 139    * @param given_name the given (first) name
 140    * @return a new StructuredName
 141    *
 142    * @since 0.3.5
 143    */
 144   public StructuredName.simple (string? family_name, string? given_name)
 145     {
 146       Object (family_name: family_name,
 147               given_name:  given_name);
 148     }
 149
 150   /**
 151    * Whether none of the components is set.
 152    *
 153    * @return `true` if all the components are the empty string, `false`
 154    * otherwise.
 155    *
 156    * @since 0.3.5
 157    */
 158   public bool is_empty ()
 159     {
 160       return this._family_name      == "" &&
 161              this._given_name       == "" &&
 162              this._additional_names == "" &&
 163              this._prefixes         == "" &&
 164              this._suffixes         == "";
 165     }
 166
 167   /**
 168    * Whether two StructuredNames are the same.
 169    *
 170    * @param other the other structured name to compare with
 171    * @return `true` if all the components are the same, `false`
 172    * otherwise.
 173    *
 174    * @since 0.5.0
 175    */
 176   public bool equal (StructuredName other)
 177     {
 178       return this._family_name      == other.family_name &&
 179              this._given_name       == other.given_name &&
 180              this._additional_names == other.additional_names &&
 181              this._prefixes         == other.prefixes &&
 182              this._suffixes         == other.suffixes;
 183     }
 184
 185   /**
 186    * Formatted version of the structured name.
 187    *
 188    * @since 0.4.0
 189    */
 190   public string to_string ()
 191     {
 192       /* Translators: format for the formatted structured name.
 193        * Parameters (in order) are: prefixes (for the name), given name,
 194        * family name, additional names and (name) suffixes */
 195       var str = "%s, %s, %s, %s, %s";
 196       return str.printf (this.prefixes,
 197           this.given_name,
 198           this.family_name,
 199           this.additional_names,
 200           this.suffixes);
 201     }
 202 }
 203
 204 /**
 205  * Interface for classes which represent contacts with names, such as
 206  * {@link Persona} and {@link Individual}.
 207  *
 208  * @since 0.3.5
 209  */
 210 public interface Folks.NameDetails : Object
 211 {
 212   /**
 213    * The contact name split in its constituent parts.
 214    *
 215    * Note that most of the time the structured name is not set (i.e.
 216    * it's `null`) or just some of the components are set.
 217    * The components are immutable. To get notification of changes of
 218    * the structured name, you just have to connect to the `notify` signal
 219    * of this property.
 220    *
 221    * @since 0.3.5
 222    */
 223   public abstract StructuredName? structured_name { get; set; }
 224
 225   /**
 226    * The full name of the contact.
 227    *
 228    * The full name is the name of the contact written in the way the contact
 229    * prefers. For instance for English names this is usually the given name
 230    * followed by the family name, but Chinese names are usually the family
 231    * name followed by the given name.
 232    * The full name could or could not contain additional names (like a
 233    * middle name), prefixes or suffixes.
 234    *
 235    * @since 0.3.5
 236    */
 237   public abstract string full_name { get; set; }
 238
 239   /**
 240    * The nickname of the contact.
 241    *
 242    * The nickname is the name that the contact chose for himself. This is
 243    * different from {@link AliasDetails.alias} as aliases can be chosen by
 244    * the user and not by the contacts themselves.
 245    *
 246    * Consequently, setting the nickname only makes sense in the context of an
 247    * address book when updating the information a contact has specified about
 248    * themselves.
 249    *
 250    * @since 0.3.5
 251    */
 252   public abstract string nickname { get; set; }
 253 }