2 Copyright (C) 2010 Paul Davis
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.
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.
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.
20 #ifndef __libpbd_property_basics_h__
21 #define __libpbd_property_basics_h__
27 #include "pbd/libpbd_visibility.h"
28 #include "pbd/xml++.h"
34 class LIBPBD_API PropertyList;
35 class LIBPBD_API StatefulDiffCommand;
37 /** A unique identifier for a property of a Stateful object */
38 typedef GQuark PropertyID;
41 struct LIBPBD_TEMPLATE_API PropertyDescriptor {
42 PropertyDescriptor () : property_id (0) {}
43 PropertyDescriptor (PropertyID pid) : property_id (pid) {}
45 PropertyID property_id;
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>
53 LIBPBD_TEMPLATE_MEMBER_API PropertyChange() {}
54 LIBPBD_TEMPLATE_MEMBER_API ~PropertyChange() {}
56 template<typename T> PropertyChange(PropertyDescriptor<T> p);
58 LIBPBD_TEMPLATE_MEMBER_API PropertyChange(const PropertyChange& other) : std::set<PropertyID> (other) {}
60 LIBPBD_TEMPLATE_MEMBER_API PropertyChange operator=(const PropertyChange& other) {
62 insert (other.begin (), other.end ());
66 template<typename T> PropertyChange operator=(PropertyDescriptor<T> p);
67 template<typename T> bool contains (PropertyDescriptor<T> p) const;
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 ()) {
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);
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)
88 class LIBPBD_API PropertyBase
91 PropertyBase (PropertyID pid)
95 virtual ~PropertyBase () {}
98 /* MANAGEMENT OF Stateful STATE */
100 /** Set the value of this property from a Stateful node.
101 * @return true if the value was set.
103 virtual bool set_value (XMLNode const &) = 0;
105 /** Get this property's value and put it into a Stateful node */
106 virtual void get_value (XMLNode& node) const = 0;
109 /* MANAGEMENT OF HISTORY */
111 /** Forget about any old changes to this property's value */
112 virtual void clear_changes () = 0;
114 /** Tell any things we own to forget about their old values */
115 virtual void clear_owned_changes () {}
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.
120 virtual bool changed () const = 0;
122 /** Invert the changes in this property */
123 virtual void invert () = 0;
126 /* TRANSFERRING HISTORY TO / FROM A StatefulDiffCommand */
128 /** Get any changes in this property as XML and add them to a
129 * StatefulDiffCommand node.
131 virtual void get_changes_as_xml (XMLNode *) const = 0;
133 /** If this Property has changed, clone it and add it to a given list.
134 * Used for making StatefulDiffCommands.
136 virtual void get_changes_as_properties (PropertyList& changes, Command *) const = 0;
138 /** Collect StatefulDiffCommands for changes to anything that we own */
139 virtual void rdiff (std::vector<Command*> &) const {}
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.
144 virtual PropertyBase* clone_from_xml (const XMLNode &) const { return 0; }
149 virtual PropertyBase* clone () const = 0;
151 /** Set this property's current state from another */
152 virtual void apply_changes (PropertyBase const *) = 0;
154 const gchar* property_name () const { return g_quark_to_string (_property_id); }
155 PropertyID property_id () const { return _property_id; }
157 bool operator==(PropertyID pid) const {
158 return _property_id == pid;
162 /* copy construction only by subclasses */
163 PropertyBase (PropertyBase const & b)
164 : _property_id (b._property_id)
168 PropertyID _property_id;
174 #endif /* __libpbd_property_basics_h__ */