Using Events with the Spotfire® Document Model Framework API

Overview

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

For complex event handling with custom nodes, see also:

• Event Handlers in the Spotfire® API - A Minimal Example
• Advanced Event Handling with Spotfire® API

The Document Model Framework separates internal and external events. Internal events update the model to a consistent state. External events update the view to reflect the state of the model.

An event signals that a part of the document has been changed. The Document Model Framework enables you to listen to every property of the model and react to changes.

There are two general scenarios, which correspond to distinct event concepts, a distinction that is crucial to the understanding of Spotfire development:

• Internal events: One part of the document needs to react to changes in another to keep the document consistent. 

  Example: When a new column is added to a data table, a new filter has to be added to each filtering scheme.

• External events: A user interface component must be updated to reflect a document change.

Events in the phases of a transaction

Internal and external events are raised during different phases of a Transaction. A normal transaction consists of three distinct phases:

1. The model is modified. 

   Internal events are raised and internal event handlers may make additional changes to the document, until all changes have been made to the document. During this process the UI must not be updated.

2. The view is updated. 

   External events are raised and the UI is updated. During this phase the model must not be changed.

3. The undo stack is updated.
    

Events During Undo

Internal events are not raised for undo and redo actions, since no event handler should be allowed to interfere when restoring a previous state. 

External events are raised for undo and redo actions.

How to work with events

Define what the event handler should do, and then make sure that internal event handlers only modify the model, while external event handlers only update the view. If changes to both model and view will result from the event handling, use both internal and external event handlers.

Internal events

Internal events keep the model consistent. They are raised during modifications of the model. By associating an event handler to a document node, the handler can modify the document.

The crucial restriction on internal event handlers is that they may not modify any state outside of the document such as the state of a UI component.

Setting up Internal Event Handlers

• Internal event handlers are set up by overriding the DeclareInternalEventHandlers method in the DocumentNode.

  InternalEventManager

  DeclareInternalEventHandlers

• Internal event handlers are torn down automatically when the document node is removed from the document.

Each internal event handler must be associated with a document node: The node hosts the event handler: The hosting node is typically the node that should be changed in response to a change elsewhere in the document. For instance the event handler adding a filter when a new column is added, is hosted by the filter panel.

The event handler is called each time the trigger fires. If the trigger fires multiple times during a transaction then the event handler is called multiple times.

Example

Creating an internal event handler in the node that hosts the handler:

protected override DeclareInternalEventHandlers(InternalEventManager eventManager)
{
    eventManager.AddEventHandler(
        my_eventHandler,
        Trigger.CreatePropertyTrigger(
            this.otherNode,
            OtherNode.PropertyNames.X));
}

Event handlers are declared by calling the AddEventHandler method.

• The first argument specifies the event handler.
• The second argument specifies a trigger.

External events

External events make the view reflect the model, which essentially boils down to keeping the user interface updated. They are raised after all modifications to the model have been completed.

External event handlers are typically associated with a Windows Forms control and update or invalidate the control. But they may also be associated to a component that communicates with another application.

Setting up External Event Handlers

• External event handlers are set up by creating an ExternalEventManager and calling the AddEventHandlermethod.

  ExternalEventManager

  AddEventHandler

• External event handlers are torn down by disposing of the ExernalEventManager.

  ExternalEventHandler

The event handler is invoked at the end of each transaction that fired one or more event trigger: The handler is invoked only once even if several triggers fired or if one of the triggers fired multiple times.

No events are raised from nodes that have been removed from the document during the transaction even if a property on the removed node has been modified during the transaction.

As mentioned, an external event handler is not allowed to modify the document while handling the event. If you need an event handler that modifies any other aspect of the document then you should use an internal event handler.

Each control that listens to external events from the document should have an instance of ExternalEventManagerclass. The manager handles the different event handlers and any event handler should be registered in the manager.

The manager should be disposed, explictly or automatically:

• The control should dispose the manager when it is disposed. The manager will then tear down all the event handlers. This way it is not necessary to detach each individual handler.
• If the ExternalEventManager class is added to the components list of a control it needs not be explicitly disposed, because it implements the IComponent interface.

Each external event handler should be registered in the event handler manager for that control using the AddEventHandler method. The method takes an event handler and one or more event triggers.