Creating your own named property class is a straightforward, three-step procedure:

Using a very simple example—the storage of two values—the following section explains how to create a named property that you can associate with graphic objects. You can, however, build named properties with member functions to handle more elaborate data members, or have named properties that store pointers to existing classes. Using named properties, you can link application data with a high level of complexity to light graphic objects, with minimum coding and without altering the API of your application classes.

To illustrate, we are going to create a named property that holds both an integer and a character string and make it easily accessible and persistent.

The general development tasks are:

The named property that we are going to create must be a subclass of IlvNamedProperty. The named property stores an integer and a string. Its complete header file is given below:

In addition to the two data members _integer and _string (and their accessors), we will focus on the _Symbol static data member and on the two macro calls that appear in the declaration part of the class, namely DeclarePropertyInfo and DeclarePropertyIOConstructors.

Note that the destructor of the class is virtual like the one of the base class IlvNamedProperty.

First we are going to define the property symbol that will be used to access the class. A simple way to define this symbol is to make it a static data member of your property class, _Symbol, and provide it with a public accessor, GetSymbol. By doing this, any application will be able to retrieve an instance of MyProperty without having to know which symbol is used to associate it with an object.

Therefore, the public and static accessor GetSymbol is defined to return the appropriate IlSymbol and create it if necessary.

In the code below, an extract of the implementation file, we define both the accessor to the property symbol and the static data member, which we initialize to 0. Note that the symbol is created the first time it is queried in MyProperty::GetSymbol.

Let’s now examine the constructor and the destructor. All we need to do is call the constructor of the parent class, IlvNamedProperty, and initialize our data members:

The first time a property of the MyProperty type is created, the static member function GetSymbol is called to set the static data member _Symbol to a valid value.

The string parameter is copied by the setString member function that will check whether the data member _string is valid. This is why we initialize this data member to 0 in the initializers of the constructor. This parameter is destroyed in the destructor, if it was valid.

Below is the definition of the setString member function that copies and stores the string:

This code is quite simple. If a valid string—a non-null string— was stored, it is destroyed. If the parameter is valid—non-null—a copy of this string is made and stored. If the parameter is not valid, the data member is simply reset to 0.

At this stage, our class can store and retrieve both an integer and a character-string value.

For our named property to be complete, we have to add the class-level information and persistence-related member functions. The easiest way to do this is to use the following two macros in the body of the class declaration:

These macros make it very easy to add copy and persistence functionality to your class.

Once the macros have been declared, all we have to do to add copy and persistence features to our class is to define a copy constructor and a constructor that take an IlvInputFile reference as its parameter:

The first constructor initializes a new instance of MyProperty with a copy of its source parameter.

The second constructor reads the provided input stream to initialize its instance with what is read.

Now that we are able to read a new instance of the class, we can save it. To do so, we have to define a write member function, which is implicitly declared by the macro DeclarePropertyInfo.

The saving order must be the same as the reading order.

Note that you may define a named property that does not have any additional information to save. In this case, you would use the DeclarePropertyInfoRO macro instead of DeclarePropertyInfo in the class declaration and drop the write member function that would be useless.

To provide Views with an entry point to the read and copy constructors, you must add another macro to the implementation file, outside the body of any function, as follows:

Calling this macro actually creates a read static member function that invokes the read constructor. It also defines a copy member function that calls the copy constructor.

The final step to have our named property up and running in our application is to register the MyProperty class with Views as follows:

Calling the macro IlvRegisterPropertyClass registers the class MyProperty with the Views persistence mechanism.

You can now use this new named property as an extension of any graphic object with which it would be associated:

You have extended your graphic object’s API in a persistent manner, without subclassing the base class.