libs/pbd/pbd/stateful.h

   1 /*
   2     Copyright (C) 2000-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 __pbd_stateful_h__
  21 #define __pbd_stateful_h__
  22
  23 #include <string>
  24 #include <list>
  25 #include <cassert>
  26
  27 #include "pbd/libpbd_visibility.h"
  28 #include "pbd/id.h"
  29 #include "pbd/xml++.h"
  30 #include "pbd/property_basics.h"
  31 #include "pbd/signals.h"
  32
  33 class XMLNode;
  34
  35 namespace PBD {
  36
  37 namespace sys {
  38         class path;
  39 }
  40
  41 class PropertyList;
  42 class OwnedPropertyList;
  43
  44 /** Base class for objects with saveable and undoable state */
  45 class LIBPBD_API Stateful {
  46   public:
  47         Stateful ();
  48         virtual ~Stateful();
  49
  50         virtual XMLNode& get_state (void) = 0;
  51         virtual int set_state (const XMLNode&, int version) = 0;
  52
  53         virtual bool apply_changes (PropertyBase const &);
  54         PropertyChange apply_changes (PropertyList const &);
  55
  56         const OwnedPropertyList& properties() const { return *_properties; }
  57
  58         void add_property (PropertyBase& s);
  59
  60         /* Extra XML node: so that 3rd parties can attach state to the XMLNode
  61            representing the state of this object.
  62          */
  63
  64         void add_extra_xml (XMLNode&);
  65         XMLNode *extra_xml (const std::string& str, bool add_if_missing = false);
  66         void save_extra_xml (const XMLNode&);
  67
  68         const PBD::ID& id() const { return _id; }
  69         bool set_id (const XMLNode&);
  70         void set_id (const std::string&);
  71         void reset_id ();
  72
  73         /* RAII structure to manage thread-local ID regeneration.
  74          */
  75         struct ForceIDRegeneration {
  76                 ForceIDRegeneration () {
  77                         set_regenerate_xml_and_string_ids_in_this_thread (true);
  78                 }
  79                 ~ForceIDRegeneration () {
  80                         set_regenerate_xml_and_string_ids_in_this_thread (false);
  81                 }
  82         };
  83
  84         /* history management */
  85
  86         void clear_changes ();
  87         virtual void clear_owned_changes ();
  88         PropertyList* get_changes_as_properties (Command *) const;
  89         virtual void rdiff (std::vector<Command*> &) const;
  90         bool changed() const;
  91
  92         /* create a property list from an XMLNode */
  93         virtual PropertyList* property_factory (const XMLNode&) const;
  94
  95         /* How stateful's notify of changes to their properties */
  96         PBD::Signal1<void,const PropertyChange&> PropertyChanged;
  97
  98         static int current_state_version;
  99         static int loading_state_version;
 100
 101         virtual void suspend_property_changes ();
 102         virtual void resume_property_changes ();
 103
 104         bool property_changes_suspended() const { return g_atomic_int_get (const_cast<gint*>(&_stateful_frozen)) > 0; }
 105
 106   protected:
 107
 108         void add_instant_xml (XMLNode&, const std::string& directory_path);
 109         XMLNode *instant_xml (const std::string& str, const std::string& directory_path);
 110         void add_properties (XMLNode &);
 111
 112         PropertyChange set_values (XMLNode const &);
 113
 114         /* derived classes can implement this to do cross-checking
 115            of property values after either a PropertyList or XML
 116            driven property change.
 117         */
 118         virtual void post_set (const PropertyChange&) { };
 119
 120         XMLNode *_extra_xml;
 121         XMLNode *_instant_xml;
 122         PBD::PropertyChange     _pending_changed;
 123         Glib::Threads::Mutex _lock;
 124
 125         std::string _xml_node_name; ///< name of node to use for this object in XML
 126         OwnedPropertyList* _properties;
 127
 128         virtual void send_change (const PropertyChange&);
 129         /** derived classes can implement this in order to process a property change
 130             within thaw() just before send_change() is called.
 131         */
 132         virtual void mid_thaw (const PropertyChange&) { }
 133
 134         bool regenerate_xml_or_string_ids () const;
 135
 136   private:
 137         friend struct ForceIDRegeneration;
 138         static Glib::Threads::Private<bool> _regenerate_xml_or_string_ids;
 139         PBD::ID  _id;
 140         gint     _stateful_frozen;
 141
 142         static void set_regenerate_xml_and_string_ids_in_this_thread (bool yn);
 143 };
 144
 145 } // namespace PBD
 146
 147 #endif /* __pbd_stateful_h__ */