Class Layout
This is the base class for all of the predefined diagram layout implementations. They only arrange Parts (primarily Nodes and Links) in a Diagram, not to GraphObjects in Panels (i.e. panel layout).
The layout classes include TreeLayout, ForceDirectedLayout, LayeredDigraphLayout, CircularLayout, and GridLayout. This base class is not abstract -- in fact an instance of this base class is the default value for Diagram.layout and for Group.layout.
An instance of a Layout class will be the value of Diagram.layout. That layout positions the graph of top-level nodes and links. Nodes and links that belong to a Group are laid out by that group's Group.layout. The Diagram will automatically perform all nested group layouts before laying out the whole diagram.
If you have position information for all of the nodes when you load a model, you will typically have data bound the Part.location to some property on your node data. In order to avoid an initial layout causing those saved node positions to be discarded, you can either not set the Diagram.layout to a predefined layout or you can set isInitial to false.
Because performing layouts can be expensive in space and time, automatic layouts are performed only on "invalid" layouts, and only well after a layout has been invalidated. This state is held by the isValidLayout property. Many standard operations, such as adding or removing nodes or links, will cause the layout that is responsible for positioning those nodes or routing those links to be invalidated. Such invalidation is performed by calling invalidateLayout, which not only clears the isValidLayout state but also requests that the diagram do an automatic layout soon. You can avoid such invalidations by setting isOngoing to false.
Layouts will ignore parts that have Part.isLayoutPositioned set to false or parts that are not GraphObject.visible. Layouts will also ignore parts that are in layers that are Layer.isTemporary.
Various operations on Parts will cause the responsible Layout to be invalidated. This includes adding or removing parts, changing their visibility, and changing their size. You can disable such automatic layout invalidations by setting Part.layoutConditions to the combination of Part flags named "Layout..." that you want.
But operations on parts are not the only way in which layouts become invalidated.
Setting most properties on the layouts, thereby changing their behavior, will invalidate that layout.
Replacing the Diagram.layout or Group.layout will automatically invalidate the new layout.
If isViewportSized is true, when a diagram's Diagram.viewportBounds changes size,
the Diagram.layout is invalidated.
(This is normally only true for GridLayouts when its GridLayout.wrappingWidth is NaN.
Most layouts do not care about the size of the viewport.)
You can also explicitly call Diagram.layoutDiagram, which can invalidate all layouts and then perform them all. But we recommend that you avoid doing so, to allow the normal updating process perform layouts as needed.
If an automatic layout is the first time that a layout has been performed for the model, the diagram first raises the DiagramEvent named "InitialLayoutCompleted". Whenever a Diagram finishes an automatic layout, it raises the DiagramEvent named "LayoutCompleted".
It is also possible to call doLayout explicitly, but this is uncommon and only used with instances of Layout that are not the Diagram.layout or Group.layout. It should only be needed when you want to layout a collection of nodes and links that is not the normal graph of top-level parts of a Diagram or a subgraph of a Group.
More complicated layouts make use of a separate LayoutNetwork, consisting of LayoutVertexes and LayoutEdges, that normally holds a graph that is isomorphic to the graph consisting of Nodes and Links in the Diagram or Group. The implementation of doLayout will call makeNetwork and remember the result as the network. makeNetwork will call createNetwork and initialize it by adding new instances of LayoutVertexes and LayoutEdges corresponding to the given collection of Nodes and Links.
When doLayout is finished with its work it will call updateParts, which will call commitLayout to set new node locations and route links. It then normally discards the network.
The LayoutVertex and LayoutEdge instances allow the layout to work with more information about each Node and Link without actually modifying those Nodes and Links until commitLayout is called to actually set the Node locations and route the Links. The use of a LayoutNetwork also allows the Layout to work with a graph that is not isomorphic to the given collection of Nodes and Links. This is useful when needing to use dummy vertexes and/or edges to achieve certain layout behaviors, or when one wants to ignore certain vertexes or edges, without actually modifying or adding or removing the diagram's nodes or links.
An instance of this base class provides a rudimentary default layout that will position all of the parts that have no position (i.e. the Part.location is (NaN,NaN). Parts that already have a position are ignored. This primitive layout class does not make use of a LayoutNetwork because it ignores all links.
To implement your own custom layouts, you can inherit from either this class or from one of the other predefined layout classes. If you inherit from this base class, you will want to override the doLayout method. You can call the Part.move method to re-position a part, including whole groups. Please read the Introduction page on Extensions for how to override methods and how to call a base method.
Constructor Summary Details
| Name | Description |
|---|---|
|
Layout()
|
Create a minimal layout that only positions Nodes that do not have a location. |
Properties Summary Details
| Name, Value Type | Description |
|---|---|
|
arrangementOrigin
{Point}
|
Gets or sets the top-left point for where the graph should be positioned when laid out.More... The default value for this property is the Point(0, 0). Setting this property invalidates this layout. |
|
diagram
{Diagram}
|
Gets the Diagram that owns this layout, if it is the value of Diagram.layout.More... If this property and group are non-null, the Group should be in this Diagram. See also:
|
|
group
{Group}
|
Gets the Group that uses this layout, if it is the value of a group's Group.layout.More... If this property is set to a Group, the diagram is automatically set to be the Group's Diagram. See also:
|
|
isInitial
{boolean}
|
Gets or sets whether this layout is performed on an initial layout.More... 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. |
|
isOngoing
{boolean}
|
Gets or sets whether this layout can be invalidated by invalidateLayout.More... 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. |
|
isRealtime
{boolean}
1.2
|
Gets or sets whether this layout be performed in real-time, before the end of a transaction.More... All layouts that are invalidated will be performed at the end of a transaction. The default value is true. Setting this property does not invalidate this layout. |
|
isRouting
{boolean}
1.1
|
Gets or sets whether this layout routes Links.More... 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. |
|
isValidLayout
{boolean}
|
Gets or sets whether this layout needs to be performed again (if false).More... 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. |
|
isViewportSized
{boolean}
|
Gets or sets whether this layout depends on the Diagram.viewportBounds's size.More... 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 Diagram.None. The default value is false. Setting this property to true will invalidate this layout. |
|
network
|
Gets or sets the LayoutNetwork used by this Layout, if any.More... 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. |
Method Summary Details
| Name, Return Type | Description |
|---|---|
|
cloneProtected(copy)
1.6
|
Copies properties from this object to the given object, which is of the same class.More... This is called by copy and should be overridden for each class that adds properties. There are examples of such overrides in the samples. Please read the Introduction page on Extensions for how to override methods and how to call this base method.
|
|
collectParts(coll)
{Set.
|
A convenient way of converting the Diagram|Group|Iterable argument to doLayout to an actual collection of eligible Parts.More... 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:
CustomLayout.prototype.doLayout = function(coll) {
// COLL might be a Diagram or a Group or some Iterable
|
|
commitLayout()
|
When using a LayoutNetwork, commit changes to the diagram by setting Node positions and by routing the Links.More... This is called by updateParts within a transaction. You should not call this method -- it is a "protected virtual" method. This may be overridden by subclasses of Layout. By default this method is implemented as follows:
Layout.prototype.commitLayout = function() {
var vit = this.network.vertexes.iterator;
while (vit.next()) {
var vert = vit.value;
vert.commit();
}
if (this.isRouting) {
var eit = this.network.edges.iterator;
while (eit.next()) {
var edge = eit.value;
edge.commit();
}
}
}
Please read the Introduction page on Extensions for how to override methods and how to call this base method. |
|
copy()
{Layout}
|
Creates a copy of this Layout and returns it.More... When a Group is copied that has a Group.layout, the Layout must also be copied. This calls cloneProtected on a newly constructed Layout.
|
|
createNetwork()
|
Create a new LayoutNetwork of LayoutVertexes and LayoutEdges.More... This may be overridden in Layout subclasses to create instances of subclasses of LayoutNetwork. Please read the Introduction page on Extensions for how to override methods and how to call this base method.
|
|
doLayout(coll)
|
Position all of the nodes that do not have an assigned Part.location in the manner of a simple rectangular array.More... The default implementation ignores all Groups and Links; many subclasses of Layout ignore all instances of Parts that are not Nodes or Links. You can override this method to do whatever node positioning and link routing that you wish. When the layout makes use of a LayoutNetwork, this method should call makeNetwork and updateParts. The updateParts method will call commitLayout within a transaction. The outline of such an override should be like:
CustomNetworkLayout.prototype.doLayout = function(coll) {
if (this.network === null) this.network = this.makeNetwork(coll);
// assign LayoutVertex.bounds to all vertexes in the network:
var vit = this.network.vertexes.iterator;
while (vit.next()) {
var v = vit.value;
v.centerX = ...
v.centerY = ...
}
this.updateParts();
this.network = null;
};
Override commitLayout to actually position nodes and route links.
When the layout does not make use of a LayoutNetwork, this method should make direct changes to Nodes and Links within a transaction, and it should call collectParts on the argument coll in order to get the proper set of Nodes and Links to work on. Examples are provided in the Extensions directory. If this Layout belongs to a Diagram, the argument must be either the same Diagram or must denote Parts that belong to the Diagram. Please read the Introduction page on Extensions for how to override methods and how to call this base method. |
|
invalidateLayout()
|
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.More... 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. |
|
makeNetwork(coll)
|
Create and initialize a LayoutNetwork with the given nodes and links.More... 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 Introduction page on Extensions for how to override methods and how to call this base method.
|
|
updateParts()
|
When using a LayoutNetwork, update the "physical" node positionings and link routings.More... 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 Introduction page on Extensions for how to override methods and how to call this base method. |