This is an extension and not part of the main GoJS library. Note that the API for this class may change at any time. If you intend to use an extension in production, you should copy the code to your own source directory. See the Extensions intro page for more information.
Optionalinit: Partial<PackedLayout>ReadonlyactualThis read-only property returns the actual rectangular bounds occupied by the packed nodes. This property does not take into account any kind of spacing around the packed nodes.
Note that this property will only return a valid value after a layout has been performed. Before then, its behavior is undefined.
ReadonlyactualThis read-only property is the effective spacing calculated after doLayout.
If the packMode is PackMode.AspectOnly, this will simply be the spacing property. However, in the PackMode.Fit and PackMode.ExpandToFit modes, this property will include the forced spacing added by the modes themselves.
Note that this property will only return a valid value after a layout has been performed. Before then, its behavior is undefined.
Gets or sets the top-left point for where the graph should be positioned when laid out. The default value for this property is the Point(0, 0). Setting this property to a new value invalidates this layout. This property is likely to be set by many Layouts that belong to a Group when the layout is performed.
Gets or sets whether or not to use the go.Layout.arrangementOrigin property when placing nodes.
The default value is true.
Gets or sets the aspect ratio for the shape that nodes will be packed into. The provided aspect ratio should be a nonzero postive number.
Note that this only applies if the packMode is PackMode.AspectOnly. Otherwise, the size will determine the aspect ratio of the packed shape.
The default value is 1.
Gets or sets a function that determines the initial size and position in document coordinates of a LayoutVertex corresponding to a Node. This function is called by getLayoutBounds. The default value for this property is null, in which case the GraphObject.actualBounds of the Node is used. Setting this property to a new value invalidates this layout.
The non-null value must be a function that takes 3 arguments. The first argument will be the Part whose bounds the Layout should use. The second argument will be this Layout. The third argument will be a Rect that must be modified and returned The return value must be in document coordinates. You may find it convenient to call GraphObject.getDocumentBounds to get the bounds in document coordinates of an object within the node.
since2.0
Gets or sets the comparison function used for sorting nodes.
By default, the comparison function is set according to the values of sortMode and sortOrder.
Whether this comparison function is used is determined by the value of sortMode. Any value except SortMode.None will result in the comparison function being used.
new PackedLayout({
sortMode: SortMode.Area,
comparer: (na, nb) => {
const na = na.data;
const nb = nb.data;
if (da.someProperty < db.someProperty) return -1;
if (da.someProperty > db.someProperty) return 1;
return 0;
}
})
ReadonlydiagramGets the Diagram that owns this layout, if it is the value of Diagram.layout.
If this property and group are non-null, the Group should be in this Diagram.
see
ReadonlyenclosingThis read-only property returns the smallest enclosing circle around the packed nodes. It makes use of the hasCircularNodes property to determine whether or not to make enclosing circle calculations for rectangles or for circles. This property does not take into account any kind of spacing around the packed nodes. The enclosing circle calculation is performed the first time this property is retrieved, and then cached to prevent slow accesses in the future.
Note that this property will only return a valid value after a layout has been performed. Before then, its behavior is undefined.
This property is included as it may be useful for some data visualizations.
ReadonlygroupGets the Group that uses this layout, if it is the value of a group's Group.layout.
If this property is set to a Group, the diagram is automatically set to be the Group's Diagram.
see
Gets or sets whether or not to assume that nodes are circular. This changes the packing algorithm to one that is much more efficient for circular nodes.
As this algorithm expects circles, it is assumed that if this property is set to true that the given nodes will all have the same height and width. All calculations are done using the width of the given nodes, so unexpected results may occur if the height differs from the width.
The default value is false.
Gets or sets whether this layout is performed on an initial layout. The default value is true. Setting this property to false causes isValidLayout to be set to true so that the diagram does not perform this layout.
If you set both isInitial and isOngoing to false, there will be no automatic layout invalidation, because invalidateLayout will not set isValidLayout to false. To get your nodes to appear, you will need to explicitly set or data-bind their Part.location or GraphObject.position to real Point values, because automatic layout will not assign any positions.
Another way of controlling when layouts are invalidated is by setting Part.isLayoutPositioned or Part.layoutConditions.
Gets or sets whether this layout can be invalidated by invalidateLayout. Set this to false to prevent actions such as adding or removing Parts from invalidating this layout. The default value is true. Setting this property does not invalidate this layout.
If you set both isInitial and isOngoing to false, there will be no automatic layout invalidation, because invalidateLayout will not set isValidLayout to false. To get your nodes to appear, you will need to explicitly set or data-bind their Part.location or GraphObject.position to real Point values, because automatic layout will not assign any positions.
Another way of controlling when layouts are invalidated is by setting Part.isLayoutPositioned or Part.layoutConditions.
Gets or sets whether this layout be performed in real-time, before the end of a transaction. All layouts that are invalidated will be performed at the end of a transaction. The default value is null. A null value is treated as true for a Diagram.layout but false for a Group.layout. Setting this property does not invalidate this layout.
Gets or sets whether this layout routes Links. The default value is true. When false, this layout will not explicitly set the Link.points, and the default routing of each individual Link will take place after the Nodes are moved by commitLayout. Setting this property does not invalidate this layout.
Some layouts ignore links, in which case this property is ignored.
Gets or sets whether this layout needs to be performed again (if false). Instead of setting this property directly, it is normal to set it to false by calling invalidateLayout, since that also requests performing a layout in the near future.
Gets or sets whether this layout depends on the Diagram.viewportBounds's size. If set to true, the layout will invalidate when the Diagram's viewport changes size. This only applies to diagram layouts, not to group layouts, and only when Diagram.autoScale is set to AutoScale.None.
The default value is false. Setting this property to true will invalidate this layout.
It is possible that a viewport-sized layout will trigger the Diagram to require scrollbars, which modifies the Diagram.viewportBounds, which will in turn trigger another layout. This is uncommon, but possible with GridLayout if the results require a vertical scrollbar, and that vertical scrollbar shrinks the viewport width enough that a grid column can no longer fit. When designing custom layouts, one should be careful that this behavior does not result in an infinite loop.
Gets or sets the LayoutNetwork used by this Layout, if any. The default value is null. Setting this property does not invalidate this layout. Not all kinds of layout make use of a LayoutNetwork. Call createNetwork or makeNetwork to create a network.
Gets or sets the mode that the layout will use to determine its size. Valid values are PackMode values.
The default value is PackMode.AspectOnly. In this mode, the layout will simply grow as needed, attempting to keep the aspect ratio defined by aspectRatio.
Gets or sets the shape that nodes will be packed into. Valid values are PackShape values.
In PackShape.Spiral mode, nodes are not packed into a particular shape, but rather packed consecutively one after another in a spiral fashion. The aspectRatio property is ignored in this mode, and the size property (if provided) is expected to be square. If it is not square, the largest dimension given will be used. This mode currently only works with circular nodes, so setting it cause the assume that layout to assume that hasCircularNodes is true.
Note that this property sets only the shape, not the aspect ratio. The aspect ratio of this shape is determined by either aspectRatio or size, depending on the packMode.
When the packMode is PackMode.Fit or PackMode.ExpandToFit and this property is set to true, the layout will attempt to make the diameter of the enclosing circle of the layout approximately equal to the greater dimension of the given size property.
The default value is PackShape.Elliptical.
Gets or sets the size for the shape that nodes will be packed into. To fill the viewport, set a size with a width and height of NaN. Size values of 0 are considered for layout purposes to instead be 1.
If the width and height are set to NaN (to fill the viewport), but this layout has no diagram associated with it, the default value of size will be used instead.
Note that this only applies if the packMode is PackMode.Fit or PackMode.ExpandToFit.
The default value is 500x500.
Gets or sets the method by which nodes will be sorted before being packed. To change the order, see sortOrder.
The default value is SortMode.None, in which nodes will not be sorted at all.
Gets or sets the order that nodes will be sorted in before being packed. To change the sort method, see sortMode.
The default value is SortOrder.Descending
Gets or sets the spacing between nodes. This value can be set to any real number (a negative spacing will compress nodes together, and a positive spacing will leave space between them).
Note that the spacing value is only respected in the PackMode.Fit packMode if it does not cause the layout to grow outside of the specified bounds. In the PackMode.ExpandToFit packMode, this property does not do anything.
The default value is 0.
ProtectedcollectA convenient way of converting the Diagram|Group|Iterable argument to doLayout to an actual collection of eligible Parts. The resulting Set will not include any Nodes or Links for which Part.canLayout is false. If the argument includes a Group for which Group.layout is null, the resulting Set will include the member parts of that group rather than that group itself. You will not need to call collectParts if you call makeNetwork, because that method does effectively the same thing when building the LayoutNetwork.
Typical usage:
public doLayout(coll) {
// COLL might be a Diagram or a Group or some Iterable<Part>
const it = this.collectParts(coll).iterator;
while (it.next()) {
const node = it.value;
if (node instanceof go.Node) {
. . . position the node . . .
}
}
}
Virtual OverridecommitThis method is called at the end of doLayout, but before the layout transaction is committed. It can be overriden and used to customize layout behavior. By default, the method does nothing.
VirtualcopyCreates a copy of this Layout and returns it. When a Group is copied that has a Group.layout, the Layout must also be copied. This calls cloneProtected on a newly constructed Layout.
VirtualcreateCreate a new LayoutNetwork of LayoutVertexes and LayoutEdges. This may be overridden in Layout subclasses to create instances of subclasses of LayoutNetwork. Please read the Learn page on Extensions for how to override methods and how to call this base method.
a new LayoutNetwork.
OverridedoVirtualgetThis method is called by layouts to determine the size and initial position of the nodes that it is laying out. Normally this just returns the part's GraphObject.actualBounds. However, if boundsComputation has been set to a function, that function will be called in order to return the bounds of the given Part in document coordinates that the layout should pretend it has.
a Rect in document coordinates
since2.0
Protected VirtualinitialCompute the desired value of arrangementOrigin if this Layout is being performed for a Group.
This is typically called near the beginning of the implementation of doLayout:
this.arrangementOrigin = this.initialOrigin(this.arrangementOrigin);
if the layout wants to respect the pre-layout location of the Group when deciding where to position its member nodes.
If isOngoing is true and if an initial layout has not yet been performed, set the isValidLayout property to false, and ask to perform another layout in the near future. If isInitial is true, this layout is invalidated only when the Diagram.model is replaced, not under the normal circumstances such as when parts are added or removed or due to other calls to Layout._invalidateLayout.
If you set both isInitial and isOngoing to false, there will be no automatic layout invalidation, because this method will not set isValidLayout to false. However you can still set isValidLayout explicitly.
This is typically called when a layout property value has changed, or when a Part is added or removed or changes visibility, if Part.layoutConditions includes the pertinent flags.
VirtualmakeCreate and initialize a LayoutNetwork with the given nodes and links. This should be called by doLayout when this layout uses a network. This method calls createNetwork to allocate the network. This may be overridden in Layout subclasses to customize the initialization. Please read the Learn page on Extensions for how to override methods and how to call this base method.
normally the value of a call to createNetwork initialized by vertexes and edges corresponding to the coll argument.
VirtualupdateWhen using a LayoutNetwork, update the "physical" node positionings and link routings. This should be called by doLayout when this layout uses a network. This calls commitLayout to actually set Node positions and route Links. This performs the changes within a transaction. Please read the Learn page on Extensions for how to override methods and how to call this base method.
Custom layout which attempts to pack nodes as close together as possible without overlap. Each node is assumed to be either rectangular or circular (dictated by the hasCircularNodes property). This layout supports packing nodes into either a rectangle or an ellipse, with the shape determined by the packShape property and the aspect ratio determined by either the aspectRatio property or the specified width and height (depending on the packMode).
Nodes with 0 width or height cannot be packed, so they are treated by this layout as having a width or height of 0.1 instead.
If you want to experiment with this extension, try the PackedLayout sample.