Using Event Triggers with the Spotfire® Document Model Framework API

Overview

This page describes how to use event triggers with the Spotfire® Document Model Framework API.

Event triggers specify the modifications that shall invoke specific event handlers.

A trigger fires when the conditions are fulfilled. There are different kinds of event triggers expressing different conditions, and triggers can be combined to handle complex conditions.

• Trigger class

To exemplify the use of triggers, the DataTable – DataColumnCollection – DataColumn – RowValues class hierarchy will be considered:

• A Property Trigger will be used to determine when columns are added or removed, that is when the Items property of the DataColumnsCollection is changed. This is indicated by the red rectangle.
   
• A Sub Tree Trigger will be used to determine when RowValues in the DataColumnCollection is changed. This is indicated by the green rectangle.
   
• A Mutable Trigger will be used to determine when a single RowValues object is altered, but in this case the trigger will be implemented for a node that references the RowValues from somewhere else in the tree. This is indicated by a blue rectangle,
   
• A Composite Triggers, finally, enables you to combine triggers.

Property Names

Every public property in the document has an associated identity, its property name. Property names are used to specify the properties that trigger a particular event handler, that invokes it.

The property names of a particular document node type are available as members of an inner class called PropertyNames. Consider the DataColumnCollection on a DataTable: It has an Items property.

Example

Accessing the Items property name:

 DataColumnCollection.PropertyNames.Items

Property Triggers

• CreatePropertyTrigger method

A Property Trigger is the simplest event trigger. It specifies that the event shall be triggered when one or more properties of a specified document node is modified.

Example

Defining a trigger which fires when columns in the DataColumnCollection are added or removed:

 Trigger.CreatePropertyTrigger(
     dataTable.Columns,
     DataColumnCollection.PropertyNames.Items);

Sub Tree Triggers

• CreateSubTreeTrigger method

A sub tree trigger fires when any property in an entire sub tree is modified.

Example

Defining a sub tree trigger that fires when any row value in any DataColumn in DataColumnCollection changes.

 Trigger.CreateSubTreeTrigger(
     dataTable.Columns,
     typeof(DataColumn),
     DataColumn.PropertyNames.RowValues);

• The first parameter to the constructor specifies the sub tree to be considered.
• The second parameter specifies the node type to be considered in that sub tree, here nodes of DataColumn type.
• The third parameter specifies triggering on the RowValues property.

Note: It is possible to specify several property names in the same sub tree trigger. The trigger will fire if any of the properties are modified.

Mutable Property Triggers

• CreateMutablePropertyTrigger methods

You often need to listen to a property of a document node that you have a reference to. There are two cases: Either you have a CrossReferenceProperty to another node, or you have an owning reference through an UndoableProperty. Triggering on a property in such a referred node requires a mutable property trigger, a trigger type that can be nested to solve complicated scenarios.

Example

Consider a custom visualization that references a column as XAxis. This is implemented as an instance of UndoableCrossReferenceProperty<DataColumn>. Suppose you want to know when the values in the column assigned to the X axis change. This must be a mutable property trigger since the X axis column may change.

Trigger.CreateMutablePropertyTrigger<DataColumn>(
    xAxisColumnReference,
    CustomVisualization.PropertyNames.XAxisReference,
    delegate(DataColumn dataColumn)                 
    {
        return Trigger.CreatePropertyTrigger(
            dataColumn,
            DataColumn.PropertyNames.RowValues);
    });

• The first parameter specifies the node which holds the cross reference.
• The second parameter is the name of the property with the cross reference. 
• Recommendation: Add a postfix Reference to the property name of the UndoableCrossReferenceProperty. This convention indicates the need for a mutable property trigger.
• The third parameter is a delegate specifying what to listen to on the referred node, in this case the X property. 
• The delegate may specify any kind of trigger. It can use sub tree triggers as well as another mutable property trigger. Using nested mutable property triggers it can even listen through chains of cross-references, for instance listening to a property of the active plot on the active page.

Composite Triggers

• CreateCompositeTrigger method

A composite trigger combines two or more triggers. It fires if any of its components triggers fire. They are convenient when an event shall be raised, either if a collection is modified, or if a property of any node in the collection is modified.

Example

Defining a trigger that fires, either if a column is added or removed, or if any row value in any column changes:

Trigger.CreateCompositeTrigger(
    Trigger.CreatePropertyTrigger(
        dataTable.Columns,
        DataColumnCollection.PropertyNames.Items),
    Trigger.CreateSubTreeTrigger(
        dataTable.Columns,
        typeof(DataColumn),
        DataColumn.PropertyNames.RowValues));