FoldingManager

This class adds folding support to IGraph implementations.

Inheritance Hierarchy

FoldingManager

Remarks

Folding is an extension to the grouping concept. It adds the functionality of collapsing (closing) and expanding (opening) group nodes. Collapsing a group node means that its content is hidden and the group node itself becomes a normal (i.e. non-group or leaf) node.

In yFiles folding works with two graph instances: a master graph which is is the complete unfolded graph and the so called view graph which supports collapsing and expanding. This view graph is a modified and managed copy of the master graph. To make sure that the state of both graphs is correctly synchronized, yFiles provides the types FoldingManager and the IFoldingView.

The FoldingManager holds the master graph and synchronizes changes between the master graph and the different IFoldingViews. Therefore, it also serves as see factory for instances of IFoldingView. In turn, each IFoldingView instance manages an IGraph implementation that provides a view of a subset of the masterGraph where group nodes can appear as collapsed group nodes with their contents hidden. The views are synchronized with the masterGraph, but may contain additional view state.

Creating a graph where nodes can be collapsed and expanded

// first create the manager
const manager = new FoldingManager()
// the manager serves as factory to create views
const foldingView = manager.createFoldingView()
// each view contains a folding-enabled graph: the view graph
const viewGraph = foldingView.graph
// the view graph is the graph which should actually be displayed
graphComponent.graph = viewGraph

Collapsed group nodes in a view, as well as their adjacent edges, maintain a separate set of labels, ports, bends, and geometry. This view-local state is shared between all views that have been created by the same manager. It can be obtained and modified via the methods getFoldingEdgeState for folding edges and getFolderNodeState for folder nodes. The FoldingManager manages the varying states nodes and edges can have in different views and during different collapsed/expanded states of the nodes. Group nodes can appear as collapsed group nodes with their contents hidden. Edges that connect to elements inside collapsed group nodes can be configured to be represented by folding edges in the views. The process of converting one or more true edges from the masterGraph to zero or more folding edges can be customized, as well as the process of converting an expanded group node to a collapsed group node.

Related Programming Samples

Graph Editor: Shows the graph editing features of the graph component.

Type Details

yfiles module: view-folding
yfiles-umd modules: view-folding, view-graphml, view
Legacy UMD name: yfiles.graph.FoldingManager

Constructors

FoldingManager

()

Creates a new manager with a default backing graph implementation.

Remarks

Use createFoldingView to create a view that supports the IFoldingView interface for displaying and working with a collapsible graph structure.

This constructor will set a new empty DefaultGraph as masterGraph.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

foldingEdgeConverter - IFoldingEdgeConverter: The IFoldingEdgeConverter implementation that is used to create/convert and modify the folding edges inside the view instances. This option sets the foldingEdgeConverter property on the created object.
folderNodeConverter - IFolderNodeConverter: The IFolderNodeConverter implementation that is used to create/convert and modify the folder nodes inside the view instances. This option sets the folderNodeConverter property on the created object.

Examples

Setting up folding with a new graph instance

const manager = new FoldingManager()
graphComponent.graph = manager.createFoldingView().graph

Setting up folding, reusing a given graph instance

const manager = new FoldingManager(graphComponent.graph)
graphComponent.graph = manager.createFoldingView().graph

FoldingManager

(masterGraph: IGraph)

Creates a manager instance for the given masterGraph to create views on top of it that support folding operations.

Remarks

The given masterGraph may already contain nodes.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

masterGraph - IGraph: The graph to use as the masterGraph.
foldingEdgeConverter - IFoldingEdgeConverter: The IFoldingEdgeConverter implementation that is used to create/convert and modify the folding edges inside the view instances. This option sets the foldingEdgeConverter property on the created object.
folderNodeConverter - IFolderNodeConverter: The IFolderNodeConverter implementation that is used to create/convert and modify the folder nodes inside the view instances. This option sets the folderNodeConverter property on the created object.

Throws

Exception({ name: 'ArgumentError' }): masterGraph is null.

Examples

Setting up folding with a new graph instance

const manager = new FoldingManager()
graphComponent.graph = manager.createFoldingView().graph

Setting up folding, reusing a given graph instance

const manager = new FoldingManager(graphComponent.graph)
graphComponent.graph = manager.createFoldingView().graph

Properties

folderNodeConverter

: IFolderNodeConverter

Gets or sets the IFolderNodeConverter implementation that is used to create/convert and modify the folder nodes inside the view instances.

Remarks

The converter instance will be used to create the initial and change the appearance of the folder nodes as soon as they appear in a view.

Examples

manager.folderNodeConverter = new DefaultFolderNodeConverter({
  copyFirstLabel: true,
  folderNodeStyle: new ShapeNodeStyle({ fill: Fill.GRAY })
})

foldingEdgeConverter

: IFoldingEdgeConverter

Gets or sets the IFoldingEdgeConverter implementation that is used to create/convert and modify the folding edges inside the view instances.

Remarks

The converter instance will be used to create the initial and change the appearance of the folding edges as soon as they appear in a view.

Throws

Exception({ name: 'ArgumentError' }): value is null.

Examples

manager.foldingEdgeConverter = new MergingFoldingEdgeConverter({
  copyFirstLabel: true,
  foldingEdgeStyle: new PolylineEdgeStyle({ stroke: Stroke.GRAY })
})

Sample Graphs

masterGraph

: IGraph

Gets the master IGraph instance that holds the complete model in expanded group node state.

Remarks

This graph contains all non-folding edges and expanded group nodes, no folding edges and no collapsed group nodes.

views

: IEnumerable<IFoldingView>

Gets all currently known view instances that are managed by this instance.

Methods

createFoldingView

(root?: INode, isExpanded?: function(INode):boolean) : IFoldingView

Creates a separate view instance of the masterGraph which is a synchronized copy of a subset of the items from the master graph.

Remarks

This method will create a new instance of an IGraph that is constructed as a synchronized copy of the masterGraph. That instance can be obtained from the graph property of the returned IFoldingView implementation. The graph instance will provide an IFoldingView instance in its lookup mechanism:

This instance can be used to gain access to this manager instance and the folding operations.

Note that the entities that are contained in the returned graph instance are not the same instances as the original "master" entities in the masterGraph. However they share the same properties (style, tag, parameters, and geometry). For collapsed group nodes and view edges, there is a separate set of properties available for each possible state combination. The getFoldingEdgeState method for edges and the getFolderNodeState method for nodes provide access to that state while it is not being displayed in a view.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

root - INode

A group node or the root of the masterGraph whose contents will be displayed in the view.

isExpanded - function(INode):boolean

A predicate that can be provided to the view that will be used as a callback to determine the initial expansion state of group nodes in the view.

Signature Details

function(obj: INode) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - INode: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

Returns

↪IFoldingView: A new graph instance that represents a synchronized view on the masterGraph.

Examples

Create a folding enabled graph

// first create the manager
const manager = new FoldingManager()
// the manager serves as factory to create views
const foldingView = manager.createFoldingView()
// each view contains a folding-enabled graph: the view graph
const viewGraph = foldingView.graph
// the view graph is the graph which should actually be displayed
graphComponent.graph = viewGraph

If the masterGraph already contains graph elements the created view and its view graph will contain these initially, too.

Create a folding enabled graph with initial elements

const manager = new FoldingManager(graphComponent.graph)
graphComponent.graph = manager.createFoldingView().graph

All group nodes are expanded by default. The isExpanded parameter allows for providing a predicate function which can decide for each node whether it is expanded or collapsed. The following example uses a predicate which returns false for all nodes. Therefore, all nodes in the view graph will be collapsed initially.

Create a folding enabled graph with all groups being collapsed initially

const manager = new FoldingManager(graphComponent.graph)
graphComponent.graph = manager.createFoldingView({
  isExpanded: (node) => false
}).graph

dispose

()

Disposes of this instance.

Remarks

This will disconnect the masterGraph from the previously created managed views. Also each view will be disposed.

getEdgesChangedAfterCollapse

(view: IFoldingView, groupNode: INode) : IEnumerable<FoldingEdgeStateId>

Returns the FoldingEdgeStateIds of all edges whose folding state would change if the groupNode would be collapsed.

Remarks

The return value is only a snapshot and considers the expansion states of nodes in the view except for the groupNode which is considered to be collapsed. This way, the returned edge state IDs can be used to adjust the corresponding FoldingEdgeStates before they become part of the view.

The groupNode may be part of the masterGraph or of the view graph. The master edges of the returned IDs may or may not currently have a corresponding view edge.

Parameters

options - Object
A map of options to pass to the method.

view - IFoldingView: The folding view that is used to determine the expansion state of group nodes.
groupNode - INode: The group node that should be considered as collapsed.

Returns

↪IEnumerable<FoldingEdgeStateId>: The FoldingEdgeStateIds of all edges whose folding state would change if the groupNode would be collapsed.

Examples

geim.navigationInputMode.addGroupCollapsingListener(
  clearBendsOfFoldingEdges
)

/**
 * @param {*} sender
 * @param {!ItemEventArgs.<INode>} e
 */
function clearBendsOfFoldingEdges(sender, e) {
  const groupNode = e.item
  const foldingView = graph.foldingView
  const edgeStateIds = foldingView.isExpanded(groupNode)
    ? foldingView.manager.getEdgesChangedAfterCollapse(foldingView, groupNode)
    : foldingView.manager.getEdgesChangedAfterExpand(foldingView, groupNode)
  edgeStateIds.forEach((edgeStateId) => {
    if (!edgeStateId.sourceIsCollapsed && !edgeStateId.targetIsCollapsed) {
      // if neither source nor target node is collapsed, edgeStateId represents the unfolded master edge
      // so the bends also have to be cleared on the master graph
      foldingView.manager.masterGraph.clearBends(edgeStateId.masterEdge)
    } else {
      // otherwise the bends are cleared on the corresponding FoldingEdgeState
      foldingView.manager.getFoldingEdgeState(edgeStateId).clearBends()
    }
  })
}function clearBendsOfFoldingEdges(sender: any, e: ItemEventArgs<INode>) {
  const groupNode = e.item
  const foldingView = graph.foldingView!
  const edgeStateIds = foldingView.isExpanded(groupNode)
    ? foldingView.manager.getEdgesChangedAfterCollapse(foldingView, groupNode)
    : foldingView.manager.getEdgesChangedAfterExpand(foldingView, groupNode)
  edgeStateIds.forEach((edgeStateId) => {
    if (!edgeStateId.sourceIsCollapsed && !edgeStateId.targetIsCollapsed) {
      // if neither source nor target node is collapsed, edgeStateId represents the unfolded master edge
      // so the bends also have to be cleared on the master graph
      foldingView.manager.masterGraph.clearBends(edgeStateId.masterEdge)
    } else {
      // otherwise the bends are cleared on the corresponding FoldingEdgeState
      foldingView.manager.getFoldingEdgeState(edgeStateId).clearBends()
    }
  })
}

getEdgesChangedAfterExpand

(view: IFoldingView, groupNode: INode) : IEnumerable<FoldingEdgeStateId>

Returns the FoldingEdgeStateIds of all edges whose folding state would change if the groupNode would be expanded.

Remarks

The return value is only a snapshot and considers the expansion states of nodes in the view except for the groupNode which is considered to be expanded. This way, the returned edge state IDs can be used to adjust the corresponding FoldingEdgeStates before they become part of the view.

The groupNode may be part of the masterGraph or of the view graph. The master edges of the returned IDs may or may not currently have a corresponding view edge.

Parameters

options - Object
A map of options to pass to the method.

view - IFoldingView: The folding view that is used to determine the expansion state of group nodes.
groupNode - INode: The group node that should be considered as expanded.

Returns

↪IEnumerable<FoldingEdgeStateId>: The FoldingEdgeStateIds of all edges whose folding state would change if the groupNode would be expanded.

Examples

geim.navigationInputMode.addGroupExpandingListener(clearBendsOfFoldingEdges)

/**
 * @param {*} sender
 * @param {!ItemEventArgs.<INode>} e
 */
function clearBendsOfFoldingEdges(sender, e) {
  const groupNode = e.item
  const foldingView = graph.foldingView
  const edgeStateIds = foldingView.isExpanded(groupNode)
    ? foldingView.manager.getEdgesChangedAfterCollapse(foldingView, groupNode)
    : foldingView.manager.getEdgesChangedAfterExpand(foldingView, groupNode)
  edgeStateIds.forEach((edgeStateId) => {
    if (!edgeStateId.sourceIsCollapsed && !edgeStateId.targetIsCollapsed) {
      // if neither source nor target node is collapsed, edgeStateId represents the unfolded master edge
      // so the bends also have to be cleared on the master graph
      foldingView.manager.masterGraph.clearBends(edgeStateId.masterEdge)
    } else {
      // otherwise the bends are cleared on the corresponding FoldingEdgeState
      foldingView.manager.getFoldingEdgeState(edgeStateId).clearBends()
    }
  })
}function clearBendsOfFoldingEdges(sender: any, e: ItemEventArgs<INode>) {
  const groupNode = e.item
  const foldingView = graph.foldingView!
  const edgeStateIds = foldingView.isExpanded(groupNode)
    ? foldingView.manager.getEdgesChangedAfterCollapse(foldingView, groupNode)
    : foldingView.manager.getEdgesChangedAfterExpand(foldingView, groupNode)
  edgeStateIds.forEach((edgeStateId) => {
    if (!edgeStateId.sourceIsCollapsed && !edgeStateId.targetIsCollapsed) {
      // if neither source nor target node is collapsed, edgeStateId represents the unfolded master edge
      // so the bends also have to be cleared on the master graph
      foldingView.manager.masterGraph.clearBends(edgeStateId.masterEdge)
    } else {
      // otherwise the bends are cleared on the corresponding FoldingEdgeState
      foldingView.manager.getFoldingEdgeState(edgeStateId).clearBends()
    }
  })
}

getFolderNodeState

(masterNode: INode) : FolderNodeState

Provides access to the folder node state of a node.

Remarks

This method can be used to query the collapsed state of a node, even if the node is currently not present in any managed view or the node is in fact expanded in all views.

Parameters

options - Object
A map of options to pass to the method.

masterNode - INode: The node in the masterGraph for which the state should be returned.

Returns

↪FolderNodeState: A state holder implementation of a node, which is not part of any graph.

Throws

Exception({ name: 'ArgumentError' }): The master node does not belong to the managed graph.

Examples

const state = manager.getFolderNodeState(masterNode)
state.style = new GroupNodeStyle()

getFoldingEdgeState

(id: FoldingEdgeStateId) : FoldingEdgeState

Return a data container implementation that is not part of any actual IGraph that describes the state of the edge for the given FoldingEdgeStateId.

Remarks

This method can be used to query the state of an edge that is either not currently visible in any view or connects to different source and target nodes because of the collapsed states of the nodes and their parents in the view.

Parameters

options - Object
A map of options to pass to the method.

id - FoldingEdgeStateId: The ID of the folding edge for which the folding state should be returned.

Returns

↪FoldingEdgeState: A FoldingEdgeState that can be used to query and change the properties of the edge.

Throws

Exception({ name: 'ArgumentError' }): if the id doesn't represent a dummy edge state which is managed by this manager.

Examples

const state = manager.getFoldingEdgeState(
  new FoldingEdgeStateId(
    masterEdge,
    masterSource,
    true,
    masterTarget,
    false
  )
)
state.style = new PolylineEdgeStyle({ stroke: Stroke.RED })

const state = manager.getFoldingEdgeState(
  new FoldingEdgeStateId(
    masterEdge,
    masterSource,
    true,
    masterTarget,
    false
  )
)
const portState = state.sourcePort
portState.locationParameter = FreeNodePortLocationModel.NODE_RIGHT_ANCHORED

Sample Graphs

getNodesRevealedAfterExpand

(view: IFoldingView, groupNode: INode) : IEnumerable<INode>

Returns the master nodes of the descendants of the groupNode that would be represented in the view if the groupNode would be expanded.

Remarks

The return value is only a snapshot and considers the expansion states of nodes in the view except for the groupNode which is considered to be expanded. This way, the returned nodes can be adjusted before they become part of the view.

The groupNode may be part of the masterGraph or of the view graph. The returned descendants all belong to the masterGraph and may currently have no corresponding view item.

Parameters

options - Object
A map of options to pass to the method.

view - IFoldingView: The folding view that is used to determine the expansion state of group nodes.
groupNode - INode: The group node that should be considered as expanded.

Returns

↪IEnumerable<INode>: The master nodes of the descendants of the groupNode that would be represented in the view if the groupNode would be expanded.

Examples

geim.navigationInputMode.addGroupExpandingListener(onGroupExpanding)

/**
 * @param {*} sender
 * @param {!ItemEventArgs.<INode>} e
 */
function onGroupExpanding(sender, e) {
  // move the center of the expanded group node (together with all descendants) to the center of the folder
  const groupNode = e.item
  const foldingView = graph.foldingView
  const masterItem = foldingView.getMasterItem(groupNode)
  // calculate the delta by which the group node and its descendants have to be moved
  const delta = groupNode.layout.center.subtract(masterItem.layout.center)

  const masterGraph = foldingView.manager.masterGraph
  masterGraph.setNodeCenter(masterItem, groupNode.layout.center)
  const descendents = foldingView.manager.getNodesRevealedAfterExpand(
    foldingView,
    groupNode
  )
  descendents.forEach((descendent) =>
    masterGraph.setNodeCenter(descendent, descendent.layout.center.add(delta))
  )
}function onGroupExpanding(sender: any, e: ItemEventArgs<INode>) {
  // move the center of the expanded group node (together with all descendants) to the center of the folder
  const groupNode = e.item
  const foldingView = graph.foldingView!
  const masterItem = foldingView.getMasterItem(groupNode)!
  // calculate the delta by which the group node and its descendants have to be moved
  const delta = groupNode.layout.center.subtract(masterItem.layout.center)

  const masterGraph = foldingView.manager.masterGraph
  masterGraph.setNodeCenter(masterItem, groupNode.layout.center)
  const descendents = foldingView.manager.getNodesRevealedAfterExpand(
    foldingView,
    groupNode
  )
  descendents.forEach((descendent) =>
    masterGraph.setNodeCenter(descendent, descendent.layout.center.add(delta))
  )
}

hasFolderNodeState

(masterNode: INode) : boolean

Determines whether for the given masterNode this manager has stored associated folder node state.

Remarks

The manager does not necessarily have folder node state for folder nodes if that specific state has never been requested by a view because it has never been visualized. This method indicates whether there is state information available for the given master node.

Parameters

options - Object
A map of options to pass to the method.

masterNode - INode: The master node for which the state is requested.

Returns

↪boolean: Whether getFolderNodeState would return existing state information.

hasFoldingEdgeState

(id: FoldingEdgeStateId) : boolean

Determines whether for the given FoldingEdgeStateId this manager has stored associated view local state.

Remarks

The manager does not necessarily have a FoldingEdgeState for folding elements if that specific state has never been requested by a IFoldingView because it has never been visualized. This method indicates whether there is state information available for the given id.

Parameters

options - Object
A map of options to pass to the method.

id - FoldingEdgeStateId: The id for which state is requested.

Returns

↪boolean: Whether getFoldingEdgeState would return existing state information.

prepareFoldingView

(foldingView: IFoldingView)

Can be overridden by subclasses to prepare the IFoldingView instance right before it will be initialized with a copy of the elements in the initial graph.

Remarks

Subclasses could override this method to register additional IMapper<K,V> instances with the graph instance or add IContextLookupChainLinks via the ILookupDecorator of the graph to the instance if they are essential for the initial creation of the elements in the view instance. Overriding methods should always consider to call the base class implementation, first.

Parameters

options - Object
A map of options to pass to the method.

foldingView - IFoldingView: The graph view that has just been created but is still empty.

updateFolderNodeStates

(masterNode: INode)

Triggers a call to updateFolderNodeState for all view nodes that represent the given masterNode in its collapsed state.

Remarks

In all views that are currently showing the node in collapsed state, the view-local state will be updated via a call to the IFolderNodeConverter's updateFolderNodeState method.

Note that all views share the same FolderNodeState for the masterNode.

This method is useful in situations where a change in the data on the master graph did not automatically trigger a call to the converter. Using this method, the state of the collapsed nodes in the views can be synchronized according to the logic in the IFolderNodeConverter implementation.

Parameters

options - Object
A map of options to pass to the method.

masterNode - INode: The master node that belongs to the masterGraph.

Throws

Exception({ name: 'ArgumentError' }): If the provided master node does not belong to the master graph.

updateFoldingEdgeStates

(masterEdge: IEdge)

Triggers a call to updateFoldingEdgeState for all folder edges that represent the given masterEdge.

Remarks

In all views that are currently showing the view edge for the provided master edge, the view-local state will be updated via a call to the IFoldingEdgeConverter's updateFoldingEdgeState method.

This method is useful in situations where a change in the data on the master graph did not automatically trigger a call to the converter. Using this method, the state of the representing edges in the views can be synchronized according to the logic in the IFoldingEdgeConverter implementation.

Parameters

options - Object
A map of options to pass to the method.

masterEdge - IEdge: The master edge that belongs to the masterGraph.

Throws

Exception({ name: 'ArgumentError' }): If the provided master edge does not belong to the master graph.

FoldingManager

Remarks

Related Reading in the Developer's Guide

Related Programming Samples

Type Details

See Also

Constructors

FoldingManager

Remarks

ParametersOptions Overload

Examples

See Also

FoldingManager

Remarks

ParametersOptions Overload

Throws

Examples

Properties

folderNodeConverter

Remarks

Examples

See Also

foldingEdgeConverter

Remarks

Throws

Examples

See Also

Sample Graphs

masterGraph

Remarks

See Also

views

See Also

Methods

createFoldingView

Remarks

ParametersOptions Overload

Signature Details

Parameters

Returns

Returns

Examples

See Also

dispose

Remarks

getEdgesChangedAfterCollapse

Remarks

Parameters

Returns

Examples

See Also

getEdgesChangedAfterExpand

Remarks

Parameters

Returns

Examples

See Also

getFolderNodeState

Remarks

Parameters

Returns

Throws

Examples

See Also

getFoldingEdgeState

Remarks

Parameters

Returns

Throws

Examples

See Also

Sample Graphs

getNodesRevealedAfterExpand

Remarks

Parameters

Returns

Examples

hasFolderNodeState

Remarks

Parameters