Difference between revisions of "Development/Cpp/Helper/OPropertyContainerHelper"
m (Development/Cpp/Helper/PropertyContainerHelper moved to Development/Cpp/Helper/OPropertyContainerHelper: wrong class name ...) |
|||
Line 1: | Line 1: | ||
{{CppHelper/Heading|OPropertyContainerHelper|is a helper class for managing properties, each associated with a location of the property value, and implementing the property set related interfaces|<code>comphelper/propertycontainerhelper.hxx</code>}} | {{CppHelper/Heading|OPropertyContainerHelper|is a helper class for managing properties, each associated with a location of the property value, and implementing the property set related interfaces|<code>comphelper/propertycontainerhelper.hxx</code>}} | ||
+ | |||
+ | __TOC__ | ||
=== Description === | === Description === |
Revision as of 09:56, 29 November 2007
Class Name | Purpose | Location |
---|---|---|
OPropertyContainerHelper | is a helper class for managing properties, each associated with a location of the property value, and implementing the property set related interfaces | comphelper/propertycontainerhelper.hxx
|
Contents
Description
A OPropertyContainerHelper manages a set of properties and property values.
A property is described by all the attributes required by a css.beans.Property: Name, Handle, Type, and Attributes. A OPropertyContainerHelper allows you to specify an arbitrary number of properties, and keeps track of them, later being able to hand out a structure describing them.
What makes the class powerful is that together with a property description the class also manages the location where the actual property value is stored. When you register a property, you also register the location (or let the OPropertyContainerHelper find one) of the property value. From then on, every read access to the property will return the value stored in the location, and every write access will change the value in this location.
This is especially useful together with member variables: If your class implements the property set related interfaces, and you also want a quick, typed access to the actual property values, you can declare a class member, and register this member as location of a property's value. Then, read and write access to the member is equivalent to read and write access to the property value, using OPropertyContainerHelper's methods.
Note that OPropertyContainerHelper is a very basic building block only. You can use it in classes which already have property set related functionality, for a certain subset thereof, or you can combine it with other helper classes.
If you're looking for a ready-made property set class, you might want to take the next step, and look at the OPropertyContainer, which merges the OPropertyContainerHelper and ::cppu::OPropertySetHelper classes.
Interface
For a complete interface description, you're referred to the file, please browse propertycontainer.hxx
's source code online, or check out the file (it's located in comphelper/inc/comphelper
).
Here, only some of the interface methods are mentioned:
- registerProperty: The main method for registering a property, together with a (typed) value location.
- registerMayBeVoidProperty: registers a property which can be
void
, thus represented by ancss.uno.Any
. - registerPropertyNoMember: registers a property without actual location. The OPropertyContainerHelper will allocate space for this property's value in an internal repository.
- convertFastPropertyValue, setFastPropertyValue, getFastPropertyValue: central entry point for setting and getting property values. Those methods have the same signature and semantics as the respective methods at the
OPropertySetHelper
class from modulecppuhelper
. - describeProperties: fills a sequence of
Property
s with the description of the actual properties of the instance. Useful to implement theXPropertySetInfo
interface.
Note that the class is intended to be derived from. This is part of the it's patina (the roots of the class as OPropertyContainer lie in the year 2000) - nowadays, you would probably make its interface public instead of protected, so you can aggregate an instance of it.
Example
The following declares a class Foo, which demonstrates how easy you can register properties.
[cpp]
- include <comphelper/propertycontainerhelper.hxx>
- include <com/sun/star/beans/PropertyAttribute.hpp>
using ::com::sun::star::uno::Any; using ::com::sun::star::uno::Reference; using ::com::sun::star::uno::XInterface; namespace PropertyAttribute = ::com::sun::star::beans::PropertyAttribute;
typedef ::comphelper::OPropertyContainerHelper Foo_Base;
class Foo : public Foo_Base { public:
Foo();
private:
// <properties> ::rtl::OUString m_sTitle; Any m_aBar; // </properties>
};
Foo::Foo()
:m_sTitle() ,m_aBar()
{
registerProperty( ::rtl::OUString( RTL_CONSTASCII_USTRINGPARAM( "Title" ) ), // property name 1, // property handle PropertyAttribute::BOUND, // property attributes &m_sTitle, // location of the property value ::getCppuType( &m_sTitle ) // type of the property );
registerMayBeVoidProperty( ::rtl::OUString( RTL_CONSTASCII_USTRINGPARAM( "Bar" ) ), // property name 2, // property handle PropertyAttribute::BOUND | PropertyAttribute::MAYBEVOID, // property attributes &m_aBar, // location of the property value ::cppu::UnoType< sal_Int32 >::get() // type of the property );
Reference< XInterface > xEmpty; registerPropertyNoMember( ::rtl::OUString( RTL_CONSTASCII_USTRINGPARAM( "IFace" ) ), // property name 3, // property handle PropertyAttribute::BOUND | PropertyAttribute::MAYBEVOID, // property attributes ::cppu::UnoType< Reference< XInterface > >::get(), // type of the property &xEmpty // initial value, will be copied );
}