- I
- I
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 masterGraph which 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 IFoldingView stores the view graph and manages the mapping from elements of the master graph to elements in the view graph and vice versa. Typically nodes and edges are being copied from the masterGraph and they share many of their properties by reference (e.g. style). However if group nodes are being represented by collapsed group nodes in this view, they 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 and can be obtained and modified via the FoldingManager's methods getFoldingEdgeState for folding edges and getFolderNodeState for folder nodes in the absence of a corresponding IFoldingView view instance.
Developers should never implement this interface themselves. Rather, an implementation is provided by the framework and can be obtained from the FoldingManager's method createFoldingView. This implementation provides a folding-enabled IGraph implementation in its graph property:
// 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 = viewGraphFor folding enabled graphs foldingView always returns the IFoldingView implementation which manages the graph:
const foldingView = viewGraph.foldingViewThis interface extends the IPropertyObservable interface. This can be used to easily monitor the validity of this view. Also changes to the localRoot property will be published via this event.
See Also
- A brief description of the interface's API and some usage aspects is given in the section Working with Folding. Class
FoldingManager's central role for folding support in general is discussed in the section Folding Revisited. Developer's Guide
API
- FoldingManager
Members
Properties
By default this property is set to true which assures that this view will never become invalid. It is the responsibility of the client code to check for the validity of this view before trying to modify it if this feature is disabled.
Upon change the property-changed event is fired.
See Also
Developer's Guide
By default, this property is set to false, however depending on the use case it may make sense to enqueue IUndoUnits for this type of operation.
Note that the UndoEngine is associated with the masterGraph. Therefore, undo actions are valid for the master and all view graphs. In an environment where view and master or multiple views are editable at the same time, this might lead to unexpected results like undoing a collapse on another view.
Upon change the property-changed event is fired.
See Also
Developer's Guide
API
- autoSwitchToAncestor
Gets the view graph managed by this view.
The view graph is the IGraph implementation that provides the actual view data. The view graph instance holds the elements in the view only, which in general is a subset of the masterGraph.
The returned IGraph instance has this implementation of IFoldingView in its ILookup.
Examples
This example shows how to create a folding view and set its graph (the view graph) as the GraphComponent 's 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 = viewGraphThe view graph provides the IFoldingView instance is managed by in its ILookup:
const graph = view.graph
console.log(graph.foldingView === view) // true
// is the same as
console.log(graph.lookup(IFoldingView) === view) // trueSee Also
Developer's Guide
- localRoot is changed
- node-created is raised
- node-removed is raised
- is-group-node-changed is raised
See Also
Developer's Guide
API
- autoSwitchToAncestor
Gets or sets an entity of the masterGraph hierarchy to serve as the virtual root for the view's local hierarchy.
This property can be set to any group node in the masterGraph's hierarchy whose contents will then be represented in this view. Note that the root of the view's local hierarchy is not set to the same instance.
If set to null the root of the local hierarchy is the overall root of the master graph.
Upon change the property-changed event is fired for this property. Additionally, one might be fired for invalid
Examples
// get the folding view to manage expanding and collapsing
const view = graph.foldingView!
// show only the contents of groupNode
// as if they were in a separate graph
view.localRoot = group
graph.contains(group) // false
console.log(graph.nodes.size) // 3 (node1, node2, node3)
console.log(graph.edges.size) // 3 (1 -> 2, 2 -> 3, 3 -> 1)
// show the entire graph
// i.e. the root of the master graph is the root of this view graph
view.localRoot = null
graph.contains(group) // true
console.log(graph.nodes.size) // 6 (all nodes)
console.log(graph.edges.size) // 5 (all edges)Sample Graphs
= nullSee Also
Developer's Guide
Gets the manager that created this view and that contains a reference to the masterGraph.
Examples
// get the folding view from the view graph
const view = viewGraph.foldingView!
// get the manager from the folding view
const manager = view.manager
// get the master graph from the manager
const masterGraph = manager.masterGraphSee Also
Developer's Guide
Methods
If a group node that belongs to this view's hierarchy is in expanded state, calling this method will remove the children from this view. This method will do nothing if the node is already collapsed. Note that collapsing a group node will make it a non-group node in the hierarchy.
The collapsed group node has its own separate set of attributes which may be different from the expanded node. To be precise, the attributes of a collapsed node, i.e. its layout and style (as well as its labels and ports) can be obtained using the getFolderNodeState method. In contrast, the expanded group node is an exact copy of its master node.
Because of these differences it may appear that the node changes its location during a collapse operation. This behavior ensures that collapsing a node does not modify the state of the model (only the state in the view is changed), but depending on the application this may confuse the user because he might lose their mental map of the diagram. In order to customize the behavior custom code can register with the group-collapsed event to perform the necessary modifications, like adjusting the view port or moving the node to the desired location.
In addition to that this method can also be used for master nodes which are currently not represented in this view. In this case these nodes will be displayed as collapsed the next time they will be included in this view.
Collapsing a group node interactively is handled by NavigationInputMode and by command COLLAPSE_GROUP.
Parameters
- groupNode: INode
- A group node that is part of the graph or the masterGraph.
Examples
// get the folding view to manage expanding and collapsing
const view = graph.foldingView!
// group is initially expanded
view.isExpanded(group) // true
// collapse group
view.collapse(group)
view.isExpanded(group) // false
console.log(graph.isGroupNode(group)) // false
console.log(graph.nodes.size) // 3 (node4, node5, group)
console.log(graph.edges.size) // 2 (group -> node4, node5 -> group)
// expand group again
view.expand(group)
view.isExpanded(group) // true
console.log(graph.isGroupNode(group)) // true
console.log(graph.nodes.size) // 6 (all nodes)
console.log(graph.edges.size) // 5 (all edges)Sample Graphs
Group node is expandedSee Also
Developer's Guide
API
- isExpanded, expand
Directly creates a collapsed node on this instance with the given parameters.
parent must be part of the Folded Graph View or null to create a folder at the root of the current hierarchy. It will be converted into a group node if necessary. The returned INode is also part of the Folded Graph View.Parameters
- parent?: INode
- The optional parent node in the graph. If omitted, a new folder will be created at the root.
- layout?: Rect
- The optional layout for the collapsed node or
nullif the default should be used. - style?: INodeStyle
- The optional style for the collapsed node or
nullif the default should be used. - tag?: INode['tag']
- The optional tag of the node which will be used for both the group in the master graph and the folder.
Return Value
Examples
const graph = view.graph
// CreateGroupNode creates a group node
const group = graph.createGroupNode()
console.log(graph.isGroupNode(group)) // true
// CreateFolderNode creates a normal node
const folder = view.createFolderNode()
console.log(graph.isGroupNode(folder)) // false
// which can expand though
view.expand(folder)
console.log(graph.isGroupNode(folder)) // truecreateGroupNode on the view graph creates a group node which is initially expanded. createFolderNode creates a node which is an initially collapsed group node (i.e. a folder node)
const graph = view.graph
// CreateFolderNode creates a normal node on the view graph
const folder = view.createFolderNode()
console.log(graph.isGroupNode(folder)) // false
// but its master element is a group on the master graph
const master = view.getMasterItem(folder)
const masterGraph = view.manager.masterGraph
console.log(masterGraph.isGroupNode(master)) // trueThe folder node is a group node in the master graph, though.
See Also
Developer's Guide
If a node that belongs to this view is in collapsed state, calling this method will make the children appear in this view. This method will do nothing if the node is already expanded. Note that expanding a collapsed group node will make the node a group node, whereas a collapsed group node is no group node in this hierarchy and thus cannot have visible children.
The expanded group node has its own set of attributes which may be different from the collapsed node. To be precise, the expanded group node is an exact copy of its master node, i.e. it has the same layout and style (as well as the same set of labels and ports). In contrast, a collapsed node has a separate set of attributes which can be obtained using the getFolderNodeState method.
Because of these differences it may appear that the node changes its location during an expand operation. This behavior ensures that expanding a node does not modify the state of the model by moving the node or its descendants (only the state in the view is changed), but depending on the application this may confuse the user because he might lose their mental map of the diagram. In order to customize the behavior custom code can register with the group-expanded event to perform the necessary modifications, like adjusting the view port or moving the node and its descendants to the desired location.
In addition to that this method can also be used for master nodes which are currently not represented in this view. In this case these nodes will be displayed as expanded the next time they will be included in this view.
Expanding a group node interactively is handled by NavigationInputMode and by command EXPAND_GROUP.
Parameters
- groupNode: INode
- A group node that is part of the graph or the masterGraph.
Examples
// get the folding view to manage expanding and collapsing
const view = graph.foldingView!
// group is initially expanded
view.isExpanded(group) // true
// collapse group
view.collapse(group)
view.isExpanded(group) // false
console.log(graph.isGroupNode(group)) // false
console.log(graph.nodes.size) // 3 (node4, node5, group)
console.log(graph.edges.size) // 2 (group -> node4, node5 -> group)
// expand group again
view.expand(group)
view.isExpanded(group) // true
console.log(graph.isGroupNode(group)) // true
console.log(graph.nodes.size) // 6 (all nodes)
console.log(graph.edges.size) // 5 (all edges)Sample Graphs
Group node is expandedSee Also
Developer's Guide
API
- isExpanded, collapse
Helper method that corresponds to the getMasterItem method, but is used for folding edges only.
Since the graph view that is associated with this instance maintains a copy of the entities in the manager's masterGraph, there is a mapping between elements that belong to this view's graph and the elements in the master graph.
Since folding edges can represent more than one master edge, this method can be used to query all of the master edges that the provided folding edge represents. If the folding edge corresponds to a single master edge, the result will enumerate that edge only.
Parameters
- foldingEdge: IEdge
- The folding edge for which the master edges should be returned.
Return Value
- IListEnumerable<IEdge>
- An enumerable that can enumerate all of the edges in the masterGraph that are being represented by the folding edge in this view.
See Also
Developer's Guide
API
- addToExistingFoldingEdge, getViewItem
Helper method that can be used to retrieve the original "master" items in the masterGraph that is managed by the manager associated with this view.
Since the graph view that is associated with this instance maintains a copy of the entities in the manager's masterGraph, there is a mapping between elements that belong to this view's graph and the elements in the master graph.
This method can be called for the elements contained in this IGraph and will return the corresponding item in the master graph that the element corresponds to, if any. Note that for some items in the graph, there is no master item in the masterGraph, e.g. the IPort instances to which folding edges connect have no corresponding ports in the master graph. The same holds true for the bends and labels of folding edges and folder nodes.
For folding edges, this method will yield the main representing edge in the master, if the folding edge represents more than one master edge. For nodes, the master node will be returned, no matter whether the node is currently collapsed or not.
Parameters
- item: T
- The item that is part of this graph for which the original "master" item in the masterGraph will be returned.
Return Value
- T
See Also
Developer's Guide
API
- getViewItem
Helper method that can be used to retrieve the items in this graph-view for all items that are part of the masterGraph that is associated with the manager of this instance.
Since the graph view that is associated with this instance maintains a copy of the entities in the manager's masterGraph, there is a mapping between elements that belong to the master graph and the elements in the graph of this view.
This method can be called for the elements contained in this masterGraph's items and will return the corresponding item in this view's graph if the element is represented by an item in this view. Note that for some items in the masterGraph, there may be no item in the graph instance, e.g. those elements which are part of a collapsed subtree in the masterGraph hierarchy or those items that do not belong to the subtree that is induced by the localRoot of this view. Also, for nodes and edges that are being represented by dummies in this view, labels, ports, and bends are not being represented directly by corresponding entities in this graph. If more than one edge is represented by a folding edge in this view, this method will yield the same folding edge instance for each of them.
Parameters
- item: T
- An item that is part of the masterGraph that is associated with the manager of this instance.
Return Value
- T
- An item in the local graph view that corresponds to the
itemornull, if the item is not currently being represented in this view.
See Also
Developer's Guide
API
- getMasterItem, getMasterEdges
Expanded group nodes will have all of their children visible in this view.
The groupNode can be either a node of the view or the masterGraph. If the node is from the master graph and is currently not represented in this view, this method will return the expanded state it will have the next time it will be included in this view.
Parameters
Return Value
- boolean
true, if the group node can be collapsed.
Examples
// get the folding view to manage expanding and collapsing
const view = graph.foldingView!
// group is initially expanded
view.isExpanded(group) // true
// collapse group
view.collapse(group)
view.isExpanded(group) // false
console.log(graph.isGroupNode(group)) // false
console.log(graph.nodes.size) // 3 (node4, node5, group)
console.log(graph.edges.size) // 2 (group -> node4, node5 -> group)
// expand group again
view.expand(group)
view.isExpanded(group) // true
console.log(graph.isGroupNode(group)) // true
console.log(graph.nodes.size) // 6 (all nodes)
console.log(graph.edges.size) // 5 (all edges)Sample Graphs
Group node is expanded: isExpanded(group) == trueSee Also
Developer's Guide
Determines whether the specified item is a folding state in this view.
Parameters
- item: IModelItem
Return Value
- boolean
- Whether the item is in a folding state and is not an exact copy of an item in the masterGraph.
null implementations for the types, nor does it have to return the same instance any time. Also, it depends on the type and context whether the instance returned stays up to date or needs to be re-obtained for further use.Parameters
- type: Constructor<T>
- the type for which an instance shall be returned
Return Value
- T
- an instance that is assignable to the type or
null
See Also
Developer's Guide
Defined in
ILookup.lookupUpdates the master group node of a single folder node in this view using updateGroupNodeState.
Parameters
See Also
Updates the masters of a single folding edge from this view using updateMasterEdges.
Parameters
See Also
Events
Occurs whenever a group has been collapsed.
Properties of
ItemEventArgs<INode>- item: T
- Gets the item that is the subject of the event.
Occurs whenever a group has been expanded.
Properties of
ItemEventArgs<INode>- item: T
- Gets the item that is the subject of the event.
Occurs when a property changes of this instance changed its value.
Properties of
PropertyChangedEventArgs- propertyName: string
- The name of the changed property.