diff options
author | Mark Vender <markv743@yahoo.co.uk> | 2012-04-01 11:29:34 +0000 |
---|---|---|
committer | Murray Cumming <murrayc@murrayc.com> | 2012-04-03 11:24:34 +0200 |
commit | 2a0b37cb594ccb04c12cc21529014a45e65eb59d (patch) | |
tree | 7b99fcfc0acbc1f9dceb12e1911c33cec65d4581 /glib/glibmm/property.h | |
parent | 40c758285f0fce4d1382071506b23fee0ca4778c (diff) | |
download | glibmm-2a0b37cb594ccb04c12cc21529014a45e65eb59d.tar.gz |
Document Glib::Property and Glib::PropertyBase
* glib/glibmm/property.h:
Bug #673291
Diffstat (limited to 'glib/glibmm/property.h')
-rw-r--r-- | glib/glibmm/property.h | 88 |
1 files changed, 86 insertions, 2 deletions
diff --git a/glib/glibmm/property.h b/glib/glibmm/property.h index b3220b69..52f486d0 100644 --- a/glib/glibmm/property.h +++ b/glib/glibmm/property.h @@ -48,11 +48,24 @@ void custom_set_property_callback(GObject* object, unsigned int property_id, #endif /* DOXYGEN_SHOULD_SKIP_THIS */ - +/** + * Base class for object properties + * + * This class manages the value type-agnostic bits of object properties. + */ class PropertyBase { public: + + /** + * Returns the name of the property + */ Glib::ustring get_name() const; + + /** + * Notifies the object containing the property that the property has changed. + * In other words, emits "notify" signal with the property name. + */ void notify(); protected: @@ -60,12 +73,28 @@ protected: Glib::ValueBase value_; GParamSpec* param_spec_; + /** + * Constructs the property of type @a value_type for @a object. The property + * is not registered in the GObject object system, call install_property in + * order to do that. The properties are usually installed on the + * initialization of the first instance of an object. + */ PropertyBase(Glib::Object& object, GType value_type); ~PropertyBase(); + /** + * Checks if the property has already been installed + */ bool lookup_property(const Glib::ustring& name); + + /** + * Installs the property specified by the given @a param_spec. + */ void install_property(GParamSpec* param_spec); + /** + * Returns the name of the property + */ const char* get_name_internal() const; private: @@ -84,7 +113,33 @@ private: #endif /* DOXYGEN_SHOULD_SKIP_THIS */ }; - +/** + * Represents an object property + * + * This class maps one to one to a property of an object in GObject object + * system. A property is a value associated to each instancy of a type and some + * global data for each property. The global data encompasses the following + * information about the property: + * * unique name, used to identify the property + * * human-readable nick + * * short explanation + * * default value, minimum and maximum bounds (applicable depending on the + * type of the property) + * * flags, defining, among other things, whether the property can be read or + * written + * + * The Property class currently supports only the name and default value. The + * minimum and maximum bounds are set to the full range of the value. The nick + * and the explanation are set to empty. The flags are set to indicate that the + * property can be both read from and written to. + * + * The global information must be installed into the GObject system once per + * property. This is handled automatically. + * + * A property can be used only as direct data member of a type, inheriting from + * Glib::Object. A reference to the object must be passed on the construction of + * the property. + */ template <class T> class Property : public PropertyBase { @@ -92,15 +147,44 @@ public: typedef T PropertyType; typedef Glib::Value<T> ValueType; + /** + * Constructs a property of @a object with @a name. For each instance of the + * object, the same property must be constructed with the same name + */ Property(Glib::Object& object, const Glib::ustring& name); + + /** + * Constructs a property of @a object with @a name and @a default_value. For + * each instance of the object, the same property must be constructed with the + * same name + */ Property(Glib::Object& object, const Glib::ustring& name, const PropertyType& default_value); + /** + * Sets the value of the property to @a data. The object containing the + * property is notified about the change. + */ inline void set_value(const PropertyType& data); + + /** + * Returns the value of the property + */ inline PropertyType get_value() const; + /** + * Sets the value of the property to @a data. The object containing the + * property is notified about the change. + */ inline Property<T>& operator=(const PropertyType& data); + + /** + * Returs the value of the property + */ inline operator PropertyType() const; + /** + * Returns a proxy object that can be used to manipulate this property + */ inline Glib::PropertyProxy<T> get_proxy(); }; |