Class DiagramEvent

A DiagramEvent represents a more abstract event than an InputEvent. They are raised on the Diagram class. One can receive such events by registering a DiagramEvent listener on a Diagram by calling Diagram.addDiagramListener. The listener function, when called, will be passed an instance of a DiagramEvent. Use the name property to decide what kind of diagram event it is. The diagram property refers to the Diagram, and you can get additional information from that, such as the Diagram.lastInput, which in turn provides information such as InputEvent.documentPoint that may be relevant for that kind of DiagramEvent.

The subject and parameter properties optionally provide additional information about the diagram event. The subject could be a collection of Parts or it could be an individual object such as a Link or a GraphObject within a Node. Everything depends on the kind of diagram event that it is.

Some DiagramEvents such as "ObjectSingleClicked" or "BackgroundDoubleClicked" are normally associated with InputEvents. Some DiagramEvents such as "SelectionMoved" or "PartRotated" are associated with the results of Tool-handled gestures or CommandHandler actions. Some DiagramEvents are not necessarily associated with any input events at all, such as "ViewportBoundsChanged", which can happen due to programmatic changes to the Diagram.position and Diagram.scale properties.

DiagramEvents that occur during a transaction may be called before the state of the whole diagram has settled down. This often means that such events occur before a layout, so nodes may not have their final positions, links may not have their final routes, and the Diagram.documentBounds and Diagram.viewportBounds may not yet have been updated. Such events may make additional changes to the diagram, which may in turn result in additional side-effects.

DiagramEvents that occur outside of a transaction require you to start and commit a transaction around any side-effects that you want to do. However, some DiagramEvents do not allow you to make any changes to the Diagram or Model.

Currently defined diagram event names include:

• "InitialAnimationStarting", the initial AnimationManager.defaultAnimation is about to start;
  this can be useful for customizing the initial animation, see AnimationManager.initialAnimationStyle.
• "AnimationStarting", a AnimationManager.defaultAnimation is about to start;
  do not modify the Diagram or its Model in the event listener.
• "AnimationFinished", a AnimationManager.defaultAnimation just completed;
  do not modify the Diagram or its Model in the event listener.
• "BackgroundSingleClicked", a click that was not on any Part;
  if you make any changes, start and commit your own transaction.
• "BackgroundDoubleClicked", a double-click that was not on any Part;
  if you make any changes, start and commit your own transaction.
• "BackgroundContextClicked", a context-click that was not on any Part;
  if you make any changes, start and commit your own transaction.
• "ChangingSelection", an operation is about to change the Diagram.selection collection,
  which is also the value of the DiagramEvent.subject;
  do not make any changes to the selection or the diagram in the event listener; note that just setting Part.isSelected will not raise this event, but tools and commands will.
• "ChangedSelection", an operation has just changed the Diagram.selection collection,
  which is also the value of the DiagramEvent.subject;
  do not make any changes to the selection or the diagram in the event listener; note that just setting Part.isSelected will not raise this event, but tools and commands will.
• "ClipboardChanged", Parts have been copied to the clipboard by CommandHandler.copySelection;
  the DiagramEvent.subject is the collection of Parts;
  if you make any changes, start and commit your own transaction.
• "ClipboardPasted", Parts have been copied from the clipboard into the Diagram by CommandHandler.pasteSelection;
  the DiagramEvent.subject is the Diagram.selection,
  and this is called within a transaction.
• "DocumentBoundsChanged", the area of the diagram's Parts, Diagram.documentBounds, has changed;
  the DiagramEvent.parameter is the old Rect
• "ExternalObjectsDropped", Parts have been copied into the Diagram by drag-and-drop from outside of the Diagram;
  the DiagramEvent.subject is the set of Parts that were dropped (which is also the Diagram.selection), the DiagramEvent.parameter is the source Diagram, and this is called within a transaction. If you choose, you can cancel the drop by executing: e.diagram.toolManager.draggingTool.transactionResult = null;
• "GainedFocus", the diagram has gained keyboard focus, such as after a call to Diagram.focus.
• "InitialLayoutCompleted", the whole diagram layout has updated for the first time since a major change to the Diagram, such as replacing the Model;
  if you make any changes, you do not need to perform a transaction.
• "LayoutCompleted", the whole diagram layout has just been updated;
  if you make any changes, you do not need to perform a transaction.
• "LinkDrawn", the user has just created a new Link using LinkingTool;
  the DiagramEvent.subject is the new Link,
  and this is called within a transaction.
• "LinkRelinked", the user has just reconnected an existing Link using RelinkingTool or DraggingTool;
  the DiagramEvent.subject is the modified Link,
  the DiagramEvent.parameter is the GraphObject port that the link was disconnected from,
  and this is called within a transaction.
• "LinkReshaped", the user has just rerouted an existing Link using LinkReshapingTool;
  the DiagramEvent.subject is the modified Link,
  the DiagramEvent.parameter is the List of Points of the link's original route, and this is called within a transaction.
• "LostFocus", the diagram has lost keyboard focus, a.k.a. "blur".
• "Modified", the Diagram.isModified property has been set to a new value -- useful for marking a window as having been modified since the last save;
  do not modify the Diagram or its Model in the event listener.
• "ObjectSingleClicked", a click that occurred on a GraphObject;
  the DiagramEvent.subject is the GraphObject;
  if you make any changes, start and commit your own transaction.
• "ObjectDoubleClicked", a double-click that occurred on a GraphObject;
  the DiagramEvent.subject is the GraphObject;
  if you make any changes, start and commit your own transaction.
• "ObjectContextClicked", a context-click that occurred on a GraphObject;
  the DiagramEvent.subject is the GraphObject;
  if you make any changes, start and commit your own transaction.
• "PartCreated", the user inserted a new Part by ClickCreatingTool;
  the DiagramEvent.subject is the new Part,
  and this is called within a transaction.
• "PartResized", the user has changed the size of a GraphObject by ResizingTool;
  the DiagramEvent.subject is the GraphObject,
  the DiagramEvent.parameter is the original Size,
  and this is called within a transaction.
• "PartRotated", the user has changed the angle of a GraphObject by RotatingTool;
  the DiagramEvent.subject is the GraphObject,
  the DiagramEvent.parameter is the original angle in degrees,
  and this is called within a transaction.
• "SelectionMoved", the user has moved selected Parts by DraggingTool;
  the DiagramEvent.subject is a Set of the moved Parts,
  and this is called within a transaction.
• "SelectionCopied", the user has copied selected Parts by DraggingTool;
  the DiagramEvent.subject is Set of the newly copied Parts,
  and this is called within a transaction.
• "SelectionDeleted", the user has deleted selected Parts by CommandHandler.deleteSelection;
  the DiagramEvent.subject is the collection of Parts that were deleted,
  and this is called within a transaction.
• "SelectionDeleting", the user is about to delete selected Parts by CommandHandler.deleteSelection;
  the DiagramEvent.subject is the Diagram.selection collection of Parts to be deleted,
  and this is called within a transaction.
• "SelectionGrouped", the user has made a new Group out of the selected Parts by CommandHandler.groupSelection;
  the DiagramEvent.subject is the new Group,
  and this is called within a transaction.
• "SelectionUngrouped", the user has removed a selected Group but kept its members by CommandHandler.ungroupSelection;
  the DiagramEvent.subject is the collection of Groups that were ungrouped,
  the DiagramEvent.parameter is the collection of former member Parts that were ungrouped,
  and this is called within a transaction.
• "SubGraphCollapsed", the user has collapsed selected Groups by CommandHandler.collapseSubGraph;
  the DiagramEvent.subject is the collection of Groups that were collapsed,
  and this is called within a transaction.
• "SubGraphExpanded", the user has expanded selected Groups by CommandHandler.expandSubGraph;
  the DiagramEvent.subject is the collection of Groups that were expanded,
  and this is called within a transaction.
• "TextEdited", the user has changed the string value of a TextBlock by TextEditingTool;
  the DiagramEvent.subject is the edited TextBlock,
  the DiagramEvent.parameter is the original string,
  and this is called within a transaction.
• "ThemeChanged", the diagram's theme has changed, maybe as a result of setting ThemeManager.currentTheme or calling ThemeManager.set.
• "TreeCollapsed", the user has collapsed selected Nodes with subtrees by CommandHandler.collapseTree;
  the DiagramEvent.subject is the collection of Nodes that were collapsed,
  and this is called within a transaction.
• "TreeExpanded", the user has expanded selected Nodes with subtrees by CommandHandler.expandTree;
  the DiagramEvent.subject is the collection of Nodes that were expanded,
  and this is called within a transaction.
• "ViewportBoundsChanged", the visible area of the Diagram, Diagram.viewportBounds, has changed;
  the DiagramEvent.subject is an object whose "scale" property is the old Diagram.scale value, whose "position" property is the old Diagram.position value, whose "bounds" property is the old Diagram.viewportBounds value, whose "canvasSize" property is the old size of the Diagram.div, and whose "newCanvasSize" property is the new size of the Diagram.div, the DiagramEvent.parameter is also the old viewportBounds Rect.