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         /* history management */
  74
  75         void clear_changes ();
  76         virtual void clear_owned_changes ();
  77         PropertyList* get_changes_as_properties (Command *) const;
  78         virtual void rdiff (std::vector<Command*> &) const;
  79         bool changed() const;
  80
  81         /* create a property list from an XMLNode
  82          */
  83         virtual PropertyList* property_factory (const XMLNode&) const;
  84
  85         /* How stateful's notify of changes to their properties
  86          */
  87         PBD::Signal1<void,const PropertyChange&> PropertyChanged;
  88
  89         static int current_state_version;
  90         static int loading_state_version;
  91
  92         virtual void suspend_property_changes ();
  93         virtual void resume_property_changes ();
  94
  95         bool property_changes_suspended() const { return g_atomic_int_get (const_cast<gint*>(&_stateful_frozen)) > 0; }
  96
  97   protected:
  98
  99         void add_instant_xml (XMLNode&, const std::string& directory_path);
 100         XMLNode *instant_xml (const std::string& str, const std::string& directory_path);
 101         void add_properties (XMLNode &);
 102
 103         PropertyChange set_values (XMLNode const &);
 104
 105         /* derived classes can implement this to do cross-checking
 106            of property values after either a PropertyList or XML
 107            driven property change.
 108         */
 109         virtual void post_set (const PropertyChange&) { };
 110
 111         XMLNode *_extra_xml;
 112         XMLNode *_instant_xml;
 113         PBD::PropertyChange     _pending_changed;
 114         Glib::Threads::Mutex _lock;
 115
 116         std::string _xml_node_name; ///< name of node to use for this object in XML
 117         OwnedPropertyList* _properties;
 118
 119         virtual void send_change (const PropertyChange&);
 120         /** derived classes can implement this in order to process a property change
 121             within thaw() just before send_change() is called.
 122         */
 123         virtual void mid_thaw (const PropertyChange&) { }
 124
 125   private:
 126         PBD::ID  _id;
 127         gint     _stateful_frozen;
 128 };
 129
 130 } // namespace PBD
 131
 132 #endif /* __pbd_stateful_h__ */
 133