Skip to main content

Event Relay

Event relays can be used to combine several events into one, or to implement a class collecting several mutable property triggers.

Overview

There are two distinct cases when event relays, available from Spotfire 2.2, should be considered:

  • Combining several events into one composite event
    Consider a document node with several internal undoable properties that should not be exposed. Another node can still listen to them using an event relay: It provides a PropertyName that fires whenever the trigger fires. A simpler event interface is exposed publicly than is really used internally.
  • Using event relays to listen through cross references
    Usually one uses a MutablePropertyTrigger when listening to events on a node that is referred by an UndoableCrossReferenceProperty. This only works when one node is referenced. It cannot handle a list of cross references. Event relays solve this problem. First, create a new class containing an undoable cross reference to the target node. Then add event relays propagating events from referenced nodes using mutable property triggers. The user of the new class can now listen to all referenced nodes using a sub tree trigger.

An event relay is created in the same pass as runtime properties by the CreateEventRelay method.

protected void CreateEventRelay(
	PropertyName propertyName, 
	StatelessDependencyDeclarer dependencyDeclarer)

Example

Add a new event to a document node for a PropertyName called Axes. The event should be raised when either of the internal property names XAxis or YAxis fires.

Assuming that the XAxis and YAxis property names are bound in the class, first define the three property names:

public new abstract class PropertyNames : DocumentNode.PropertyNames
{
    internal static readonly PropertyName XAxis = CreatePropertyName("XAxis");

    internal static readonly PropertyName YAxis = CreatePropertyName("YAxis");

    public static readonly PropertyName Axes = CreatePropertyName("Axes");
}

Next, create an InitEventRelays method and add the CreateEventRelay method call. InitEventRelays should be called from all constructors of the class, specifying that the property name Axes should be sent whenever the triggers created by AxesTrigger fire:

private void InitEventRelays()
{
    CreateEventRelay(PropertyNames.Axes, AxesTrigger);
}

Finally, the AxesTrigger is defined in the following way:

private static readonly StatelessDependencyDeclarer AxesTrigger = AxesTriggerDeclarer;
private static Trigger AxesTriggerDeclarer (DocumentNode node)
{
   return Trigger.CreatePropertyTrigger(node, PropertyNames.YAxis, PropertyNames.XAxis);
}