Properties

Property locking

During rendering, all properties can be considered in a locked state. This means that the host application can still modify property values, but these new values will not be available to the visualization until the next render operation. This ensures that in your visualization you can rely on a property value during for instance a long running animation.

If the visualization needs to have synchronous access to properties, use properties.peek. This returns the value of the property that was set by a hosting application without caring about locking.

Another way to get synchronous access to a property value is to override the updateProperty method. This method is called directly when the property value changes and no locking is applied. A visualization typically uses the updateProperty method only if it wants to update the active state of properties based on the value of other properties.

Property values

If you want to retrieve the value of a property, you can call the get method on the properties object. The get function returns the property value as either a native type (for number, string and boolean) or an object (for color, font, length, and palette).

javascript
var ticks = this.properties.get( "numTicks" );
assert( typeof ticks === "number" );

var title = this.properties.get( "title" );
assert( typeof title === "string" );

var color = this.properties.get( "backgroundColor" );
assert( typeof color = "string" );

Dirty properties

When a hosting application changes the value of a property, then that property becomes dirty. The property will remain dirty until after the next render operation. This gives a visualization the opportunity to process dirty properties during update. The dirty state of a property can be retrieved by calling properties.getDirty(). In some cases, rendering performance can be optimized by only processing properties that changed since the last update operation.

Active & inactive properties

A property can be marked as active or inactive. The active state of a property is an indication for a host whether it should show the property in the UI as enabled or disabled.

The visualization can control the active state of a property through the properties.setActive() method, or retrieve the active state of a property using properties.isActive(). Typically, properties should be made active or disabled in the updateProperty method of Renderbase. This method is called at initialization time of the visualization and each time a property changes its value. For more information and a code sample, see updateProperty.

Property Groups

Properties can be organized in groups and subgroups. This allows the hosting application to show this group organization in the UI. Any number of groups and subgroups is possible, but it is recommended to stick with a limited grouping depth.

There are two built-in property groups that are called visualization and text. These groups have a special meaning to the hosting application. If both these groups are available, then a set of automatically generated legend properties, are added to these two groups. If either of these groups is not available, then a new group that is called legend is generated and used for the automatically generated legend properties.

The only party that is interested in property groups is the hosting application. Therefore, the RenderBase implementation does not have access to property groups. The only thing the visualization developer does is define the property groups in the Visualization definition.