GoJS provides its own collection classes: List, Set, and Map. The latter two are very similar to the ECMAScript Set and Map classes, but iteration is quite different, using an Iterator instead of the ECMAScript Iterator protocol.
These collection classes have several advantages over using JavaScript arrays as lists or objects as maps. They can be made read-only to avoid undesired modifications. If you are writing in TypeScript, they optionally enforce compile-time type checking of the item types.
In GoJS most of the properties and methods that return collections describing the structure of the diagram return an Iterator. 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 Diagram.nodes, which returns the current collection of Nodes and Groups in the diagram as an Iterator. The collection is automatically modified as the programmer adds or removes node data in the model or by direct calls to Diagram.add or Diagram.remove.
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: Geometry.figures, PathFigure.segments, and Brush.colorStops. Other examples include collections that are modified very infrequently, usually only upon diagram initialization: ToolManager.mouseDownTools (and the other lists of tools) and Diagram.nodeTemplateMap (and other template maps).
See samples that make use of collections in the samples index.
A List is an ordered collection of values that are indexed by integers from zero to one less than the List.count.
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");
However, if you are writing in TypeScript, GoJS collections classes (List, Map, Set) are now generic, and will help you enforce types:
// TypeScript:
const l = new go.List<string>(); // Create a list of only strings
l.add("A");
l.add(23); // produces an error during compilation or highlights it in an IDE
l.add({}); // produces an error during compilation or highlights it in an IDE
To iterate over a List, get its List.iterator and call Iterator.next on it to advance its position in the list. Its Iterator.value will be a list item; its Iterator.key will be the corresponding index in the list. Or, more commonly, just call List.each.
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));
A Set is an unordered collection of values that does not allow duplicate values.
This class is similar to the Set object that is defined in ECMAScript 2015 (ES6).
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.delete("B"); // remove an item
assert(s.count === 2);
assert(!s.has("B"));
When writing TypeScript, it is a generic class so that the compiler can enforce types:
// TypeScript:
const s = new go.Set<string>(); // Create a set of only strings
s.add("A");
s.add(23); // produces an error during compilation or highlights it in an IDE
s.add({}); // produces an error during compilation or highlights it in an IDE
Iterating over the items in a Set is just like iterating over a List, except that the order of the items may vary.
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));
Furthermore, as of version 3, Set implements the ECMAScript Iterable protocol,
by defining the [Symbol.iterator] property.
This allows using the for (let item of set) ... statement.
const s = new go.Set();
s.add("A");
s.add("B");
s.add("C");
// iteration using for ... of:
for (let item of s) console.log(item);
Thus Sets can be used with spread syntax. For example:
const s = new go.Set();
s.add("A");
s.add("B");
s.add("C");
const arr = [...set, "Z"];
// which is an Array of length 4: ["A", "B", "C", "Z"]
A Map is an unordered collection of key-value pairs that are indexed by the keys.
This class is similar to the Map object that is defined in ECMAScript 2015 (ES6).
const m = new go.Map();
m.set("A", 1); // associate "A" with 1
m.set("B", 2);
m.set("C", 3);
assert(s.count === 3);
assert(s.has("B"));
assert(s.get("B") === 2);
m.set("B", 222); // replace the value for "B"
assert(s.get("B") === 222);
s.delete("B"); // remove an item
assert(s.count === 2);
assert(!s.has("B"));
assert(s.get("B") === null);
When writing TypeScript, it is a generic class so that the compiler can enforce types:
// TypeScript:
const m = new go.Map<string, number>(); // Create a map of strings to numbers
m.set("A", 1);
m.set(23, 23); // produces an error during compilation or highlights it in an IDE
m.set({}, 23); // produces an error during compilation or highlights it in an IDE
Iterating over the items in a Map is just like iterating over a List, but offering access to both the keys and the values. As with Sets the order of the items may vary.
const m = new go.Map();
m.set("A", 1); // associate "A" with 1
m.set("B", 2);
m.set("C", 3);
m.set("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
Typically one uses Map.iteratorKeys or Map.iteratorValues when needing to pass a collection on to other methods that take an Iterator.
As of version 3, Map implements the ECMAScript Iterable protocol,
by defining the [Symbol.iterator] property.
This allows using the for (let item of map) ... statement.
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"
// ECMAScript iteration over the key and value pairs:
for (let kvp of map) console.log(`${kvp[0]}: ${kvp[1]}`);
// This might output, perhaps in different order:
// A: 1
// B: 222
// C: 3
for (let k of map.iteratorKeys) console.log(k);
// This might output, perhaps in different order:
// A
// B
// C
for (let v of map.iteratorValues) console.log(v);
// This might output, perhaps in different order:
// 1
// 222
// 3
It is commonplace to iterate over the selected Parts of a Diagram:
for (let part of diagram.selection) {
// 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) { . . . }
}
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) { . . . }
});
Sometimes one needs to iterate over the Nodes in a Diagram:
for (let n of diagram.nodes) {
// n is now a Node or a Group
if (n.category === "Special") { . . . }
}
You can also iterate over the port elements in a Node, or the Links connected to a port element:
for (let port of node.ports) {
// port is now a GraphObject within the Node
for (let link of node.findLinksConnected(port.portId)) {
// link is now a Link connected with the port
if (link.data.xyz === 17) { . . . }
}
}
Or perhaps you need to iterate over the elements of a Panel:
for (let elt of panel.elements) {
// 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 . . . }
}
If you want to find Nodes that are immediate members of a Group:
for (let part of group.memberParts) {
// part is now a Part within the Group
if (part instanceof go.Node) { . . . maybe work with part.data . . . }
}