gojs
Version:
Interactive diagrams, charts, and graphs, such as trees, flowcharts, orgcharts, UML, BPMN, or business diagrams
574 lines (519 loc) • 23.2 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no, viewport-fit=cover"/>
<link rel="stylesheet" href="../assets/css/style.css"/>
<!-- Copyright 1998-2023 by Northwoods Software Corporation. --> <title> GoJS Collections -- Northwoods Software </title>
<link rel="stylesheet" href="../assets/css/prism.css" />
</head>
<script>
window.diagrams = [];
window.goCode = function(pre, w, h, parentid, animation) {
window.diagrams.push([pre, w, h, parentid, animation]);
}
</script>
<body>
<nav id="navTop" class="w-full z-30 top-0 text-white bg-nwoods-primary">
<div class="w-full container max-w-screen-lg mx-auto flex flex-wrap sm:flex-nowrap items-center justify-between mt-0 py-2">
<div class="md:pl-4">
<a class="text-white hover:text-white no-underline hover:no-underline
font-bold text-2xl lg:text-4xl rounded-lg hover:bg-nwoods-secondary " href="../">
<h1 class="my-0 p-1 ">GoJS</h1>
</a>
</div>
<button id="topnavButton" class="rounded-lg sm:hidden focus:outline-none focus:ring" aria-label="Navigation">
<svg fill="currentColor" viewBox="0 0 20 20" class="w-6 h-6">
<path id="topnavOpen" fill-rule="evenodd" d="M3 5a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zM3 10a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zM9 15a1 1 0 011-1h6a1 1 0 110 2h-6a1 1 0 01-1-1z" clip-rule="evenodd"></path>
<path id="topnavClosed" class="hidden" fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd"></path>
</svg>
</button>
<div id="topnavList" class="hidden sm:block items-center w-auto mt-0 text-white p-0 z-20">
<ul class="list-reset list-none font-semibold flex justify-end flex-wrap sm:flex-nowrap items-center px-0 pb-0">
<li class="p-1 sm:p-0"><a class="topnav-link" href="../learn/">Learn</a></li>
<li class="p-1 sm:p-0"><a class="topnav-link" href="../samples/">Samples</a></li>
<li class="p-1 sm:p-0"><a class="topnav-link" href="../intro/">Intro</a></li>
<li class="p-1 sm:p-0"><a class="topnav-link" href="../api/">API</a></li>
<li class="p-1 sm:p-0"><a class="topnav-link" href="https://www.nwoods.com/products/register.html">Register</a></li>
<li class="p-1 sm:p-0"><a class="topnav-link" href="../download.html">Download</a></li>
<li class="p-1 sm:p-0"><a class="topnav-link" href="https://forum.nwoods.com/c/gojs/11">Forum</a></li>
<li class="p-1 sm:p-0"><a class="topnav-link" href="https://www.nwoods.com/contact.html"
target="_blank" rel="noopener" onclick="getOutboundLink('https://www.nwoods.com/contact.html', 'contact');">Contact</a></li>
<li class="p-1 sm:p-0"><a class="topnav-link" href="https://www.nwoods.com/sales/index.html"
target="_blank" rel="noopener" onclick="getOutboundLink('https://www.nwoods.com/sales/index.html', 'buy');">Buy</a></li>
</ul>
</div>
</div>
<hr class="border-b border-gray-600 opacity-50 my-0 py-0" />
</nav>
<div class="md:flex flex-col md:flex-row md:min-h-screen w-full max-w-screen-xl mx-auto">
<div id="navSide" class="flex flex-col w-full md:w-40 lg:w-48 text-gray-700 bg-white flex-shrink-0">
<div class="flex-shrink-0 px-8 py-4">
<button id="navButton" class="rounded-lg md:hidden focus:outline-none focus:ring" aria-label="Navigation">
<svg fill="currentColor" viewBox="0 0 20 20" class="w-6 h-6">
<path id="navOpen" fill-rule="evenodd" d="M3 5a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zM3 10a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zM9 15a1 1 0 011-1h6a1 1 0 110 2h-6a1 1 0 01-1-1z" clip-rule="evenodd"></path>
<path id="navClosed" class="hidden" fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd"></path>
</svg>
</button>
</div>
<nav id="navList" class="min-h-screen hidden md:block sidebar-nav flex-grow px-1 lg:px-4 pb-4 md:pb-0 md:overflow-y-auto break-words">
<a href="index.html">Basics</a>
<a href="buildingObjects.html">Building Parts</a>
<a href="usingModels.html">Using Models</a>
<a href="dataBinding.html">Data Binding</a>
<a href="react.html">GoJS with React</a>
<a href="angular.html">GoJS with Angular</a>
<a href="textBlocks.html">TextBlocks</a>
<a href="shapes.html">Shapes</a>
<a href="pictures.html">Pictures</a>
<a href="panels.html">Panels</a>
<a href="tablePanels.html">Table Panels</a>
<a href="brush.html">Brushes</a>
<a href="sizing.html">Sizing Objects</a>
<a href="itemArrays.html">Item Arrays</a>
<a href="changedEvents.html">Changed Events</a>
<a href="transactions.html">Transactions</a>
<a href="viewport.html">Coordinates</a>
<a href="initialView.html">Initial View</a>
<a href="collections.html">Collections</a>
<a href="links.html">Links</a>
<a href="linkLabels.html">Link Labels</a>
<a href="connectionPoints.html">Link Points</a>
<a href="ports.html">Ports</a>
<a href="nodes.html">Nodes</a>
<a href="typings.html">Typings</a>
<a href="debugging.html">Debugging</a>
<a href="layouts.html">Layouts</a>
<a href="trees.html">Trees</a>
<a href="subtrees.html">SubTrees</a>
<a href="groups.html">Groups</a>
<a href="subgraphs.html">SubGraphs</a>
<a href="sizedGroups.html">Sized Groups</a>
<a href="selection.html">Selection</a>
<a href="highlighting.html">Highlighting</a>
<a href="animation.html">Animation</a>
<a href="toolTips.html">ToolTips</a>
<a href="contextmenus.html">Context Menus</a>
<a href="events.html">Diagram Events</a>
<a href="tools.html">Tools</a>
<a href="commands.html">Commands</a>
<a href="permissions.html">Permissions</a>
<a href="validation.html">Validation</a>
<a href="HTMLInteraction.html">HTML Interaction</a>
<a href="layers.html">Layers & Z-ordering</a>
<a href="palette.html">Palette</a>
<a href="overview.html">Overview</a>
<a href="resizing.html">Resizing Diagrams</a>
<a href="replacingDeleting.html">Replacing and Deleting</a>
<a href="buttons.html">Buttons</a>
<a href="templateMaps.html">Template Maps</a>
<a href="legends.html">Legends and Titles</a>
<a href="extensions.html">Extensions</a>
<a href="geometry.html">Geometry Strings</a>
<a href="grids.html">Grid Patterns</a>
<a href="graduatedPanels.html">Graduated Panels</a>
<a href="makingImages.html">Diagram Images</a>
<a href="makingSVG.html">Diagram SVG</a>
<a href="printing.html">Printing</a>
<a href="serverSideImages.html">Server-side Images</a>
<a href="nodeScript.html">GoJS in Node.js</a>
<a href="testing.html">Testing</a>
<a href="storage.html">Storage</a>
<a href="performance.html">Performance</a>
<a href="source.html">Building from Source</a>
<a href="platforms.html">Platforms</a>
<a href="deployment.html">Deployment</a>
</nav>
</div>
<div class="pt-4 px-2 md:px-0 lg:px-4 pb-16 w-full overflow-hidden">
<h1>Collections</h1>
<p>
<b>GoJS</b> provides its own collection classes: <a>List</a>, <a>Set</a>, and <a>Map</a>.
You can iterate over a collection by using an <a>Iterator</a>.
</p>
<p>
These collection classes have several advantages over using JavaScript arrays as lists or objects as maps.
They raise an error when trying to get the next item of an iterator if the collection has been modified since getting the iterator.
They can be made read-only to avoid unexpected modifications.
They offer methods not found on simple arrays or objects, such as <a>Iterator.any</a>, <a>Iterator.all</a>, and <a>Iterator.each</a>.
If you are writing in TypeScript, they optionally enforce compile-time type checking of the item types.
</p>
<p>
In <b>GoJS</b> most of the properties and methods that return collections describing the structure of the diagram return an <a>Iterator</a>.
That is because the implementation of the collections are internal -- you only need to know how to iterate over the result collection.
Other methods or properties will allow you to modify the diagram.
An example is <a>Diagram.nodes</a>, which returns the current collection of <a>Node</a>s and <a>Group</a>s in the diagram as an <a>Iterator</a>.
The collection is automatically modified as the programmer adds or removes node data in the model or by direct calls to
<a>Diagram.add</a> or <a>Diagram.remove</a>.
</p>
<p>
However there are a few properties that return collections that are allowed to be modified.
Examples include collections on classes that are usually frozen after initialization:
<a>Geometry.figures</a>, <a>PathFigure.segments</a>, and <a>Brush.colorStops</a>.
Other examples include collections that are modified very infrequently, usually only upon diagram initialization:
<a>ToolManager.mouseDownTools</a> (and the other lists of tools) and <a>Diagram.nodeTemplateMap</a>
(and other template maps).
</p>
<p>
See samples that make use of collections in the <a href="../samples/index.html#collections">samples index</a>.
</p>
<h2 id="List">List</h2>
<p>
A <a>List</a> is an ordered collection of values that are indexed by integers from zero to one less than the count.
</p>
<pre class="lang-js"><code>
const l = new go.List();
l.add("A");
l.add("B");
l.add("C");
assert(l.count === 3);
assert(l.elt(0) === "A");
assert(l.has("B"));
assert(l.indexOf("B") === 1);
l.setElt(1, "z"); // replace an item
assert(l.elt(1) === "z");
l.removeAt(1); // remove an item
assert(l.count === 2);
assert(l.elt(1) === "C");
</code></pre>
<p>
In 2.0, the optional argument to the <a>List</a> constructor has been removed.
However, if you are writing in TypeScript, GoJS collections classes (<code>List</code>, <code>Map</code>, <code>Set</code>) are now generic, and will help you enforce types:
</p>
<pre class="lang-ts"><code>
// TypeScript:
const l = new go.List<string>(); // Create a list of only strings
l.add("A");
l.add(23); // throws an error during compilation or in an IDE
l.add({}); // throws an error during compilation or in an IDE
</code></pre>
<p>
To iterate over a <a>List</a>, get its <a>List.iterator</a> and call <a>Iterator.next</a>
on it to advance its position in the list. Its <a>Iterator.value</a> will be a list item;
its <a>Iterator.key</a> will be the corresponding index in the list.
</p>
<pre class="lang-js"><code>
const l = new go.List();
l.add("A");
l.add("B");
l.add("C");
const it = l.iterator;
while (it.next()) {
console.log(it.key + ": " + it.value);
}
// This outputs:
// 0: A
// 1: B
// 2: C
// Or, if you just want to iterate over the items in the list:
l.each(item => console.log(item));
</code></pre>
<h2 id="Set">Set</h2>
<p>
A <a>Set</a> is an unordered collection of values that does not allow duplicate values.
This class is similar to the <code>Set</code> object that is defined in ECMAScript 2015 (ES6).
</p>
<p>
The optional argument to the <a>Set</a> constructor specifies the type of the items that may be added to the set.
</p>
<pre class="lang-js"><code>
const s = new go.Set();
s.add("A");
s.add("B");
s.add("C");
s.add("B"); // duplicate is ignored
assert(s.count === 3);
assert(s.has("B"));
s.remove("B"); // remove an item
assert(s.count === 2);
assert(!s.has("B"));
</code></pre>
<p>
As with <code>List</code> and <code>Map</code>, in 2.0 the optional argument to the <a>Set</a> constructor has been removed, but it is now a generic class in TypeScript and can enforce types:
</p>
<pre class="lang-ts"><code>
// TypeScript:
const s = new go.Set<string>(); // Create a set of only strings
s.add("A");
s.add(23); // throws an error during compilation or in an IDE
s.add({}); // throws an error during compilation or in an IDE
</code></pre>
<p>
Iterating over the items in a <a>Set</a> is just like iterating over a <a>List</a>,
except that the order of the items may vary.
</p>
<pre class="lang-js"><code>
const s = new go.Set();
s.add("A");
s.add("B");
s.add("C");
s.add("B"); // duplicate is ignored
const it = s.iterator;
while (it.next()) {
console.log(it.value);
}
// This might output, perhaps in different order:
// A
// B
// C
// Or, equivalent code using Set.each:
s.each(item => console.log(item));
</code></pre>
<h2 id="Map">Map</h2>
<p>
A <a>Map</a> is an unordered collection of key-value pairs that are indexed by the keys.
This class is similar to the <code>Map</code> object that is defined in ECMAScript 2015 (ES6).
</p>
<p>
The two optional arguments to the <a>Map</a> constructor specifies the types of the keys and the types of the item values that may be added to the map.
</p>
<pre class="lang-js"><code>
const m = new go.Map();
m.add("A", 1); // associate "A" with 1
m.add("B", 2);
m.add("C", 3);
assert(s.count === 3);
assert(s.has("B"));
assert(s.get("B") === 2);
m.add("B", 222); // replace the value for "B"
assert(s.get("B") === 222);
s.remove("B"); // remove an item
assert(s.count === 2);
assert(!s.has("B"));
assert(s.get("B") === null);
</code></pre>
<p>
As with <code>List</code> and <code>Set</code>, in 2.0 the optional arguments to the <a>Map</a> constructor have been removed, but it is now a generic class in TypeScript and can enforce types:
</p>
<pre class="lang-ts"><code>
// TypeScript:
const m = new go.Map<string, number>(); // Create a map of strings to numbers
m.add("A", 1);
m.add(23, 23); // throws an error during compilation or in an IDE
m.add({}, 23); // throws an error during compilation or in an IDE
</code></pre>
<p>
Iterating over the items in a <a>Map</a> is just like iterating over a <a>List</a>,
but offering access to both the keys and the values.
As with <a>Set</a>s the order of the items may vary.
</p>
<pre class="lang-js"><code>
const m = new go.Map();
m.add("A", 1); // associate "A" with 1
m.add("B", 2);
m.add("C", 3);
m.add("B", 222); // replace the value for "B"
// Normal iteration lets you get both the key and its corresponding value:
const it = m.iterator;
while (it.next()) {
console.log(it.key + ": " + it.value);
}
// This might output, perhaps in different order:
// A: 1
// B: 222
// C: 3
// Or, equivalently using Map.each:
m.each(kvp => console.log(kvp.key + ": " + kvp.value));
// To get a collection of the keys, use Map.iteratorKeys:
const kit = m.iteratorKeys;
while (kit.next()) {
console.log(kit.value);
}
// This might output, perhaps in different order:
// A
// B
// C
// To get a collection of the values, use Map.iteratorValues:
const vit = m.iteratorValues;
while (vit.next()) {
console.log(vit.value);
}
// This might output, perhaps in different order:
// 1
// 222
// 3
</code></pre>
<p>
Typically one uses <a>Map.iteratorKeys</a> or <a>Map.iteratorValues</a>
when needing to pass a collection on to other methods that take an <a>Iterator</a>.
</p>
<h2 id="MoreIterationExamples">More Iteration Examples</h2>
<p>
It is commonplace to iterate over the selected <a>Part</a>s of a <a>Diagram</a>:
<pre class="lang-js"><code>
for (const it = diagram.selection.iterator; it.next(); ) {
const part = it.value; // part is now a Node or a Group or a Link or maybe a simple Part
if (part instanceof go.Node) { . . . }
else if (part instanceof go.Link) { . . . }
}
</code></pre>
Alternatively:
<pre class="lang-js"><code>
diagram.selection.each(part => {
// part is now a Node or a Group or a Link or maybe a simple Part
if (part instanceof go.Node) { . . . }
else if (part instanceof go.Link) { . . . }
});
</code></pre>
</p>
<p>
Sometimes one needs to iterate over the <a>Node</a>s in a <a>Diagram</a>:
<pre class="lang-js"><code>
for (const it = diagram.nodes; it.next(); ) {
const n = it.value; // n is now a Node or a Group
if (n.category === "Special") { . . . }
}
</code></pre>
</p>
<p>
You can also iterate over the port elements in a <a>Node</a>, or the <a>Link</a>s connected to a port element:
<pre class="lang-js"><code>
for (const pit = node.ports; pit.next(); ) {
const port = pit.value; // port is now a GraphObject within the node
for (const lit = node.findLinksConnected(port.portId); lit.next(); ) {
const link = lit.value; // link is now a Link connected with the port
if (link.data.xyz === 17) { . . . }
}
}
</code></pre>
</p>
<p>
Or perhaps you need to iterate over the elements of a <a>Panel</a>:
<pre class="lang-js"><code>
for (const it = panel.elements; it.next(); ) {
const elt = it.value; // elt is now a GraphObject that is an immediate child of the Panel
if (elt instanceof go.TextBlock) { . . . }
else if (elt instanceof go.Panel) { . . . recurse . . . }
}
</code></pre>
</p>
<p>
If you want to find <a>Node</a>s that are immediate members of a <a>Group</a>:
<pre class="lang-js"><code>
for (const mit = group.memberParts; mit.next(); ) {
const part = mit.value; // part is now a Part within the Group
if (part instanceof go.Node) { . . . maybe work with part.data . . . }
}
</code></pre>
</p>
</div>
</div>
<div class="bg-nwoods-primary">
<section class="max-w-screen-lg text-white container mx-auto py-2 px-12">
<p id="version" class="leading-none mb-2 my-4">GoJS</p>
</section>
</div><footer class="bg-nwoods-primary text-white">
<div class="container max-w-screen-lg mx-auto px-8">
<div class="w-full py-6">
<div class="max-w-screen-lg xl:max-w-screen-xl mx-auto px-4 sm:px-6 md:px-8">
<ul class="text-sm font-medium pb-6 grid grid-cols-2 sm:grid-cols-3 gap-y-10">
<li class="list-none row-span-2">
<h2 class="text-base font-semibold tracking-wide">GoJS</h2>
<ul class="list-none space-y-4 md:space-y-1 px-0">
<li>
<a href="../samples/index.html">Samples</a>
</li>
<li>
<a href="../learn/index.html">Learn</a>
</li>
<li>
<a href="../intro/index.html">Intro</a>
</li>
<li>
<a href="../api/index.html">API</a>
</li>
<li>
<a href="../changelog.html">Changelog</a>
</li>
<li>
<a href="https://github.com/NorthwoodsSoftware/GoJS">GitHub</a>
</li>
</ul>
</li>
<li class="list-none row-span-2">
<h2 class="text-base font-semibold tracking-wide">Support</h2>
<ul class="list-none space-y-4 md:space-y-1 px-0">
<li>
<a href="https://www.nwoods.com/contact.html"
target="_blank" rel="noopener" onclick="getOutboundLink('https://www.nwoods.com/contact.html', 'contact');">Contact</a>
</li>
<li>
<a href="https://forum.nwoods.com/c/gojs">Forum</a>
</li>
<li>
<a href="https://www.nwoods.com/app/activate.aspx?sku=gojs">Activate</a>
</li>
<li>
<a href="https://www.nwoods.com/sales/index.html"
target="_blank" rel="noopener" onclick="getOutboundLink('https://www.nwoods.com/sales/index.html', 'buy');">Buy</a>
</li>
<li>
<a href="https://www.youtube.com/channel/UC9We8EoX596-6XFjJDtZIDg">Videos</a>
</li>
</ul>
</li>
<li class="list-none row-span-2">
<h2 class="text-base font-semibold tracking-wide">Company</h2>
<ul class="list-none space-y-4 md:space-y-1 px-0">
<li>
<a target="_blank" href="https://www.nwoods.com">Northwoods</a>
</li>
<li>
<a target="_blank" href="https://www.nwoods.com/about.html">About Us</a>
</li>
<li>
<a target="_blank" href="https://www.nwoods.com/contact.html">Contact Us</a>
</li>
<li>
<a target="_blank" href="https://www.nwoods.com/consulting.html">Consulting</a>
</li>
<li>
<a target="_blank" href="https://twitter.com/northwoodsgo">Twitter</a>
</li>
</ul>
</li>
</ul>
<p class="text-sm text-gray-100 md:mb-6">
Copyright 1998-2023 <a class="text-white" href="https://www.nwoods.com">Northwoods Software</a>
</p>
</div>
</div>
</footer> </body>
<script async src="https://www.googletagmanager.com/gtag/js?id=G-S5QK8VSK84"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date()); gtag('config', 'G-S5QK8VSK84');
var getOutboundLink = function(url, label) {
gtag('event', 'click', {
'event_category': 'outbound',
'event_label': label,
'transport_type': 'beacon'
});
}
// topnav
var topButton = document.getElementById("topnavButton");
var topnavList = document.getElementById("topnavList");
topButton.addEventListener("click", function() {
this.classList.toggle("active");
topnavList.classList.toggle("hidden");
document.getElementById("topnavOpen").classList.toggle("hidden");
document.getElementById("topnavClosed").classList.toggle("hidden");
});
</script>
<script src="../assets/js/prism.js"></script>
<script src="../release/go.js"></script>
<script src="../assets/js/goDoc.js"></script>
<script>
document.addEventListener("DOMContentLoaded", function() {
if (window.go) document.getElementById('version').textContent = "GoJS version " + go.version;
if (window.goDoc) window.goDoc();
var d = window.diagrams;
for (var i = 0; i < d.length; i++) {
var dargs = d[i];
goCodeExecute(dargs[0], dargs[1], dargs[2], dargs[3], dargs[4]);
}
if (window.extra) window.extra();
});
</script>
</html>