libs/pbd/pbd/property_basics.h

   1 /*
   2     Copyright (C) 2010 Paul Davis
   3
   4     This program is free software; you can redistribute it and/or modify
   5     it under the terms of the GNU General Public License as published by
   6     the Free Software Foundation; either version 2 of the License, or
   7     (at your option) any later version.
   8
   9     This program 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 General Public License for more details.
  13
  14     You should have received a copy of the GNU General Public License
  15     along with this program; if not, write to the Free Software
  16     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17
  18 */
  19
  20 #ifndef __libpbd_property_basics_h__
  21 #define __libpbd_property_basics_h__
  22
  23 #include <glib.h>
  24 #include <set>
  25 #include <vector>
  26
  27 #include "pbd/libpbd_visibility.h"
  28 #include "pbd/xml++.h"
  29
  30 class Command;
  31
  32 namespace PBD {
  33
  34 class LIBPBD_API PropertyList;
  35 class LIBPBD_API StatefulDiffCommand;
  36
  37 /** A unique identifier for a property of a Stateful object */
  38 typedef GQuark PropertyID;
  39
  40 template<typename T>
  41 struct LIBPBD_TEMPLATE_API PropertyDescriptor {
  42         PropertyDescriptor () : property_id (0) {}
  43         PropertyDescriptor (PropertyID pid) : property_id (pid) {}
  44
  45         PropertyID property_id;
  46         typedef T value_type;
  47 };
  48
  49 /** A list of IDs of Properties that have changed in some situation or other */
  50 class LIBPBD_TEMPLATE_API PropertyChange : public std::set<PropertyID>
  51 {
  52 public:
  53         LIBPBD_TEMPLATE_MEMBER_API PropertyChange() {}
  54         LIBPBD_TEMPLATE_MEMBER_API ~PropertyChange() {}
  55
  56         template<typename T> PropertyChange(PropertyDescriptor<T> p);
  57
  58         LIBPBD_TEMPLATE_MEMBER_API PropertyChange(const PropertyChange& other) : std::set<PropertyID> (other) {}
  59
  60         LIBPBD_TEMPLATE_MEMBER_API PropertyChange operator=(const PropertyChange& other) {
  61                 clear ();
  62                 insert (other.begin (), other.end ());
  63                 return *this;
  64         }
  65
  66         template<typename T> PropertyChange operator=(PropertyDescriptor<T> p);
  67         template<typename T> bool contains (PropertyDescriptor<T> p) const;
  68
  69         LIBPBD_TEMPLATE_MEMBER_API bool contains (const PropertyChange& other) const {
  70                 for (const_iterator x = other.begin (); x != other.end (); ++x) {
  71                         if (find (*x) != end ()) {
  72                                 return true;
  73                         }
  74                 }
  75                 return false;
  76         }
  77
  78         void add (PropertyID id)               { insert (id); }
  79         void add (const PropertyChange& other) { insert (other.begin (), other.end ()); }
  80         template<typename T> void add (PropertyDescriptor<T> p);
  81 };
  82
  83 /** Base (non template) part of Property
  84  *  Properties are used for two main reasons:
  85  *    - to handle current state (when serializing Stateful objects)
  86  *    - to handle history since some operation was started (when making StatefulDiffCommands for undo)
  87  */
  88 class LIBPBD_API PropertyBase
  89 {
  90 public:
  91         PropertyBase (PropertyID pid)
  92                 : _property_id (pid)
  93         {}
  94
  95         virtual ~PropertyBase () {}
  96
  97
  98         /* MANAGEMENT OF Stateful STATE */
  99
 100         /** Set the value of this property from a Stateful node.
 101          *  @return true if the value was set.
 102          */
 103         virtual bool set_value (XMLNode const &) = 0;
 104
 105         /** Get this property's value and put it into a Stateful node */
 106         virtual void get_value (XMLNode& node) const = 0;
 107
 108
 109         /* MANAGEMENT OF HISTORY */
 110
 111         /** Forget about any old changes to this property's value */
 112         virtual void clear_changes () = 0;
 113
 114         /** Tell any things we own to forget about their old values */
 115         virtual void clear_owned_changes () {}
 116
 117         /** @return true if this property has changed in value since construction or since
 118          *  the last call to clear_changes (), whichever was more recent.
 119          */
 120         virtual bool changed () const = 0;
 121
 122         /** Invert the changes in this property */
 123         virtual void invert () = 0;
 124
 125
 126         /* TRANSFERRING HISTORY TO / FROM A StatefulDiffCommand */
 127
 128         /** Get any changes in this property as XML and add them to a
 129          *  StatefulDiffCommand node.
 130          */
 131         virtual void get_changes_as_xml (XMLNode *) const = 0;
 132
 133         /** If this Property has changed, clone it and add it to a given list.
 134          *  Used for making StatefulDiffCommands.
 135          */
 136         virtual void get_changes_as_properties (PropertyList& changes, Command *) const = 0;
 137
 138         /** Collect StatefulDiffCommands for changes to anything that we own */
 139         virtual void rdiff (std::vector<Command*> &) const {}
 140
 141         /** Look in an XML node written by get_changes_as_xml and, if XML from this property
 142          *  is found, create a property with the changes from the XML.
 143          */
 144         virtual PropertyBase* clone_from_xml (const XMLNode &) const { return 0; }
 145
 146
 147         /* VARIOUS */
 148
 149         virtual PropertyBase* clone () const = 0;
 150
 151         /** Set this property's current state from another */
 152         virtual void apply_changes (PropertyBase const *) = 0;
 153
 154         const gchar* property_name () const { return g_quark_to_string (_property_id); }
 155         PropertyID   property_id () const   { return _property_id; }
 156
 157         bool operator==(PropertyID pid) const {
 158                 return _property_id == pid;
 159         }
 160
 161 protected:
 162         /* copy construction only by subclasses */
 163         PropertyBase (PropertyBase const & b)
 164                 : _property_id (b._property_id)
 165         {}
 166
 167 private:
 168         PropertyID _property_id;
 169
 170 };
 171
 172 }
 173
 174 #endif /* __libpbd_property_basics_h__ */