Rogue Wave banner
Previous fileTop of DocumentContentsIndex pageNext file
Stingray Foundation Library User's Guide
Rogue Wave web site:  Home Page  |  Main Documentation Page

5.2 Property Containers

The IPropertyContainer interface provides an interface to an object's properties. You can use it to retrieve an IProperty pointer to each property supported by the object. The IProperty interface only describes the property, it doesn't give access to the value of the property. The IPropertyContainer interface has methods for getting and setting the value of a given property.

Example 23 demonstrates how to display each of the properties for a given property container.

Example 23: Using a property container to display an object's properties

5.2.1 A Property Container Implementation

Any C++ object can expose properties at run time by implementing the IPropertyContainer interface. However, the CPropertyContainer class provides an implementation of the IPropertyContainer interface that is sufficient for most applications. Properties must be registered with CPropertyContainer objects using one of several RegisterProperty() methods. The most basic RegisterProperty() method takes an IProperty pointer. There are several variations of RegisterProperty() that create a CProperty object using the parameters passed in and register it.

5.2.1.1 The Property Map

The CPropertyContainer class stores the properties in a map, which is keyed on the property ID. The nested class CPropertyContainer::Map implements the property map. To avoid the overhead of maintaining a separate map of properties for each instance of CPropertyContainer, the CPropertyContainer class calls the virtual method GetPropertyMap() whenever it needs to access the property map. This gives derived classes the opportunity to implement GetPropertyMap() in an efficient manner. For example, they can return a statically declared CPropertyContainer::Map object. The SFL_PROPERTY_MAP macro is provided to do this. The SFL_PROPERTY_MAP macro implements GetPropertyMap() as shown in Example 24.

Example 24: Expansion of SFL_PROPERTY_MAP

Example 25 shows a class that uses the SFL_PROPERTY_MAP macro.

Example 25: Using the SFL_PROPERTY_MAP macro in a class definition

Classes that derive from CPropertyContainer can implement GetPropertyMap() any way they like. The SFL_PROPERTY_MAP macro is a convenient way to do so.

5.2.1.2 Property Accessors

The CPropertyContainer class is a template that takes an accessor class as its parameter. CPropertyContainer uses accessor objects to implement the GetPropertyValue() and PutPropertyValue() methods it inherits from IPropertyContainer. It creates an accessor object for each property and stores it in the property map along with the IProperty pointer. To store or retrieve a property value, CPropertyContainer does a quick lookup in the property map to get the accessor object and then invokes either the GetValue() function or PutValue() function on the accessor. A pointer to the derived class is passed to the accessor, so that it can invoke the appropriate get or put function. The accessor object is an essential get and put functor for the property.

The only requirement for an accessor class is that it define an embedded typedef called _SourceClass and implement the following methods.

Fortunately, there is a default accessor implementation called CPropertyAccessor, which is suitable for most applications. The CPropertyAccessor uses function pointers to implement GetValue() and PutValue(), and it uses a template parameter to define SourceClass. CPropertyAccessor defines a set of function signatures that you must use for the get and put functions. The functions assigned to the accessor must match one of those signatures. Example 26 shows how to create and use an accessor for storing and retrieving a floating-point value in a class called CFoo.

Example 26: Creating and using an accessor

Property accessors allow containers to get and set values using simple accessor functions without knowing the names of those functions and without knowing the memory address and type of the data. The container simply needs to map the property ID to an accessor to store and retrieve values. Class CFoo doesn't need to perform any special functions.

5.2.2 Property Container Example

Example 27 shows a class that inherits CPropertyContainer and registers some properties.


Each property must have a numeric identifier associated with it. The only rule for assigning property identifiers is that they must be unique within the container.

Example 27: Implementing a property container

With the exception of the SFL_PROPERTY_MAP macro and the calls to RegisterProperty() in the constructor, this class looks and acts like any C++ class.



Previous fileTop of DocumentContentsNo linkNext file

Copyright © Rogue Wave Software, Inc. All Rights Reserved.

The Rogue Wave name and logo, and Stingray, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.