folks/note-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  *       Raul Gutierrez Segales <raul.gutierrez.segales@collabora.co.uk>
  20  *       Philip Withnall <philip@tecnocode.co.uk>
  21  */
  22
  23 using Gee;
  24 using GLib;
  25
  26 /**
  27  * Object representing a note that can have some parameters associated with it.
  28  *
  29  * See {@link Folks.AbstractFieldDetails} for details on common parameter names
  30  * and values.
  31  *
  32  * @since 0.6.0
  33  */
  34 public class Folks.NoteFieldDetails : AbstractFieldDetails<string>
  35 {
  36   private string _id;
  37   /**
  38    * {@inheritDoc}
  39    */
  40   public override string id
  41     {
  42       get { return this._id; }
  43       set { this._id = (value != null ? value : ""); }
  44     }
  45
  46   /**
  47    * The UID of the note (if any).
  48    */
  49   [Deprecated (since = "0.6.5", replacement = "AbstractFieldDetails.id")]
  50   public string uid
  51     {
  52       get { return this.id; }
  53       set { this.id = value; }
  54     }
  55
  56   /**
  57    * Create a new NoteFieldDetails.
  58    *
  59    * @param value the value of the field, which should be a non-empty free-form
  60    * UTF-8 string as entered by the user
  61    * @param parameters initial parameters. See
  62    * {@link AbstractFieldDetails.parameters}. A `null` value is equivalent to a
  63    * empty map of parameters.
  64    *
  65    * @return a new NoteFieldDetails
  66    *
  67    * @since 0.6.0
  68    */
  69   public NoteFieldDetails (string value,
  70       MultiMap<string, string>? parameters = null,
  71       string? uid = null)
  72     {
  73       if (value == "")
  74         {
  75           warning ("Empty note passed to NoteFieldDetails.");
  76         }
  77
  78       Object (value: value,
  79               id: uid,
  80               parameters: parameters);
  81     }
  82
  83   /**
  84    * {@inheritDoc}
  85    *
  86    * @since 0.6.0
  87    */
  88   public override bool equal (AbstractFieldDetails<string> that)
  89     {
  90       return base.equal (that);
  91     }
  92
  93   /**
  94    * {@inheritDoc}
  95    *
  96    * @since 0.6.0
  97    */
  98   public override uint hash ()
  99     {
 100       return (this.value.hash () + this.id.hash ());
 101     }
 102 }
 103
 104 /**
 105  * This interface represents the list of notes associated
 106  * to a {@link Persona} and {@link Individual}.
 107  *
 108  * @since 0.4.0
 109  */
 110 public interface Folks.NoteDetails : Object
 111 {
 112   /**
 113    * The notes about the contact.
 114    *
 115    * @since 0.5.1
 116    */
 117   public abstract Set<NoteFieldDetails> notes { get; set; }
 118
 119   /**
 120    * Change the contact's notes.
 121    *
 122    * It's preferred to call this rather than setting {@link NoteDetails.notes}
 123    * directly, as this method gives error notification and will only return once
 124    * the notes have been written to the relevant backing store (or the
 125    * operation's failed).
 126    *
 127    * @param notes the set of notes
 128    * @throws PropertyError if setting the notes failed
 129    * @since 0.6.2
 130    */
 131   public virtual async void change_notes (Set<NoteFieldDetails> notes)
 132       throws PropertyError
 133     {
 134       /* Default implementation. */
 135       throw new PropertyError.NOT_WRITEABLE (
 136           _("Notes are not writeable on this contact."));
 137     }
 138 }