ChangedEvent class

A ChangedEvent represents a change to an object, typically a GraphObject, but also for model data, a Model, or a Diagram. The most common case is for remembering the name of a property and the before-and-after values for that property.

You can listen for changed events on the model using Model#addChangedListener or Diagram#addModelChangedListener, and on the Diagram using Diagram#addChangedListener.

There are four kinds of changes, represented by enumerated values: ChangedEvent.Property (the most common), ChangedEvent.Insert and ChangedEvent.Remove (to represent inserting or removing objects from collections), and ChangedEvent.Transaction (to notify about beginning or ending transactions or undo or redo).

The most common kind of ChangedEvent is a Property change. The name of the property is given by #propertyName. The modified object is given by #object. Use the #oldValue and #newValue properties for the before and after property values.

For an Insert ChangedEvent, the modified collection (often an Array) is a property value on the #object. The #propertyName helps distinguish between different collections on the object. Use the #newValue property to indicate the value that was inserted. Use the #newParam property to indicate where or how, such as an array index or dictionary key.

For a Remove ChangedEvent, the modified collection is a property value on the #object. The #propertyName helps distinguish between different collections on the object. Use the #oldValue property to indicate the value that was removed. Use the #oldParam property to indicate where or how, such as an array index or dictionary key.

Transaction ChangedEvents are generated by the UndoManager. The #propertyName names the nature of the ChangedEvent. For the very first transaction, the property name is "StartingFirstTransaction". This ChangedEvent precedes a ChangedEvent whose property name is "StartedTransaction", which occurs for every top-level transaction.

When ending a transaction, there is first a ChangedEvent whose name is "ComittingTransaction". This is followed by one with either "CommittedTransaction" or "RolledBackTransaction", depending on how the transaction is ending. The #oldValue provides the transaction name and the #object is the Transaction being finished. (Note that the Transaction value may be null if no Transaction is available at that time, perhaps because there were no changes made during the transaction.) That Transaction can be scanned to look for ChangedEvents that you may wish to record in a database, all within a single database transaction.

There are also Transaction ChangedEvents corresponding to "StartingUndo", "FinishedUndo", "StartingRedo", and "FinishedRedo". The #object property provides the Transaction that is about-to-be or just-was undone or redone.

Non-Transaction ChangedEvents are remembered by the UndoManager, if UndoManager#isEnabled, and held in the UndoManager#history as Transactions which hold lists of ChangedEvents. That is why ChangedEvent implements #undo and #redo of the change that it remembers.

When the ChangedEvent represents a change to a Model, the value of #model is non-null and the value of #diagram is meaningless. If the change is a structural change to the model, the value of #modelChange indicates the kind of change. Currently defined model changed event names include:

  • "nodeDataArray", after the model's Model#nodeDataArray is replaced, inserted into or removed from (setting Model#nodeDataArray or calling Model#addNodeData or Model#removeNodeData)
  • "nodeKey", after changing a node data's unique key (Model#setKeyForNodeData)
  • "nodeCategory", after changing a node data's category (Model#setCategoryForNodeData)
  • "linkDataArray", after the model's GraphLinksModel#linkDataArray is replaced, inserted into or removed from (setting GraphLinksModel#linkDataArray or calling GraphLinksModel#addLinkData or GraphLinksModel#removeLinkData)
  • "linkKey", after changing a link data's unique key (GraphLinksModel#setKeyForLinkData)
  • "linkCategory", after changing a link data's category (GraphLinksModel#setCategoryForLinkData)
  • "linkFromKey", after changing a link data's "from" node key (GraphLinksModel#setFromKeyForLinkData)
  • "linkToKey", after changing a link data's "to" node key (GraphLinksModel#setToKeyForLinkData)
  • "linkFromPortId", after changing a link data's "from" port identifier string (GraphLinksModel#setFromPortIdForLinkData)
  • "linkToPortId", after changing a link data's "to" port identifier string (GraphLinksModel#setToPortIdForLinkData)
  • "linkLabelKeys", after replacing, inserting into, or removing from a link data's array of keys to label nodes (calling GraphLinksModel#setLabelKeysForLinkData, GraphLinksModel#addLabelKeyForLinkData, or GraphLinksModel#removeLabelKeyForLinkData)
  • "nodeGroupKey", after changing a node data's key for a containing group data (GraphLinksModel#setGroupKeyForNodeData)
  • "nodeParentKey", after changing a node data's "parent" node key (TreeModel#setParentKeyForNodeData)
  • "parentLinkCategory", after changing a node data's "parent" link's category(TreeModel#setParentLinkCategoryForNodeData)
  • other names are for internal implementation use only, only on Transaction ChangedEvents

The value of ChangedEvent#propertyName indicates the actual name of the property that was modified. ChangedEvent#modelChange is a non-empty string only when there is a known structural change to the model, not just the setting of some property on some object.

When the ChangedEvent represents a change to a Diagram or a GraphObject within a diagram, the value of #diagram is non-null and the values of #model and #modelChange are meaningless.

Please note that ChangedEvents can be raised for many different causes. You may not be interested in changes to temporary objects -- in that case ignore the ChangedEvent when Model#skipsUndoManager or Diagram#skipsUndoManager is true.

Available Extensions
Annotations
  • @JS()
  • @staticInterop

Constructors

ChangedEvent()
factory

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

insert ↔ EnumValue
For inserting into collections, and used as the value for ChangedEvent#change. The modified object is given by ChangedEvent#object. Use the optional ChangedEvent#propertyName to distinguish between different collections on the object. Use the ChangedEvent#newValue property to indicate the value that was inserted. Use the optional ChangedEvent#newParam property to indicate where or how, such as an array index or dictionary key.
getter/setter pair
property ↔ EnumValue
For simple property changes, and used as the value for ChangedEvent#change. The name of the property is given by ChangedEvent#propertyName. The modified object is given by ChangedEvent#object. Use the ChangedEvent#oldValue and ChangedEvent#newValue properties for the previous and next property values.
getter/setter pair
remove ↔ EnumValue
For removing from collections, and used as the value for ChangedEvent#change. The modified object is given by ChangedEvent#object. Use the optional ChangedEvent#propertyName to distinguish between different collections on the object. Use the ChangedEvent#oldValue property to indicate the value that was removed. Use the optional ChangedEvent#oldParam property to indicate where or how, such as an array index or dictionary key.
getter/setter pair
transaction ↔ EnumValue
For informational events, such as transactions and undo/redo operations, and used as the value for ChangedEvent#change. The ChangedEvent#object refers to the Transaction affected, if any. The ChangedEvent#propertyName distinguishes the different transaction or undo or redo stages. The ChangedEvent#oldValue may provide the transaction name, if available, as given to UndoManager#commitTransaction.
getter/setter pair