Development/Cpp/Helper/OPropertyContainerHelper

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

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 an css.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 module cppuhelper.
• 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.

#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
    );
}