zcy
/
maxGraph
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: improve JSDoc of GraphLayout and CompositeLayout (#217) 

Improve wording
Remove references to mxGraph code
Use modern JS code in examples
development
Thomas Bouffard 2023-07-06 16:59:45 +02:00 committed by GitHub
parent 992f3af63d
commit d7646d6405
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 46 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
packages/core/src/view/layout/CompositeLayout.ts
View File

@ -20,32 +20,39 @@ import { Graph } from '../Graph';
import GraphLayout from './GraphLayout'; import GraphLayout from './GraphLayout';
/** /**
* Allows to compose multiple layouts into a single layout. The master layout * Allows to compose multiple layouts into a single layout.
* is the layout that handles move operations if another layout than the first *
* element in <layouts> should be used. The {@link aster} layout is not executed as * The {@link master} layout is the layout that handles move operations if another layout than the first
* the code assumes that it is part of <layouts>. * element in {@link GraphLayout}s should be used. The {@link master} layout is not executed as
* the code assumes that it is part of {@link layouts}.
* *
* Example: * Example:
* ```javascript * ```javascript
* let first = new mxFastOrganicLayout(graph); * const first = new FastOrganicLayout(graph);
* let second = new mxParallelEdgeLayout(graph); * const second = new ParallelEdgeLayout(graph);
* let layout = new mxCompositeLayout(graph, [first, second], first); * const layout = new CompositeLayout(graph, [first, second], first);
* layout.execute(graph.getDefaultParent()); * layout.execute(graph.getDefaultParent());
* ``` * ```
* *
* Constructor: mxCompositeLayout
*
* Constructs a new layout using the given layouts. The graph instance is * Constructs a new layout using the given layouts. The graph instance is
* required for creating the transaction that contains all layouts. * required for creating the transaction that contains all layouts.
* *
* Arguments: * Arguments:
* *
* graph - Reference to the enclosing {@link Graph}. * graph - Reference to the enclosing {@link Graph}.
* layouts - Array of {@link GraphLayouts}. * layouts - Array of {@link GraphLayout}s.
* master - Optional layout that handles moves. If no layout is given then * master - Optional layout that handles moves. If no layout is given then
* the first layout of the above array is used to handle moves. * the first layout of the above array is used to handle moves.
*/ */
class CompositeLayout extends GraphLayout { class CompositeLayout extends GraphLayout {
/**
* Constructs a new layout using the given layouts. The graph instance is
* required for creating the transaction that contains all layouts.
*
* @param graph Reference to the enclosing {@link Graph}.
* @param layouts Array of {@link GraphLayout}s.
* @param master Optional layout that handles moves. If no layout is given, then the first layout of the above array is used to handle moves.
*/
constructor(graph: Graph, layouts: GraphLayout[], master?: GraphLayout) { constructor(graph: Graph, layouts: GraphLayout[], master?: GraphLayout) {
super(graph); super(graph);
this.layouts = layouts; this.layouts = layouts;
@ -53,19 +60,18 @@ class CompositeLayout extends GraphLayout {
} }
/** /**
* Holds the array of {@link GraphLayouts} that this layout contains. * Holds the array of {@link GraphLayout}s that this layout contains.
*/ */
layouts: GraphLayout[]; layouts: GraphLayout[];
/** /**
* Reference to the {@link GraphLayouts} that handles moves. If this is null * Reference to the {@link GraphLayout}s that handles moves. If this is null
* then the first layout in <layouts> is used. * then the first layout in <layouts> is used.
*/ */
master?: GraphLayout; master?: GraphLayout;
/** /**
* Implements {@link GraphLayout#moveCell} by calling move on {@link aster} or the first * Calls `move` on {@link master} or the first layout in {@link layouts}.
* layout in <layouts>.
*/ */
moveCell(cell: Cell, x: number, y: number) { moveCell(cell: Cell, x: number, y: number) {
if (this.master != null) { if (this.master != null) {
@ -76,8 +82,7 @@ class CompositeLayout extends GraphLayout {
} }
/** /**
* Implements {@link GraphLayout#execute} by executing all <layouts> in a * Implements {@link GraphLayout#execute} by executing all {@link layouts} in a single transaction.
* single transaction.
*/ */
execute(parent: Cell): void { execute(parent: Cell): void {
this.graph.batchUpdate(() => { this.graph.batchUpdate(() => {

57
packages/core/src/view/layout/GraphLayout.ts
View File

@ -25,17 +25,10 @@ import Cell from '../cell/Cell';
import { GraphLayoutTraverseArgs } from './types'; import { GraphLayoutTraverseArgs } from './types';
/** /**
* @class GraphLayout * Base class for all layout algorithms in mxGraph.
* *
* Base class for all layout algorithms in mxGraph. Main public functions are * Main public methods are {@link moveCell} for handling a moved cell within a layouted parent,
* {@link moveCell} for handling a moved cell within a layouted parent, and {@link execute} for * and {@link execute} for running the layout on a given parent cell.
* running the layout on a given parent cell.
*
* Known Subclasses:
*
* {@link mxCircleLayout}, {@link mxCompactTreeLayout}, {@link mxCompositeLayout},
* {@link mxFastOrganicLayout}, {@link mxParallelEdgeLayout}, {@link mxPartitionLayout},
* {@link mxStackLayout}
*/ */
class GraphLayout { class GraphLayout {
constructor(graph: Graph) { constructor(graph: Graph) {
@ -43,18 +36,19 @@ class GraphLayout {
} }
/** /**
* Reference to the enclosing {@link mxGraph}. * Reference to the enclosing {@link Graph}.
*/ */
graph: Graph; graph: Graph;
/** /**
* Boolean indicating if the bounding box of the label should be used if * Boolean indicating if the bounding box of the label should be used if it iss available.
* its available. Default is true. * @default true.
*/ */
useBoundingBox = true; useBoundingBox = true;
/** /**
* The parent cell of the layout, if any * The parent cell of the layout, if any
* @default null
*/ */
parent: Cell | null = null; parent: Cell | null = null;
@ -66,7 +60,7 @@ class GraphLayout {
* *
* Empty implementation. * Empty implementation.
* *
* @param cell {@link mxCell} which has been moved. * @param cell {@link Cell} which has been moved.
* @param x X-coordinate of the new cell location. * @param x X-coordinate of the new cell location.
* @param y Y-coordinate of the new cell location. * @param y Y-coordinate of the new cell location.
*/ */
@ -80,8 +74,9 @@ class GraphLayout {
* *
* Empty implementation. * Empty implementation.
* *
* @param cell <Cell> which has been moved. * @param cell {@link Cell} which has been moved.
* @param bounds {@link Rectangle} that represents the new cell bounds. * @param bounds {@link Rectangle} that represents the new cell bounds.
* @param prev
*/ */
resizeCell(cell: Cell, bounds: Rectangle, prev?: Cell) { resizeCell(cell: Cell, bounds: Rectangle, prev?: Cell) {
return; return;
@ -90,7 +85,7 @@ class GraphLayout {
/** /**
* Executes the layout algorithm for the children of the given parent. * Executes the layout algorithm for the children of the given parent.
* *
* @param parent {@link mxCell} whose children should be layed out. * @param parent {@link Cell} whose children should be layed out.
*/ */
execute(parent: Cell): void { execute(parent: Cell): void {
return; return;
@ -110,8 +105,8 @@ class GraphLayout {
* returns the value for the given key in the style of the given cell. * returns the value for the given key in the style of the given cell.
* *
* @param key Key of the constraint to be returned. * @param key Key of the constraint to be returned.
* @param cell {@link mxCell} whose constraint should be returned. * @param cell {@link Cell} whose constraint should be returned.
* @param edge Optional {@link mxCell} that represents the connection whose constraint * @param edge Optional {@link Cell} that represents the connection whose constraint
* should be returned. Default is null. * should be returned. Default is null.
* @param source Optional boolean that specifies if the connection is incoming * @param source Optional boolean that specifies if the connection is incoming
* or outgoing. Default is null. * or outgoing. Default is null.
@ -132,19 +127,19 @@ class GraphLayout {
* *
* ```javascript * ```javascript
* MaxLog.show(); * MaxLog.show();
* var cell = graph.getSelectionCell(); * const cell = graph.getSelectionCell();
* graph.traverse(cell, false, function(vertex, edge) * graph.traverse(cell, false, function(vertex, edge)
* { * {
* MaxLog.debug(graph.getLabel(vertex)); * MaxLog.debug(graph.getLabel(vertex));
* }); * });
* ``` * ```
* *
* @param vertex {@link mxCell} that represents the vertex where the traversal starts. * @param vertex {@link Cell} that represents the vertex where the traversal starts.
* @param directed Optional boolean indicating if edges should only be traversed * @param directed Optional boolean indicating if edges should only be traversed
* from source to target. Default is true. * from source to target. Default is true.
* @param func Visitor function that takes the current vertex and the incoming * @param func Visitor function that takes the current vertex and the incoming
* edge as arguments. The traversal stops if the function returns false. * edge as arguments. The traversal stops if the function returns false.
* @param edge Optional {@link mxCell} that represents the incoming edge. This is * @param edge Optional {@link Cell} that represents the incoming edge. This is
* null for the first step of the traversal. * null for the first step of the traversal.
* @param visited Optional {@link Dictionary} of cell paths for the visited cells. * @param visited Optional {@link Dictionary} of cell paths for the visited cells.
*/ */
@ -185,8 +180,8 @@ class GraphLayout {
/** /**
* Returns true if the given parent is an ancestor of the given child. * Returns true if the given parent is an ancestor of the given child.
* *
* @param parent {@link mxCell} that specifies the parent. * @param parent {@link Cell} that specifies the parent.
* @param child {@link mxCell} that specifies the child. * @param child {@link Cell} that specifies the child.
* @param traverseAncestors boolean whether to * @param traverseAncestors boolean whether to
*/ */
isAncestor(parent: Cell, child: Cell | null, traverseAncestors?: boolean): boolean { isAncestor(parent: Cell, child: Cell | null, traverseAncestors?: boolean): boolean {
@ -206,35 +201,33 @@ class GraphLayout {
} }
/** /**
* Returns a boolean indicating if the given {@link mxCell} is movable or * Returns a boolean indicating if the given {@link Cell} is movable or
* bendable by the algorithm. This implementation returns true if the given * bendable by the algorithm. This implementation returns true if the given
* cell is movable in the graph. * cell is movable in the graph.
* *
* @param cell {@link mxCell} whose movable state should be returned. * @param cell {@link Cell} whose movable state should be returned.
*/ */
isVertexMovable(cell: Cell): boolean { isVertexMovable(cell: Cell): boolean {
return this.graph.isCellMovable(cell); return this.graph.isCellMovable(cell);
} }
/** /**
* Returns a boolean indicating if the given {@link mxCell} should be ignored by * Returns a boolean indicating if the given {@link Cell} should be ignored by
* the algorithm. This implementation returns false for all vertices. * the algorithm. This implementation returns false for all vertices.
* *
* @param vertex {@link mxCell} whose ignored state should be returned. * @param vertex {@link Cell} whose ignored state should be returned.
*/ */
isVertexIgnored(vertex: Cell): boolean { isVertexIgnored(vertex: Cell): boolean {
return !vertex.isVertex() || !vertex.isVisible(); return !vertex.isVertex() || !vertex.isVisible();
} }
/** /**
* Returns a boolean indicating if the given {@link mxCell} should be ignored by * Returns a boolean indicating if the given {@link Cell} should be ignored by
* the algorithm. This implementation returns false for all vertices. * the algorithm. This implementation returns false for all vertices.
* *
* @param cell {@link mxCell} whose ignored state should be returned. * @param edge {@link Cell} whose ignored state should be returned.
*/ */
isEdgeIgnored(edge: Cell): boolean { isEdgeIgnored(edge: Cell): boolean {
const model = this.graph.getDataModel();
return ( return (
!edge.isEdge() || !edge.isEdge() ||
!edge.isVisible() || !edge.isVisible() ||
@ -320,7 +313,7 @@ class GraphLayout {
* the geometry is not replaced with an updated instance. The new or old * the geometry is not replaced with an updated instance. The new or old
* bounds are returned (including overlapping labels). * bounds are returned (including overlapping labels).
* *
* @param cell {@link mxCell} whose geometry is to be set. * @param cell {@link Cell} whose geometry is to be set.
* @param x Integer that defines the x-coordinate of the new location. * @param x Integer that defines the x-coordinate of the new location.
* @param y Integer that defines the y-coordinate of the new location. * @param y Integer that defines the y-coordinate of the new location.
*/ */