Overview

A RoseProperty is an auxiliary object that stores extra information about certain classes. If a class has a property list, your applications can define subclasses of RoseProperty to store temporary information.

The example below defines a name property NameProp, as a subclass of RoseProperty. The declare and implement macros give the class some common functions.

/* In the header file: */
class NameProp : public RoseProperty {
public:
   RoseStringObject name;
   ROSE_DECLARE_PROPERTY(NameProp);
}

/* In the C++ implementation file: */
ROSE_IMPLEMENT_PROPERTY(NameProp);

To use the NameProp class, you would do something like the following. The mesh face class has a list of properties that is returned by the RoseMeshFace::getProps() function.

RoseMeshFace * face = ...

// Add a name property to a face
NameProp * np = new NameProp;
np->name = Test name;
face->getProps()->add(np);


// Find an existing name property or create one if not present
NameProp * np = NameProp::make(face->getProps());
np->name = My new name;


// Find a name property to a face, null if not present
NameProp * np = NameProp::find(face->getProps());
if (np)
    printf (Name = %s\n, np->name.ro_str());
else
    printf (NO NAME\n);

RosePropertyList

class RosePropertyList {
    RoseProperty * find(RosePropertyType t) const;

    void add(RoseProperty * prop);
    void remove(RoseProperty * prop);
    void remove(RosePropertyType t);

    void clear();
}

The RosePropertyList class holds the list of properties and provides functions for adding, removing, and finding them. An object that supports properties will have a function that returns its property list. For example, the mesh face class has a list of properties that is returned by the RoseMeshFace::getProps() function.

RosePropertyType (typedef)

typedef RosePropertyType;

The RosePropertyType typedef is an integer type that identifies each different subclass of RoseProperty so that a property can be identified and cast to a subclass.

The static type() function returns the integer type identifier for a class while the getType() function returns the type identifier for a property instance.

NameProp * np = new NameProp;

// These should print the same number
printf (This instance returns %u\n, np->getType());
printf (All NameProps return %u\n, NameProp::type());

DECLARE and IMPLEMENT macros

#define ROSE_DECLARE_PROPERTY(CLS)
#define ROSE_IMPLEMENT_PROPERTY(CLS)

The ROSE_DECLARE_PROPERTY and ROSE_IMPLEMENT_PROPERTY() macros provide functions used to identify and cast properties. Put the declare macro within the class definition and put the implement macro in the CXX file where you define your other functions. There provide the following:

• static type id for the class - type()
• static find property on a face - find()
• static find or make property on a face - make()
• get type id of a property - getType()

In addition, you can manually declare a copy() function if you would like a property value copied with its owning object.

add()

void RosePropertyList::add(RoseProperty * prop);

The property list add() function adds a property to the list. A property object can only belong to one list and a list can only have one instance of each type() of property. When a property belongs to a list, it will be deleted when the list is cleared or deleted.

RosePropertyList * props;

// using the static function for the class
NameProp * np = new NameProp;
np->name = Test name;

props->add(np);

clear()

void RosePropertyList::clear();

The property list clear() function deletes all properties in the list.

RosePropertyList * props;

props->clear();

copy()

virtual RoseProperty * <CLS>::copy() const;

The property copy() function can be defined to copy the property when its owning list is copied. The inherited version of this function simply returns NULL and the property is omitted. To copy, override this function to return a new instance of the property with the appropriate values set.

class FooProp public RoseProperty {
public:
    int some_data;
    virtual RoseProperty * copy() const;
    ROSE_DECLARE_PROPERTY(FooProp);
};


ROSE_IMPLEMENT_PROPERTY(FooProp);
RoseProperty * FooProp::copy() const
{
     FooProp * ret = new FooProp;
     ret->some_data = this->some_data;
     return ret;
}

find()

static <CLS> * <CLS>::find(
        const RosePropertyList * f
	);

RoseProperty * RosePropertyList::find(
	RosePropertyType t
	) const;

The static property find() function searches a property list for the first instance of that type, or NULL if no match is found. The pointer value is returned cast as the desired class.

The property list find() function works the same way, but takes the RosePropertyType for the desired class and returns a pointer that needs additional down-casting.

RosePropertyList * props;

// using the static function for the class
NameProp * np = NameProp::find(props);

// using the function on the property list
NameProp * np = (NameProp*) props->find(NameProp::type());

getType()

virtual RosePropertyType <CLS>::getType();

The property getType() function returns the type identifier for a property instance. The static property type() function returns the integer type identifier for the class.

make()

static <CLS> * <CLS>::make(
        const RosePropertyList * f
	);

The static property make() function searches a property list for the first instance of that type. If no match is found, the function will creates and adds a new property of the requested type. The function uses the default constructor. If the property requires a different procedure, test with find() and create it manually.

RosePropertyList * props;

// find or create automatically
NameProp * np = NameProp::make(props);

// find and create manually
NameProp * np = NameProp::find(props);
if (!np) {
    np = new NameProp;
    np->name = Test name;
    props->add(np);
}

remove()

void RosePropertyList::remove(RoseProperty * prop);
void RosePropertyList::remove(RosePropertyType t);

The property list remove() function takes a property object or finds a property object matching a given type, removes it from the list, and deletes it.

RosePropertyList * props;

// delete the NameProp object if the list has onect
props->remove(NameProp::type());

type()

static RosePropertyType <CLS>::type();

The static property type() function returns the integer type identifier for the class. The getType() function returns the type identifier for a property instance.