com.yworks.yfiles.graph

Class FoldingManager

java.lang.Object

com.yworks.yfiles.graph.FoldingManager

public class FoldingManager
extends Object

This class adds folding support to IGraph implementations.

This implementation manages the varying states nodes and edges can have in different views and during different collapsed/expanded states of the nodes. Create an instance of this class for a given IGraph and use the createFoldingView(INode, Predicate) methods to create an IGraph implementation that provides a view of a subset of the graph, where group nodes can be collapsed and expanded.

This class can be used to create folding views of the MasterGraph, where 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.

Class FoldingManager's central role for folding support is discussed in the section Folding Revisited. A brief description of the class's API, set-up, etc. is given in the section Working with Folding.

See Also:

IFoldingView, createFoldingView(INode, Predicate)

Constructor Summary

Constructors

Constructor and Description
FoldingManager() Creates a new manager with a default backing graph implementation.
FoldingManager(IGraph masterGraph) Creates a manager instance for the given MasterGraph to create views on top of it that support folding operations.

Method Summary

Modifier and Type	Method and Description
IFoldingView	createFoldingView() Creates a separate view instance of the MasterGraph which is a synchronized copy of a subset of the items from the master graph.
IFoldingView	createFoldingView(INode root) Creates a separate view instance of the MasterGraph which is a synchronized copy of a subset of the items from the master graph.
IFoldingView	createFoldingView(INode root, Predicate<INode> isExpanded) Creates a separate view instance of the MasterGraph which is a synchronized copy of a subset of the items from the master graph.
void	dispose() Disposes of this instance.
IFolderNodeConverter	getFolderNodeConverter() Gets the IFolderNodeConverter implementation that is used to create/convert and modify the folder nodes inside the view instances.
FolderNodeState	getFolderNodeState(INode masterNode) Provides access to the folder node state of a node.
IFoldingEdgeConverter	getFoldingEdgeConverter() Gets the IFoldingEdgeConverter implementation that is used to create/convert and modify the folding edges inside the view instances.
FoldingEdgeState	getFoldingEdgeState(FoldingEdgeStateId id) Return a data container implementation that is not part of any actual IGraph that describes the state of the edge for the given FoldingEdgeStateId.
IGraph	getMasterGraph() Yields the master IGraph instance that holds the complete model in expanded group node state.
IEnumerable<IFoldingView>	getViews() Yields all currently known view instances that are managed by this instance.
boolean	hasFolderNodeState(INode masterNode) Determines whether for the given masterNode this manager has stored associated folder node state.
boolean	hasFoldingEdgeState(FoldingEdgeStateId id) Determines whether for the given FoldingEdgeStateId this manager has stored associated view local state.
protected void	prepareFoldingView(IFoldingView foldingView) Callback that 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.
void	setFolderNodeConverter(IFolderNodeConverter value) Sets the IFolderNodeConverter implementation that is used to create/convert and modify the folder nodes inside the view instances.
void	setFoldingEdgeConverter(IFoldingEdgeConverter value) Sets the IFoldingEdgeConverter implementation that is used to create/convert and modify the folding edges inside the view instances.
void	updateFolderNodeStates(INode masterNode) Triggers a call to IFolderNodeConverter.updateFolderNodeState(FolderNodeState, IFoldingView, INode, INode) for all view nodes that represent the given masterNode in its collapsed state.
void	updateFoldingEdgeStates(IEdge masterEdge) Triggers a call to IFoldingEdgeConverter.updateFoldingEdgeState(FoldingEdgeState, IFoldingView, IEdge, java.util.List) for all folder edges that represent the given masterEdge.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FoldingManager

public FoldingManager()

Creates a new manager with a default backing graph implementation.

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

See Also:

createFoldingView(INode, Predicate), getMasterGraph()

FoldingManager

public FoldingManager(IGraph masterGraph)

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

Throws:

NullPointerException - masterGraph is null.

Parameters:

masterGraph - The graph to use as the MasterGraph.

Method Detail

createFoldingView

public final IFoldingView createFoldingView()

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

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 ILookup.lookup(java.lang.Class) 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(FoldingEdgeStateId) method for edges and the getFolderNodeState(INode) method for nodes provide access to that state while it is not being displayed in a view.

Returns:

A new graph instance that represents a synchronized view on the MasterGraph.

See Also:

prepareFoldingView(IFoldingView)

createFoldingView

public final IFoldingView createFoldingView(INode root)

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

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 ILookup.lookup(java.lang.Class) 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(FoldingEdgeStateId) method for edges and the getFolderNodeState(INode) method for nodes provide access to that state while it is not being displayed in a view.

Parameters:

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

Returns:

A new graph instance that represents a synchronized view on the MasterGraph.

See Also:

prepareFoldingView(IFoldingView)

createFoldingView

public IFoldingView createFoldingView(INode root,
                                      Predicate<INode> isExpanded)

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

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 ILookup.lookup(java.lang.Class) 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(FoldingEdgeStateId) method for edges and the getFolderNodeState(INode) method for nodes provide access to that state while it is not being displayed in a view.

Parameters:

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

isExpanded - 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.

Returns:

A new graph instance that represents a synchronized view on the MasterGraph.

See Also:

prepareFoldingView(IFoldingView)

dispose

public void dispose()

Disposes of this instance.

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

getFolderNodeConverter

public final IFolderNodeConverter getFolderNodeConverter()

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

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.

Returns:

The FolderNodeConverter.

See Also:

DefaultFolderNodeConverter, setFolderNodeConverter(IFolderNodeConverter)

getFolderNodeState

public FolderNodeState getFolderNodeState(INode masterNode)

Provides access to the folder node state of a node.

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.

Throws:

IllegalArgumentException - The master node does not belong to the managed graph.

Parameters:

masterNode - The node in the MasterGraph for which the state should be returned.

Returns:

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

getFoldingEdgeConverter

public final IFoldingEdgeConverter getFoldingEdgeConverter()

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

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:

NullPointerException - value is null.

Returns:

The FoldingEdgeConverter.

See Also:

DefaultFoldingEdgeConverter, setFoldingEdgeConverter(IFoldingEdgeConverter)

getFoldingEdgeState

public FoldingEdgeState getFoldingEdgeState(FoldingEdgeStateId id)

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

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:

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

Returns:

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

See Also:

getFolderNodeState(INode), FoldingEdgeStateId

getMasterGraph

public final IGraph getMasterGraph()

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

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

Returns:

The MasterGraph.

getViews

public final IEnumerable<IFoldingView> getViews()

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

Returns:

The Views.

See Also:

IFoldingView.getGraph()

hasFolderNodeState

public boolean hasFolderNodeState(INode masterNode)

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

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:

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

Returns:

Whether getFolderNodeState(INode) would return existing state information.

See Also:

getFolderNodeState(INode)

hasFoldingEdgeState

public boolean hasFoldingEdgeState(FoldingEdgeStateId id)

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

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:

id - The id for which state is requested.

Returns:

Whether getFoldingEdgeState(FoldingEdgeStateId) would return existing state information.

See Also:

getFoldingEdgeState(FoldingEdgeStateId)

prepareFoldingView

protected void prepareFoldingView(IFoldingView foldingView)

Callback that 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.

Subclasses could override this method to register additional IMapper 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:

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

setFolderNodeConverter

public final void setFolderNodeConverter(IFolderNodeConverter value)

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

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.

Parameters:

value - The FolderNodeConverter to set.

See Also:

DefaultFolderNodeConverter, getFolderNodeConverter()

setFoldingEdgeConverter

public final void setFoldingEdgeConverter(IFoldingEdgeConverter value)

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

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:

NullPointerException - value is null.

Parameters:

value - The FoldingEdgeConverter to set.

See Also:

DefaultFoldingEdgeConverter, getFoldingEdgeConverter()

updateFolderNodeStates

public void updateFolderNodeStates(INode masterNode)

Triggers a call to IFolderNodeConverter.updateFolderNodeState(FolderNodeState, IFoldingView, INode, INode) for all view nodes that represent the given masterNode in its collapsed state.

In all Views that are currrently showing the node in collapsed state, the view-local state will be updated via a call to the IFolderNodeConverter's IFolderNodeConverter.updateFolderNodeState(FolderNodeState, IFoldingView, INode, INode) 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.

Throws:

IllegalArgumentException - If the provided master node does not belong to the master graph.

Parameters:

masterNode - The master node that belongs to the MasterGraph.

See Also:

updateFoldingEdgeStates(IEdge)

updateFoldingEdgeStates

public void updateFoldingEdgeStates(IEdge masterEdge)

Triggers a call to IFoldingEdgeConverter.updateFoldingEdgeState(FoldingEdgeState, IFoldingView, IEdge, java.util.List) for all folder edges that represent the given masterEdge.

In all Views that are currrently showing the view edge for the provided master edge, the view-local state will be updated via a call to the IFoldingEdgeConverter's IFoldingEdgeConverter.updateFoldingEdgeState(FoldingEdgeState, IFoldingView, IEdge, java.util.List) 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.

Throws:

IllegalArgumentException - If the provided master edge does not belong to the master graph.

Parameters:

masterEdge - The master edge that belongs to the MasterGraph.

See Also:

updateFolderNodeStates(INode)