Difference between revisions of "Development/Cpp/Helper/OPropertyContainerHelper"
(→Example) |
(→Interface) |
||
Line 28: | Line 28: | ||
* {{CppMethod|describeProperties}}: fills a sequence with the description of the actual properties of the instance. Useful to implement the <code>XPropertySetInfo</code> interface. | * {{CppMethod|describeProperties}}: fills a sequence with the description of the actual properties of the instance. Useful to implement the <code>XPropertySetInfo</code> interface. | ||
− | Note that the class is intended to be derived from. This is part of the it's patina [[Image:smiley.gif]] (the roots of the class as {{CppClass|OPropertyContainer}} lie in the year 2000) - nowadays, you would probably make its interface public instead of protected, so you | + | Note that the class is intended to be derived from. This is part of the it's patina [[Image:smiley.gif]] (the roots of the class as {{CppClass|OPropertyContainer}} lie in the year 2000) - nowadays, you would probably make its interface public instead of protected, so you could aggregate an instance of it. |
=== Example === | === Example === |
Revision as of 10:03, 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. This saves you a lot of the switch/case
blocks you usually see in implementations of the get/set[Fast]PropertyValue 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 header file, please browse propertycontainer.hxx
's source code online, or check out the file from CVS (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 with the description of the actual properties of the instance. Useful to implement the
XPropertySetInfo
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 could aggregate an instance of it.
Example
The following declares a class Foo, which demonstrates how easy you can register properties. As mentioned above, the class is far from being read-for-use, but it demonstrates some aspects of the OPropertyContainerHelper.
[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 XInterface::static_type(), // type of the property &xEmpty // initial value, will be copied );
}