markgojs
Version:
Interactive diagrams, charts, and graphs, such as trees, flowcharts, orgcharts, UML, BPMN, or business diagrams
1,192 lines (267 loc) • 322 kB
HTML
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="generator" content="JsDoc Toolkit" />
<title>GoJS® Reference - Index</title>
<script src="../assets/js/jquery.min.js"></script>
<script src="../assets/js/bootstrap.min.js"></script>
<script src="../assets/js/highlight.js"></script>
<script src="../assets/js/api.js"></script>
<script src="../assets/js/fuse.min.js"></script>
<link href="../assets/css/bootstrap.min.css" rel="stylesheet" >
<!-- custom CSS after bootstrap -->
<link href="../assets/css/main.css" rel="stylesheet" type="text/css"/>
<link href="../assets/css/api.css" rel="stylesheet" type="text/css"/>
<link rel="stylesheet" href="../assets/css/highlight.css" type="text/css" media="all" />
</head>
<body>
<!-- non-fixed navbar -->
<nav id="non-fixed-nav" class="navbar navbar-inverse navbar-top">
<div class="container-fluid">
<div class="navbar-header">
<div class="navheader-container">
<div class="navheader-collapse" data-toggle="collapse" data-target="#navbar">
<a id="toplogo" class="navbar-brand" href="../index.html">GoJS</a>
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
</div>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav navbar-right">
<li><a href="../index.html">Home</a></li>
<li><a href="../learn/index.html">Learn</a></li>
<li><a href="../samples/index.html">Samples</a></li>
<li><a href="../intro/index.html">Intro</a></li>
<li><a href="../api/index.html">API</a></li>
<li><a href="https://www.nwoods.com/components/evalform.htm">Register</a></li>
<li><a href="../download.html">Download</a></li>
<li><a href="https://forum.nwoods.com/c/gojs">Forum</a></li>
<li><a href="https://www.nwoods.com/contact.html" onclick="ga('send','event','Outbound Link','click','contact');">Contact</a></li>
<li class="buy"><a href="https://www.nwoods.com/sales/index.html" onclick="ga('send','event','Outbound Link','click','buy');">Buy</a></li>
<li class="activate"><a href="https://www.nwoods.com/app/activate.aspx?sku=gojs">Activate</a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
</nav>
<div class="container-fluid">
<div id="navindex" class="col-md-2">
<!-- <div><a href="index.html">GoJS Class Index</a></div> -->
<div class="sidebar-nav">
<div class="navbar navbar-default" role="navigation">
<div class="navbar-header">
<div class="navheader-container">
<div class="navheader-collapse" data-toggle="collapse" data-target="#DiagramNavbar">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#DiagramNavbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<span class="navbar-brand">Diagram Classes</span>
</div>
</div>
<div id="DiagramNavbar" class="navbar-collapse collapse sidebar-navbar-collapse">
<ul class="classList nav navbar-nav">
<li><a href="symbols/Adornment.html" class="linkConstructor">Adornment</a></li>
<li><a href="symbols/AnimationManager.html" class="linkConstructor">AnimationManager</a></li>
<li><a href="symbols/CommandHandler.html" class="linkConstructor">CommandHandler</a></li>
<li><a href="symbols/Diagram.html" class="linkConstructor">Diagram</a></li>
<li><a href="symbols/DiagramEvent.html" class="linkConstructor">DiagramEvent</a></li>
<li><a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a></li>
<li><a href="symbols/Group.html" class="linkConstructor">Group</a></li>
<li><a href="symbols/InputEvent.html" class="linkConstructor">InputEvent</a></li>
<li><a href="symbols/Layer.html" class="linkConstructor">Layer</a></li>
<li><a href="symbols/Link.html" class="linkConstructor">Link</a></li>
<li><a href="symbols/Node.html" class="linkConstructor">Node</a></li>
<li><a href="symbols/Overview.html" class="linkConstructor">Overview</a></li>
<li><a href="symbols/Palette.html" class="linkConstructor">Palette</a></li>
<li><a href="symbols/Panel.html" class="linkConstructor">Panel</a></li>
<li><a href="symbols/Part.html" class="linkConstructor">Part</a></li>
<li><a href="symbols/Picture.html" class="linkConstructor">Picture</a></li>
<li><a href="symbols/Placeholder.html" class="linkConstructor">Placeholder</a></li>
<li><a href="symbols/RowColumnDefinition.html" class="linkConstructor">RowColumnDefinition</a></li>
<li><a href="symbols/Shape.html" class="linkConstructor">Shape</a></li>
<li><a href="symbols/TextBlock.html" class="linkConstructor">TextBlock</a></li>
</ul>
</div>
</div>
<div class="navbar navbar-default" role="navigation">
<div class="navbar-header">
<div class="navheader-container">
<div class="navheader-collapse" data-toggle="collapse" data-target="#GeometryNavbar">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#GeometryNavbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<span class="navbar-brand">Geometry Classes</span>
</div>
</div>
<div id="GeometryNavbar" class="navbar-collapse collapse sidebar-navbar-collapse">
<ul class="classList nav navbar-nav">
<li><a href="symbols/Brush.html" class="linkConstructor">Brush</a></li>
<li><a href="symbols/Geometry.html" class="linkConstructor">Geometry</a></li>
<li><a href="symbols/Margin.html" class="linkConstructor">Margin</a></li>
<li><a href="symbols/PathFigure.html" class="linkConstructor">PathFigure</a></li>
<li><a href="symbols/PathSegment.html" class="linkConstructor">PathSegment</a></li>
<li><a href="symbols/Point.html" class="linkConstructor">Point</a></li>
<li><a href="symbols/Rect.html" class="linkConstructor">Rect</a></li>
<li><a href="symbols/Size.html" class="linkConstructor">Size</a></li>
<li><a href="symbols/Spot.html" class="linkConstructor">Spot</a></li>
</ul>
</div>
</div>
<div class="navbar navbar-default" role="navigation">
<div class="navbar-header">
<div class="navheader-container">
<div class="navheader-collapse" data-toggle="collapse" data-target="#ModelNavbar">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#ModelNavbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<span class="navbar-brand">Model Classes</span>
</div>
</div>
<div id="ModelNavbar" class="navbar-collapse collapse sidebar-navbar-collapse">
<ul class="classList nav navbar-nav">
<li><a href="symbols/Binding.html" class="linkConstructor">Binding</a></li>
<li><a href="symbols/ChangedEvent.html" class="linkConstructor">ChangedEvent</a></li>
<li><a href="symbols/GraphLinksModel.html" class="linkConstructor">GraphLinksModel</a></li>
<li><a href="symbols/Model.html" class="linkConstructor">Model</a></li>
<li><a href="symbols/Transaction.html" class="linkConstructor">Transaction</a></li>
<li><a href="symbols/TreeModel.html" class="linkConstructor">TreeModel</a></li>
<li><a href="symbols/UndoManager.html" class="linkConstructor">UndoManager</a></li>
</ul>
</div>
</div>
<div class="navbar navbar-default" role="navigation">
<div class="navbar-header">
<div class="navheader-container">
<div class="navheader-collapse" data-toggle="collapse" data-target="#LayoutNavbar">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#LayoutNavbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<span class="navbar-brand">Layout Classes</span>
</div>
</div>
<div id="LayoutNavbar" class="navbar-collapse collapse sidebar-navbar-collapse">
<ul class="classList nav navbar-nav">
<li><a href="symbols/CircularLayout.html" class="linkConstructor">CircularLayout</a></li>
<li><a href="symbols/ForceDirectedLayout.html" class="linkConstructor">ForceDirectedLayout</a></li>
<li><a href="symbols/GridLayout.html" class="linkConstructor">GridLayout</a></li>
<li><a href="symbols/LayeredDigraphLayout.html" class="linkConstructor">LayeredDigraphLayout</a></li>
<li><a href="symbols/Layout.html" class="linkConstructor">Layout</a></li>
<li><a href="symbols/LayoutNetwork.html" class="linkConstructor">LayoutNetwork</a></li>
<li><a href="symbols/TreeLayout.html" class="linkConstructor">TreeLayout</a></li>
</ul>
</div>
</div>
<div class="navbar navbar-default" role="navigation">
<div class="navbar-header">
<div class="navheader-container">
<div class="navheader-collapse" data-toggle="collapse" data-target="#ToolNavbar">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#ToolNavbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<span class="navbar-brand">Tool Classes</span>
</div>
</div>
<div id="ToolNavbar" class="navbar-collapse collapse sidebar-navbar-collapse">
<ul class="classList nav navbar-nav">
<li><a href="symbols/ActionTool.html" class="linkConstructor">ActionTool</a></li>
<li><a href="symbols/ClickCreatingTool.html" class="linkConstructor">ClickCreatingTool</a></li>
<li><a href="symbols/ClickSelectingTool.html" class="linkConstructor">ClickSelectingTool</a></li>
<li><a href="symbols/ContextMenuTool.html" class="linkConstructor">ContextMenuTool</a></li>
<li><a href="symbols/DraggingTool.html" class="linkConstructor">DraggingTool</a></li>
<li><a href="symbols/DragSelectingTool.html" class="linkConstructor">DragSelectingTool</a></li>
<li><a href="symbols/HTMLInfo.html" class="linkConstructor">HTMLInfo</a></li>
<li><a href="symbols/LinkingBaseTool.html" class="linkConstructor">LinkingBaseTool</a></li>
<li><a href="symbols/LinkingTool.html" class="linkConstructor">LinkingTool</a></li>
<li><a href="symbols/LinkReshapingTool.html" class="linkConstructor">LinkReshapingTool</a></li>
<li><a href="symbols/PanningTool.html" class="linkConstructor">PanningTool</a></li>
<li><a href="symbols/RelinkingTool.html" class="linkConstructor">RelinkingTool</a></li>
<li><a href="symbols/ResizingTool.html" class="linkConstructor">ResizingTool</a></li>
<li><a href="symbols/RotatingTool.html" class="linkConstructor">RotatingTool</a></li>
<li><a href="symbols/TextEditingTool.html" class="linkConstructor">TextEditingTool</a></li>
<li><a href="symbols/Tool.html" class="linkConstructor">Tool</a></li>
<li><a href="symbols/ToolManager.html" class="linkConstructor">ToolManager</a></li>
</ul>
</div>
</div>
<div class="navbar navbar-default" role="navigation">
<div class="navbar-header">
<div class="navheader-container">
<div class="navheader-collapse" data-toggle="collapse" data-target="#CollectionNavbar">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#CollectionNavbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<span class="navbar-brand">Collection Classes</span>
</div>
</div>
<div id="CollectionNavbar" class="navbar-collapse collapse sidebar-navbar-collapse">
<ul class="classList nav navbar-nav">
<li><a href="symbols/Iterable.html" class="linkConstructor">Iterable</a></li>
<li><a href="symbols/Iterator.html" class="linkConstructor">Iterator</a></li>
<li><a href="symbols/List.html" class="linkConstructor">List</a></li>
<li><a href="symbols/Map.html" class="linkConstructor">Map</a></li>
<li><a href="symbols/Set.html" class="linkConstructor">Set</a></li>
</ul>
</div>
</div>
</div> <!-- /class="sidebar-nav -->
</div>
<div id="contentBody" class="col-md-10">
<div class="searchsumm">
<div class="table-wrap">
<div class="table-cell" id="apisearch" data-base="./">
<div class="title">Search API</div>
<div class="field">
<label for="search-field" class="search-icon"></label>
<input id="search-field" type="text" />
</div>
<ul class="results">
<li class="state loading">Preparing search index...</li>
<li class="state failure">The search index is not available</li>
</ul>
</div>
<div class="table-cell" id="apisumm">
<input type="checkbox" id="showsumms" />
<label class="apisumms" for="showsumms">Show Summaries</label>
</div>
</div>
</div>
<div id="header" class="fineprint">
<b>GoJS</b>® Diagramming Components<br/>version 1.8.36 for JavaScript/HTML<br/>by <a href="https://www.nwoods.com/">Northwoods Software®</a>
</div>
<h1 class="classTitle">GoJS Class Index</h1>
<div><h2><a href="symbols/ActionTool.html" class="linkConstructor">ActionTool</a></h2><p>The ActionTool is responsible for handling and dispatching mouse events on <a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a>s
that have <a href="symbols/GraphObject.html#isActionable" class="linkProperty">GraphObject.isActionable</a> set to true.<span class="nodetails" id="xActionTool"><a class="morelink" onclick="hst('ActionTool')">More...</a></span> <span class="details" id="ActionTool">
This is how one implements "controls", such as buttons or sliders or knobs, as <a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a>s
that can be inside <a href="symbols/Part.html" class="linkConstructor">Part</a>s without interfering with the standard tool behaviors.
</span><div class="details" id="dActionTool"><p>
This tool allows individual GraphObjects (usually Panels) to handle mouse-down-move-up events without
having to define new <a href="symbols/Tool.html" class="linkConstructor">Tool</a>s.
It does this by calling <a href="symbols/GraphObject.html#actionDown" class="linkProperty">GraphObject.actionDown</a>, <a href="symbols/GraphObject.html#actionMove" class="linkProperty">GraphObject.actionMove</a>, <a href="symbols/GraphObject.html#actionUp" class="linkProperty">GraphObject.actionUp</a>,
and <a href="symbols/GraphObject.html#actionCancel" class="linkProperty">GraphObject.actionCancel</a> on objects that have <a href="symbols/GraphObject.html#isActionable" class="linkProperty">GraphObject.isActionable</a> set to true.
<p>
This tool is a standard mouse-down tool, the <a href="symbols/ToolManager.html#actionTool" class="linkProperty">ToolManager.actionTool</a>.
<p>
This tool does not utilize any <a href="symbols/Adornment.html" class="linkConstructor">Adornment</a>s or tool handles.
This tool does not modify the model or conduct any transaction, although the actions that this invokes may do so.
<p>
It would be very unusual to want to customize this tool.</div></div>
<div><h2><a href="symbols/Adornment.html" class="linkConstructor">Adornment</a></h2><p>An adornment is a special kind of <a href="symbols/Part.html" class="linkConstructor">Part</a> that is associated with another Part,
the <a href="symbols/Adornment.html#adornedPart" class="linkProperty">Adornment.adornedPart</a>.<span class="nodetails" id="xAdornment"><a class="morelink" onclick="hst('Adornment')">More...</a></span> <span class="details" id="Adornment">
</span><div class="details" id="dAdornment"><p>
Adornments are normally associated with a particular <a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a> in the adorned part --
that is the value of #adornedObject.
However, the #adornedObject may be null, in which case the #adornedPart will also be null.
<p>
The area occupied by the adorned object is represented in the adornment's visual tree by a <a href="symbols/Placeholder.html" class="linkConstructor">Placeholder</a>.
The placeholder is always the <a href="symbols/Part.html#locationObject" class="linkProperty">Part.locationObject</a>,
although you may specify any <a href="symbols/Spot.html" class="linkConstructor">Spot</a> as the <a href="symbols/Part.html#locationSpot" class="linkProperty">Part.locationSpot</a>.
An adornment need not have a placeholder, but it may have at most one.
<p>
Adornments can be distinguished by their <a href="symbols/Part.html#category" class="linkProperty">Part.category</a>.
This property can be an arbitrary string value determined by the code creating the adornment,
typically a tool that wants to be able to tell various adornments apart from each other.
Use the <a href="symbols/Part.html#findAdornment" class="linkMethod">Part.findAdornment</a> method to find an adornment for a part of a given category.
<p>
For example, one of the Adornments created by <a href="symbols/Part.html#updateAdornments" class="linkMethod">Part.updateAdornments</a> when the part
<a href="symbols/Part.html#isSelected" class="linkProperty">Part.isSelected</a> has the <a href="symbols/Part.html#category" class="linkProperty">Part.category</a> of "Selection".
Those created by <a href="symbols/ResizingTool.html#updateAdornments" class="linkMethod">ResizingTool.updateAdornments</a> have a category of "Resize"
and normally contain eight resize handles.
<p>
Besides the selection adornment and tool adornments, adornments are also used for
context menus and tooltips.
The #adornedObject in such cases refers to the <a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a> to which the
the context menu or tooltip applies.
<p>
There cannot be any links connected to an adornment,
nor can an adornment have members or be a member of a group.
<p>
An adornment cannot have its own adornments.
An adornment cannot be selected.
<p>
Adornments are not positioned by a <a href="symbols/Layout.html" class="linkConstructor">Layout</a> because they are normally positioned
according to the Part that they adorn.
<p>
For more discussion and examples, see <a href="../../intro/selection.html">Selection</a>,
<a href="../../intro/toolTips.html">ToolTips</a>,
<a href="../../intro/contextMenus.html">Context Menus</a>, and
<a href="../../intro/tools.html">Tools</a>.</div></div>
<div><h2><a href="symbols/AnimationManager.html" class="linkConstructor">AnimationManager</a></h2><p>AnimationManager handles animations in a <a href="symbols/Diagram.html" class="linkConstructor">Diagram</a>.<span class="nodetails" id="xAnimationManager"><a class="morelink" onclick="hst('AnimationManager')">More...</a></span> <span class="details" id="AnimationManager"> Each Diagram has one, <a href="symbols/Diagram.html#animationManager" class="linkProperty">Diagram.animationManager</a>.
Layouts, Group expansion and Tree expansion automatically start animations.
</span><div class="details" id="dAnimationManager"><p>
Animation is enabled by default, setting the <a href="symbols/UndoManager.html#isEnabled" class="linkProperty">isEnabled</a> property to false will turn off animations for a Diagram.
<p>
When an animations begins it raises the "AnimationStarting" diagram event,
upon completion it raises the "AnimationFinished" diagram event.
<p>
Animation will stop if a new transaction is started, if an undo or redo is called,
if a layout is invalidated, or if a model is replaced.
When an animation is stopped, the Diagram immediately finishes the animation and draws the final state.
Animations can be stopped programatically with the method <a href="symbols/AnimationManager.html#stopAnimation" class="linkMethod">AnimationManager.stopAnimation</a>.</div></div>
<div><h2><a href="symbols/Binding.html" class="linkConstructor">Binding</a></h2><p>A Binding describes how to automatically set a property on a <a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a>
to a value of a property of data in the model.<span class="nodetails" id="xBinding"><a class="morelink" onclick="hst('Binding')">More...</a></span> <span class="details" id="Binding">
The target property name and the data source property name are strings.
All name matching is case-sensitive.
</span><div class="details" id="dBinding"><p>
Register bindings by calling <a href="symbols/GraphObject.html#bind" class="linkMethod">GraphObject.bind</a> with a new Binding.
Existing bindings become read-only, and no new bindings may be added,
when a template (a <a href="symbols/Part.html" class="linkConstructor">Part</a>) is copied.
Bindings will be shared by all copies of the template's GraphObjects.
<p>
For example, your node data might be like:
<pre>
{ key: 23, say: "hello!" }
</pre>
<p>
Your simple node template might be like:
<pre>
var template = new go.Node(go.Panel.Auto);
// . . . define the rest of the Node's visual tree . . .
var txt = new go.TextBlock();
txt.bind(new go.Binding("text", "say"));
template.add(txt);
myDiagram.nodeTemplate = template;
</pre>
Using <a>GraphObject.make</a> it might look like:
<pre>
var $ = go.GraphObject.make;
myDiagram.nodeTemplate =
$(go.Node, "Auto",
. . .
$(go.TextBlock, new go.Binding("text", "say"))
)
</pre>
<p>
The data binding causes the <a href="symbols/TextBlock.html#text" class="linkProperty">TextBlock.text</a> property of
the TextBlock to be set to the value of the data's "say" property.
If the value of the "say" property of a particular data object is undefined,
the binding is not evaluated: the target property is not set.
If there is an error with the binding, you may see a message in the console log.
For this reason you may want to explicitly set the initial value for a property
when defining the GraphObject, since that value will remain as the default value
if the Binding is not evaluated.
<p>
Bindings are not necessarily evaluated in any particular order.
Binding sources should not be (or depend in a conversion function on) the category of the data
if you might be modifying the category (e.g. by calling <a href="symbols/Model.html#setCategoryForNodeData" class="linkMethod">Model.setCategoryForNodeData</a>),
because then some bindings might be evaluated before or after the category has been changed.
<h4>Conversions</h4>
Sometimes the data value needs to be modified or converted in order
to be used as the new value of a <a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a> property.
The most common conversion functions are provided for you --
they convert a string to a geometric class:
<a href="symbols/Point.html#.parse" class="linkStatic">Point.parse</a>, <a href="symbols/Size.html#.parse" class="linkStatic">Size.parse</a>, <a href="symbols/Rect.html#.parse" class="linkStatic">Rect.parse</a>,
<a href="symbols/Margin.html#.parse" class="linkStatic">Margin.parse</a>, <a href="symbols/Spot.html#.parse" class="linkStatic">Spot.parse</a>, and <a href="symbols/Geometry.html#.parse" class="linkStatic">Geometry.parse</a>.
But you can easily define your own conversion function.
<p>
As an example of a conversion function, let's use a function that adds some
text prefixing the data property value:
<pre>
new go.Binding("text", "say", function(v) { return "I say: " + v; })
</pre>
Although simple conversions cover almost all binding cases, there are some infrequent uses
that are covered by "Advanced Conversions", discussed below.
Conversion functions must not have any side-effects.
Conversion functions may be called frequently, so they should be fast and avoid allocating memory.
The order in which conversion functions are called is not specified and may vary.
<h4>OneWay and TwoWay Bindings</h4>
By default bindings are <a href="symbols/Binding.html#OneWay" class="linkConstant">Binding.OneWay</a>.
OneWay bindings are evaluated when the <a href="symbols/Panel.html#data" class="linkProperty">Panel.data</a> property is set
or when you call <a href="symbols/Panel.html#updateTargetBindings" class="linkMethod">Panel.updateTargetBindings</a> or <a href="symbols/Model.html#setDataProperty" class="linkMethod">Model.setDataProperty</a>.
OneWay bindings only transfer values from the source to the target.
<p>
TwoWay bindings are evaluated in the source-to-target direction just as OneWay
bindings are evaluated.
However when the <a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a> target property is set, the TwoWay
bindings are evaluated in the target-to-source direction.
There is no point in having a TwoWay binding on a GraphObject property that cannot be set.
For efficiency, avoid TwoWay bindings on GraphObject properties that do not change value in your app.
<p>
You should not have a TwoWay binding with a source that is a node data object's key property,
i.e. on the data property whose name is the same as the value of <a href="symbols/Model.html#nodeKeyProperty" class="linkProperty">Model.nodeKeyProperty</a>.
Unintentionally changing the node key value to be the same as another node data's key value
may cause indeterminate behavior.
Furthermore, changing a node data key without changing any references to that node
using the key value will result in "dangling" references and inconsistent relationships.
You can make that change safely by calling <a href="symbols/Model.html#setKeyForNodeData" class="linkMethod">Model.setKeyForNodeData</a>,
but not via a data binding.
<p>
The target-to-source update can also go through a conversion function.
The most common back-conversion functions are provided for you.
They convert a geometric class to a string:
<a href="symbols/Point.html#.stringify" class="linkStatic">Point.stringify</a>, <a href="symbols/Size.html#.stringify" class="linkStatic">Size.stringify</a>, <a href="symbols/Rect.html#.stringify" class="linkStatic">Rect.stringify</a>,
<a href="symbols/Margin.html#.stringify" class="linkStatic">Margin.stringify</a>, <a href="symbols/Spot.html#.stringify" class="linkStatic">Spot.stringify</a>, and <a href="symbols/Geometry.html#.stringify" class="linkStatic">Geometry.stringify</a>.
<p>
It is common to want to update some data properties based on changes to the diagram.
For example, as the user changes the <a href="symbols/Part.html#location" class="linkProperty">Part.location</a> by dragging a Node,
you can automatically keep the node's model data in sync using a TwoWay binding.
<pre>
new go.Binding("location", "loc", go.Point.parse).makeTwoWay(go.Point.stringify)
</pre>
The call to <a href="symbols/Binding.html#makeTwoWay" class="linkMethod">Binding.makeTwoWay</a> changes the <a href="symbols/Binding.html#mode" class="linkProperty">Binding.mode</a>
to be <a href="symbols/Binding.html#TwoWay" class="linkConstant">Binding.TwoWay</a> and specifies the <a href="symbols/Binding.html#backConverter" class="linkProperty">Binding.backConverter</a>
function to be the <a href="symbols/Point.html#.stringify" class="linkStatic">Point.stringify</a> static function.
<p>
Because the Binding is on the whole node (<code>template</code>),
the target object is the whole <a href="symbols/Node.html" class="linkConstructor">Node</a> and the target property is "location".
The value of <code>data.loc</code> will be a string representation of the <code>Node.location</code> value.
<h4>Binding Sources</h4>
The target of a Binding is always a property of a <a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a> or a <a href="symbols/RowColumnDefinition.html" class="linkConstructor">RowColumnDefinition</a>.
The source of a Binding is normally a property of a data object in the model.
But it is also possible to have the source of a Binding be the shared JavaScript object that is the value of <a href="symbols/Model.html#modelData" class="linkProperty">Model.modelData</a>.
You can specify such a binding by calling <a href="symbols/Binding.html#ofModel" class="linkMethod">Binding.ofModel</a>, meaning "a binding of a source that is a property of the Model.modelData".
<p>
As an example, you might want all Nodes to use the same color.
It would be possible but not natural to bind to a property on the node data object, because that property would have to be
duplicated on all of the node data objects in the model, and updating the property would mean calling <a href="symbols/Model.html#setDataProperty" class="linkMethod">Model.setDataProperty</a>
on each node data object with the same new value. Furthermore if there happened to be no nodes at all in the model,
there would be no place to save the data. Hence using the shared <a href="symbols/Model.html#modelData" class="linkProperty">Model.modelData</a> object
would be the sensible place for that shared information.
<pre>
new go.Binding("stroke", "strokeColor").ofModel()
</pre>
and to set or modify that color one would just call, within a transaction:
<pre>
model.setDataProperty(model.modelData, "strokeColor", "red");
</pre>
That would cause all nodes with that model data binding to be re-evaluated.
It is not commonplace to have a TwoWay Binding on "ofModel" Bindings, but that should work.
Converters also work with "ofModel" Bindings.
<p>
And it is also possible to have the source of a Binding be another GraphObject that is in the same Part.
You can enable such a binding by calling <a href="symbols/Binding.html#ofObject" class="linkMethod">Binding.ofObject</a>, meaning "a binding of a source that is a property of a GraphObject".
You just have to make sure that object has a unique <a href="symbols/GraphObject.html#name" class="linkProperty">GraphObject.name</a> or is the Part itself.
The source property on the GraphObject has to be settable, and the Part must have a value for <a href="symbols/Panel.html#data" class="linkProperty">Panel.data</a>.
(If the source property setter does not notify about property value changes, the binding mechanism will not be invoked.
Similarly, if there is no Panel.data, the binding mechanism is not active.)
<p>
As a common kind of example of data binding between two properties of GraphObjects,
consider this Binding on a <a href="symbols/Shape.html" class="linkConstructor">Shape</a> which changes the color of the <a href="symbols/Shape.html#stroke" class="linkProperty">Shape.stroke</a>
depending on whether the Node is selected (<a href="symbols/Part.html#isSelected" class="linkProperty">Part.isSelected</a>):
<pre>
new go.Binding("stroke", "isSelected", function(s) { return s ? "dodgerblue" : "gray"; }).ofObject()
</pre>
Note the call to <a href="symbols/Binding.html#ofObject" class="linkMethod">Binding.ofObject</a>, which tells the Binding that it should use as the source
a GraphObject with a particular name. However that name argument is optional -- supplying no name
(or supplying an empty string) will cause the binding to operate with the root GraphObject.
In this case that would be the Node itself.
Now with this binding whenever the value of <a href="symbols/Part.html#isSelected" class="linkProperty">Part.isSelected</a> changes, this Shape's stroke changes color.
The conversion function is what changes the boolean "isSelected" value to a brush color specifier.
<h4>Advanced Conversions</h4>
The binding functionality also has more advanced features for less common situations.
The source property name may be an empty string, to convert the object as a whole.
Conversion functions may take a second argument that takes the object that is bound.
For source-to-target conversions, the second argument will be the <a>GraphObject</a> whose property is bound.
For target-to-source (back-)conversions, the second argument will be the source data object and
the third argument will be the <a>Model</a>.
<p>
Here's an example of a two-way data-binding using two custom conversion functions working with two separate data properties.
First we define the two conversion functions.
<pre>
function toLocation(data, node) {
return new go.Point(data.x, data.y);
};
function fromLocation(loc, data, model) {
model.setDataProperty(data, "x", loc.x);
model.setDataProperty(data, "y", loc.y);
};
</pre>
<p>
Then to data-bind the default template's <a href="symbols/Part.html#location" class="linkProperty">Part.location</a> property
to two separate data properties, "x" and "y":
<pre>
new go.Binding("location", "", toLocation).makeTwoWay(fromLocation)
</pre>
<p>
An empty string argument for the <i>sourceprop</i> parameter indicates
that the whole data object should be passed to the <code>toLocation</code> function,
rather than the value of some property of that data.
The return value is used as the new value for the <a href="symbols/Part.html#location" class="linkProperty">Part.location</a> property.
In almost all cases the second argument is not used.
Caution: for efficiency reasons you should try to avoid using an empty source property name.
Such bindings will be evaluated much more frequently than ones whose source is a particular property name.
<p>
The binding works normally for the source-to-target direction.
But when the target property is modified it is the source property that is
set with the back-converted property value from the target object.
Because in this example the source property name is the empty string,
and because one cannot replace the whole source data object,
any return value from the conversion function is ignored.
Instead the conversion function has to modify the data object directly,
as this example <code>fromLocation</code> function does.
<p>
Note that because the source property name is the empty string, the binding system will not know
which properties are modified in the call to <code>fromLocation</code>.
Hence to support undo and redo, in order to make the data changes we have to call
<a href="symbols/Model.html#setDataProperty" class="linkMethod">Model.setDataProperty</a> so that the <a href="symbols/UndoManager.html" class="linkConstructor">UndoManager</a> can record the change,
including the previous value.
<h4>Replacing Items in Arrays</h4>
However, although a TwoWay Binding cannot replace the node data object in the <a>Model.nodeDataArray</a>,
it is possible to replace an item in an <a>Panel.itemArray</a>.
So if your node data were:
<pre>{ key: 1, items: ["one", "two", "three"] }</pre>
And if your node template included something like:
<pre>
$(go.Panel, "Vertical",
new go.Binding("itemArray", "items"),
{
itemTemplate: $(go.Panel,
$(go.TextBlock, { editable: true },
new go.Binding("text", "").makeTwoWay())
)
}
)</pre>
Then the user would be able to edit any of the <a>TextBlock</a>s, causing the item Array to be modified,
for example resulting in this node data:
<pre>{ key: 1, items: ["one", "SOME NEW TEXT HERE", "three"] }</pre></div></div>
<div><h2><a href="symbols/Brush.html" class="linkConstructor">Brush</a></h2><p>A Brush holds color information and describes how to draw the inside
of a <a href="symbols/Shape.html" class="linkConstructor">Shape</a> or the stroke of a shape or a <a href="symbols/TextBlock.html" class="linkConstructor">TextBlock</a> or the
background of any <a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a>.<span class="nodetails" id="xBrush"><a class="morelink" onclick="hst('Brush')">More...</a></span> <span class="details" id="Brush">
</span><div class="details" id="dBrush"><p>
A Brush must not be modified once it has been assigned to a <a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a>,
such as the <a href="symbols/Shape.html#fill" class="linkProperty">Shape.fill</a> or <a href="symbols/TextBlock.html#stroke" class="linkProperty">TextBlock.stroke</a>
or <a href="symbols/GraphObject.html#background" class="linkProperty">GraphObject.background</a>.
However, a Brush may be shared by multiple GraphObjects.</div></div>
<div><h2><a href="symbols/ChangedEvent.html" class="linkConstructor">ChangedEvent</a></h2><p>A ChangedEvent represents a change to an object, typically a <a href="symbols/GraphObject.html" class="linkConstructor">GraphObject</a>,
but also for model data, a <a href="symbols/Model.html" class="linkConstructor">Model</a>, or a <a href="symbols/Diagram.html" class="linkConstructor">Diagram</a>.<span class="nodetails" id="xChangedEvent"><a class="morelink" onclick="hst('ChangedEvent')">More...</a></span> <span class="details" id="ChangedEvent">
The most common case is for remembering the name of a property
and the before-and-after values for that property.
</span><div class="details" id="dChangedEvent"><p>
You can listen for changed events on the model using <a href="symbols/Model.html#addChangedListener" class="linkMethod">Model.addChangedListener</a>
or <a href="symbols/Diagram.html#addModelChangedListener" class="linkMethod">Diagram.addModelChangedListener</a>, and on the Diagram using <a href="symbols/Diagram.html#addChangedListener" class="linkMethod">Diagram.addChangedListener</a>.
<p>
There are four kinds of changes, represented by enumerated values:
<a href="symbols/ChangedEvent.html#Property" class="linkConstant">ChangedEvent.Property</a> (the most common), <a href="symbols/ChangedEvent.html#Insert" class="linkConstant">ChangedEvent.Insert</a> and <a href="symbols/ChangedEvent.html#Remove" class="linkConstant">ChangedEvent.Remove</a>
(to represent inserting or removing objects from collections),
and <a href="symbols/ChangedEvent.html#Transaction" class="linkConstant">ChangedEvent.Transaction</a> (to notify about beginning or ending transactions or undo or redo).
<p>
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.
<p>
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.
<p>
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.
<p>
Transaction ChangedEvents are generated by the <a href="symbols/UndoManager.html" class="linkConstructor">UndoManager</a>.
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.
<p>
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 <a href="symbols/Transaction.html" class="linkConstructor">Transaction</a> 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.
<p>
There are also Transaction ChangedEvents corresponding to "StartingUndo", "FinishedUndo",
"StartingRedo", and "FinishedRedo".
The #object property provides the <a href="symbols/Transaction.html" class="linkConstructor">Transaction</a> that is about-to-be or just-was undone or redone.
<p>
Non-Transaction ChangedEvents are remembered by the <a href="symbols/UndoManager.html" class="linkConstructor">UndoManager</a>, if <a href="symbols/UndoManager.html#isEnabled" class="linkProperty">UndoManager.isEnabled</a>,
and held in the <a href="symbols/UndoManager.html#history" class="linkProperty">UndoManager.history</a> as <a href="symbols/Transaction.html" class="linkConstructor">Transaction</a>s which hold lists of ChangedEvents.
That is why ChangedEvent implements <a href="symbols/UndoManager.html#undo" class="linkMethod">undo</a> and <a href="symbols/UndoManager.html#redo" class="linkMethod">redo</a> of the change that it remembers.
<p>
When the ChangedEvent represents a change to a <a href="symbols/Model.html" class="linkConstructor">Model</a>, 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:
<ul>
<li><b>"nodeDataArray"</b>, after the model's <a href="symbols/Model.html#nodeDataArray" class="linkProperty">Model.nodeDataArray</a> is replaced, inserted into or removed from
(setting <a href="symbols/Model.html#nodeDataArray" class="l