simgear/props/PropertyBasedElement.hxx

   1 // Base class for elements of property controlled subsystems
   2 //
   3 // Copyright (C) 2012  Thomas Geymayer <tomgey@gmail.com>
   4 //
   5 // This library is free software; you can redistribute it and/or
   6 // modify it under the terms of the GNU Library General Public
   7 // License as published by the Free Software Foundation; either
   8 // version 2 of the License, or (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 GNU
  13 // Library General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU Library General Public
  16 // License along with this library; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
  18
  19 #ifndef SG_PROPERTY_BASED_ELEMENT_HXX_
  20 #define SG_PROPERTY_BASED_ELEMENT_HXX_
  21
  22 #include <simgear/props/props.hxx>
  23 #include <simgear/structure/SGWeakReferenced.hxx>
  24
  25 namespace simgear
  26 {
  27
  28   /**
  29    * Base class for a property controlled element
  30    */
  31   class PropertyBasedElement:
  32     public SGPropertyChangeListener,
  33     public virtual SGVirtualWeakReferenced
  34   {
  35     public:
  36       PropertyBasedElement(SGPropertyNode* node);
  37       virtual ~PropertyBasedElement();
  38
  39       /**
  40        * Remove the property listener of the element.
  41        *
  42        * You will need to call the appropriate methods (childAdded(),
  43        * childRemoved(), valueChanged()) yourself to ensure the element still
  44        * receives the needed events.
  45        */
  46       void removeListener();
  47
  48       /**
  49        * Destroys this element (removes node from property tree)
  50        */
  51       void destroy();
  52
  53       virtual void update(double delta_time_sec) = 0;
  54
  55       SGConstPropertyNode_ptr getProps() const;
  56       SGPropertyNode_ptr getProps();
  57
  58       template<class T>
  59       void set( const std::string& name,
  60                 const T& val )
  61       {
  62         setValue(_node->getNode(name, true), val);
  63       }
  64
  65       template<class T>
  66       T get( const std::string& name,
  67              const T& def = T() )
  68       {
  69         SGPropertyNode const* child = _node->getNode(name);
  70         if( !child )
  71           return def;
  72
  73         return getValue<T>(child);
  74       }
  75
  76       // Unshadow what we have just hidden...
  77       using SGWeakReferenced::get;
  78
  79
  80       /** @brief Set a HTML5 like data property on this element.
  81        *
  82        * Set data-* properties on this element. A camel-case @a name will be
  83        * converted to a hyphenated name with 'data-' prefixed. Setting a value
  84        * with this method does not trigger an update of the canvas and is meant
  85        * to store data related to this element (used eg. inside scripts).
  86        *
  87        * @code{cpp}
  88        * // Set value
  89        * my_element->setDataProp("mySpecialInt", 3);
  90        *
  91        * // Get value (with default value)
  92        * int val = my_element->getDataProp<int>("mySpecialInt");   // val == 3
  93        *     val = my_element->getDataProp<int>("notExisting", 5); // val == 5
  94        *
  95        * // Check if value exists
  96        * SGPropertyNode* node =
  97        *   my_element->getDataProp<SGPropertyNode*>("mySpecialInt");
  98        * if( node )
  99        *   val = node->getIntValue(); // node != NULL, val == 3
 100        *
 101        * node = my_element->getDataProp<SGPropertyNode*>("notExisting");
 102        * // node == NULL
 103        * @endcode
 104        */
 105       template<class T>
 106       void setDataProp( const std::string& name,
 107                         const T& val )
 108       {
 109         const std::string& attr = dataPropToAttrName(name);
 110         if( !attr.empty() )
 111           set<T>(attr, val);
 112         else
 113           SG_LOG(SG_GENERAL, SG_WARN, "Invalid data-prop name: " << name);
 114       }
 115
 116       /** @brief Get a HTML5 like data property on this element.
 117        *
 118        * Get value or default value.
 119        *
 120        * @see setDataProp
 121        */
 122       template<class T>
 123       typename boost::disable_if<
 124         boost::is_same<T, SGPropertyNode*>,
 125         T
 126       >::type getDataProp( const std::string& name,
 127                            const T& def = T() ) const
 128       {
 129         SGPropertyNode* node = getDataProp<SGPropertyNode*>(name);
 130         if( node )
 131           return getValue<T>(node);
 132
 133         return def;
 134       }
 135
 136       /** @brief Get a HTML5 like data property on this element.
 137        *
 138        * Use this variant to check if a property exists.
 139        *
 140        * @see setDataProp
 141        */
 142       template<class T>
 143       typename boost::enable_if<
 144         boost::is_same<T, SGPropertyNode*>,
 145         T
 146       >::type getDataProp( const std::string& name,
 147                            SGPropertyNode* = NULL ) const
 148       {
 149         const std::string& attr = dataPropToAttrName(name);
 150         if( attr.empty() )
 151         {
 152           SG_LOG(SG_GENERAL, SG_WARN, "Invalid data-prop name: " << name);
 153           return NULL;
 154         }
 155
 156         return _node->getNode(attr);
 157       }
 158
 159       /** @brief Check whether a HTML5 like data property exists on this
 160        *         element.
 161        *
 162        */
 163       bool hasDataProp(const std::string& name) const;
 164
 165       /** @brief Remove a HTML5 like data property (if it exists).
 166        *
 167        */
 168       void removeDataProp(const std::string& name);
 169
 170       virtual void onDestroy() {};
 171
 172       static std::string dataPropToAttrName(const std::string& name);
 173       static std::string attrToDataPropName(const std::string& name);
 174
 175     protected:
 176
 177       SGPropertyNode_ptr _node;
 178
 179   };
 180
 181   typedef SGSharedPtr<PropertyBasedElement> PropertyBasedElementPtr;
 182   typedef SGWeakPtr<PropertyBasedElement> PropertyBasedElementWeakPtr;
 183
 184 } // namespace simgear
 185
 186 #endif /* SG_PROPERTY_BASED_ELEMENT_HXX_ */