Copying Elements of a Graph

This section describes how graph elements can be copied on a low level base. For clipboard operations please see the sections Clipboard and Customizing the Clipboard.

A graph or a part of a graph can be copied using class GraphCopier. Its various copy methods provide a means to fine control the copied elements.

copy(sourceGraph: IGraph, targetGraph: IGraph)

Copies all elements of the source graph into the target graph.

copy(sourceGraph: IGraph, filter: Predicate<IModelItem>, targetGraph: IGraph, offset: Point, elementCopiedCallback: ElementCopiedCallback)

Copies elements from the source graph into the target graph. Copies only elements for which the filter returns true. After the elements are copied the offset is applied to their position and the given element copied callback is applied on the copied item.

copy(sourceGraph: IGraph, filter: Predicate<IModelItem>, targetGraph: IGraph, targetRootNode: INode, offset: Point, elementCopiedCallback: ElementCopiedCallback)

Copies elements from the source graph into the target graph, using the provided rootNode as parent (see Grouping Nodes) for the copied elements. Copies only elements for which the filter returns true. After the elements are copied the offset is applied to their position and the given element copied callback is applied on the copied item.

Note that the source and target graph can be the same graph.

// copy the elements of 'sourceGraph' to 'targetGraph'
const copier = new GraphCopier()
copier.copy(sourceGraph, targetGraph)

// copy some elements (on the same graph)
const copier = new GraphCopier()
copier.copy(graph, (item) => item.tag === 'copy me', graph)

Copying Styles, Model Parameters, and Tags

By default GraphCopier clones styles and model parameters of the copied model items. For tags, however, the same reference is shared between original and copy. This can be customized using the following properties:

clone

Defines whether styles, model parameters, or tags are cloned or shared. A bitwise combination of CloneTypes.

referentialIdentityTypes

Defines whether styles, model parameters, or tags are cloned or shared between the copied items. A bitwise combination of CloneTypes.

It is also possible to configure that copies of items which share the same instance of a style, parameter, or tag share the same instance, too, which is, however, a clone of the original. Let’s say nodes n1 and n2 share the same style instance s1. Then their copies share the same style instance s2 which is, however, another reference than the original s1. This is contolled by referentialIdentityTypes which is enabled for all types of elements by default.

// clone node label model parameter and tags but nothing else
const copier = new GraphCopier()
copier.clone = CloneTypes.LABEL_MODEL_PARAMETER | CloneTypes.TAGS

Only styles, model parameters, and tag objects which implement ICloneable can be cloned. For all other elements the same reference is shared. Note that all built-in styles and model parameter of yFiles for HTML are cloneable.

Grouping and Folding

The GraphCopier supports both grouping and folding.

when using a GraphCopier with a folding-enabled graph it is mandatory to use folding-enabled master graphs as both source and target graph.

copyGrouping

Whether to copy grouping information. When set to false a grouped graph loses its grouping hierarchy upon copying. This can be used to "flatten" a grouped graph.

copyFoldingStates

Whether to copy the folding states together with the copied items.

const copier = new GraphCopier()
// the copier works on the master graph
const sourceView = sourceGraph.foldingView
const sourceMaster = sourceView.manager.masterGraph
const targetView = targetGraph.foldingView
const targetMaster = targetView.manager.masterGraph
// we want the folding states
// to be copied with the master items
copier.copyFoldingStates = true
// we only copy items with "copy me" as tag
const filter = (item) => item.tag === 'copy me'
// after a node is copied we collapse it
// if its original is a collapsed group node
const callback = (original, copy) => {
  if (original instanceof INode && copy instanceof INode && !sourceView.isExpanded(original)) {
    targetView.collapse(copy)
  }
}
// we don't move items after copying
const offset = Point.ORIGIN
copier.copy(sourceMaster, filter, targetMaster, offset, callback)

const copier = new GraphCopier()
// the copier works on the master graph
const sourceView = sourceGraph.foldingView!
const sourceMaster = sourceView.manager.masterGraph
const targetView = targetGraph.foldingView!
const targetMaster = targetView.manager.masterGraph
// we want the folding states
// to be copied with the master items
copier.copyFoldingStates = true
// we only copy items with "copy me" as tag
const filter = (item: IModelItem): boolean => item.tag === 'copy me'
// after a node is copied we collapse it
// if its original is a collapsed group node
const callback = (original: IModelItem, copy: IModelItem): void => {
  if (original instanceof INode && copy instanceof INode && !sourceView.isExpanded(original)) {
    targetView.collapse(copy)
  }
}
// we don't move items after copying
const offset = Point.ORIGIN
copier.copy(sourceMaster, filter, targetMaster, offset, callback)