Associating Named Properties with Objects

As with user properties, you associate a named property with a graphic object using an IlSymbol. An IlSymbol is attached to one and only one subclass of IlvNamedProperty to ensure that the type of the retrieved property is correct.

To handle named properties, you can use the following three member functions of the class IlvGraphic:

IlvNamedProperty* getNamedProperty(const IlSymbol*) const;

IlvNamedProperty* setNamedProperty(IlvNamedProperty*);

IlvNamedProperty* removeNamedProperty(IlSymbol*);

You can see that an IlSymbol is all you need to indicate which named property you are dealing with.

A Predefined Named Property: the Tooltip

An example of a predefined named property is the tooltip, a small text window that pops up when the pointing device enters a panel control element (such as a gadget) and stays for a moment. The class IlvToolTip is defined in the header file <ilviews/graphics/tooltip.h>.

To set a tooltip for a graphic object, retrieve it, and then remove it, write the following:

obj->setNamedProperty(new IlvToolTip("Text"));

...

IlvToolTip* toolTip = IlvToolTip::GetToolTip(obj);

...

delete obj->removeNamedProperty(toolTip->getSymbol());

Named properties may be transferred from object to object. To remove a named property from the list of named properties without deleting it, use the IlvGraphic::removeNamedProperty member function. To delete a named property and thus clear the memory it occupies, you must call delete explicitly.

Because a subclass of IlvNamedProperty and the symbol (that is, the pointer to IlSymbol) that refers to it are tightly coupled, most of the time this symbol is a static data member of the property class. Note, however, that this is not mandatory. Using a static data member of the property class makes it possible for you to retrieve a named property from an object using a symbol that you may not know, but which is directly accessible from the class.

In the above example, you can see that the symbol used by the tooltip property never appears. To retrieve the named property, we simply get the property symbol using the member function IlvNamedProperty::getSymbol.

Note that named properties are copied and saved with the object, and they are deleted when you delete the object. Named properties behave like additional data members of existing classes, with the possibility of defining a powerful API to access the data at the level of the named property class.