Property Aggregation

The iTools property aggregation mechanism allows the properties of several different objects held by the same container object to be displayed in the same property sheet automatically. Without property aggregation, you would have to manually register all of the properties of the objects contained in your visualization type object.

Aggregate the properties of contained objects using the Aggregate method of the IDLitVisualization class:

self->Aggregate, Object_Reference

where Object_Reference is a reference to the object whose properties you want aggregated into the visualization object. A typical property aggregation call looks like the following:

self._oSymbol = OBJ_NEW('IDLitSymbol', PARENT = self) 
self->Aggregate, self._oSymbol

Here, the first line creates an IDLitSymbol object and stores it in the _oSymbol field of the visualization object's class structure. The second line calls the Aggregate method with the object reference to the IDLitSymbol object as the argument. After the call to the Aggregate method, all registered properties of the IDLitSymbol object will be exposed in the property sheet for the visualization itself.

Note
The IDLitVisualization::Add method includes an AGGREGATE keyword. This keyword is simply a shorthand method of aggregating the properties of an object during the call to the Add method, eliminating the need to call the Aggregate method separately. The call

self->Add, Object_Reference, /AGGREGATE
is the same as the following two calls:

self->Add, Object_Reference self->Aggregate, Object_Reference

Warning
Take care when naming properties of objects that will be aggregated into a custom visualization. If the complete name of a property in one of the aggregated objects matches the prefix of the name of a property in another of the aggregated objects, IDL will display an "Ambiguous keyword abbreviation" error when the aggregate object is instantiated. To combine objects with ambiguous property names, you must manually register only the unambiguous property names with each object before calling the Aggregate method or using the AGGREGATE keyword.

Working with Aggregated Properties

When the properties of multiple objects are aggregated in a visualization object, there are two possible ways to display the combined property set: a union or an intersection. The way aggregated properties are displayed by a given visualization depends on the value of the visualization's PROPERTY_INTERSECTION property: by default, this property is not set (it contains a value of 0), and the union of the aggregated properties is displayed. If PROPERTY_INTERSECTION is set to 1 when the visualization object is created, the intersection of the aggregated properties is displayed. The following sections explain the behavior of the property sheet interface in both situations.

Union

By default, a visualization object displays the union of the properties of any aggregated objects. Properties are displayed in the property sheet interface as follows:

All of the unique properties of all of the aggregated objects are displayed.

Only one instance of a given property is displayed. This means that if multiple objects have the same property, this property will be displayed only once, and all objects will have the same property value.

The visualization will appear in iTool browsers as a single object — the aggregated objects will not be visible in the browser hierarchy.

Intersection

If the PROPERTY_INTERSECTION property is set when the visualization is created, the visualization object displays the intersection of any aggregated objects. Properties are displayed in the property sheet interface as follows:

Only properties that are common to all of the aggregated objects are displayed as properties of the visualization object. Changing the value of a common property in the visualization's property sheet changes the value for all aggregated objects.

The visualization will appear in iTool browsers as a container object — the aggregated objects will be visible beneath the visualization object in the browser hierarchy (unless the property's HIDE attribute is set, in which case the property will not be displayed). Selecting an individual aggregated object in the browser hierarchy will display that object's own properties.

If the value of a property that is common to all of the aggregated objects is different for different objects, the value will show in the parent container's property sheet as undefined.