C

GraphClipboard

Clipboard implementation for IGraph instances.
Inheritance Hierarchy

Remarks

This implementation copies a given graph to an internally held clipboardGraph. The clipboard graph can then be pasted to a target graph instance.

The clipboard can be configured to copy and paste items that depend on other items without copying the items it depends on, e.g. labels, ports, edges, and bends.

Also depending on the selection in the target graph, items can be pasted at multiple locations at once, e.g. a single label can be copied to the clipboard independently and pasted onto several selected target items.

See Also

Developer's Guide

API

IClipboardHelper, cut, copy, onPaste, clipboardGraph

Demos

Shows the graph editing features of the graph component.

Members

Show:

Constructors

Creates a new initially empty clipboard.

Parameters

Properties

Gets the clipboard context for the current clipboard operation.
The context is only valid during cut, copy, onPaste, and duplicate and is null otherwise.
protectedreadonlyfinal
Gets the graph that contains the clipboard's contents.
Gets or sets the type of items that can be copied and pasted using the clipboard.

If the corresponding item type is set in this property, items can be effectively copied.

If the corresponding item type is not set in this property, items will not be pasted, even if they have been explicitly selected. They may be copied to the clipboard and become part of the clipboardGraph, nevertheless though, if they are required as helper items. But these items will not be pasted to the target during paste or duplicate operations.

The default is ALL.

conversionfinal

See Also

Developer's Guide
Gets or sets the type of items that depend on other items but should automatically be copied implicitly to the clipboard if all items that they depend on are explicitly selected for copying.

Labels depend on their owner, like ports depend on their owner. Also bends of course depend on their owning edge.

If the corresponding item type is set in this property, items that depend on other items are implicitly included in the copy operation, if all of the items that they depend on are included recursively, even if they are not included explicitly themselves.

The default is ALL minus NODE, which means that selecting a number of nodes will automatically select all items that directly and indirectly depend on the existence of this set of nodes will be copied to the clipboard, too.

Technically nodes do not depend on anything. Setting this property to a value that includes NODE will include all child nodes for every selected group node.

conversionfinal

See Also

Developer's Guide
Gets or sets the ClipboardGraphCopier instance that will be used to duplicate items inside the graph.
final

See Also

Developer's Guide
Gets or sets the ClipboardGraphCopier instance that will be used to copy the graph from the clipboard to the target graph.
final

See Also

Developer's Guide
Gets or sets the IClipboardIdProvider used by this instance to provide IDs for copied items.

The default implementation simply uses a reference to the original item as ID.

Custom ID can be used to map between items in different graphs.

final
Gets or sets whether to paste edges where either its source or target node was copied while the other was not.
The default is false.
final
Gets or sets the type of items that can be copied and pasted independently of their owning item.

Labels depend on their owner, like ports depend on their owner. Also bends of course depend on their owning edge.

If the corresponding item type is set in this property, items can be copied alone to the clipboard and be pasted onto different owning items.

This enables copying of a label to one or more owners, without having to copy the owner of the label. Also ports can be copied to other IPortOwners and bends to other edges.

The default is ALL which means that all items can be copied to the clipboard even if the items that they depend on are not copied to the clipboard.

Technically owning items are still part of the clipboard as helper items, but these items will not be pasted to the target during paste or duplicate operations.

conversionfinal

See Also

Developer's Guide
Gets whether the clipboard graph is empty.
Gets or sets whether nodes should be automatically put into a group node and if so how this group will be determined.

This property is used by getTargetNode to decide what node to yield as the target group node for the newly pasted node.

The default is SELECTION| PREVIOUS_PARENT.

conversionfinal

See Also

Developer's Guide
Gets or sets a vector that will be used to move nodes and bends by after they have been pasted to the target graph.
This offset is modified by several operations:
conversionfinal

See Also

Developer's Guide
Gets or sets the increment the pasteOffset is increased by after a paste operation.

The offset is incremented to avoid that repeatedly pasted items are pasted exactly over the last pasted ones.

Default is (15, 15).

conversionfinal

Examples

Setting the pasteOffsetIncrement to 0,0 will prevent the pasted items from being moved from their original location.
clipboard.pasteOffsetIncrement = Point.ORIGIN

See Also

Developer's Guide
Gets or sets the ClipboardGraphCopier instance that will be used to copy the graph to the clipboard.
final

See Also

Developer's Guide

Methods

Clears the clipboard's contents.
Copies the itemsToCopy to the clipboard graph.
For each item copied to the clipboard graph, the onItemCopied method will be called. The actual work of this method is delegated to the toClipboardCopier's copy method.

Parameters

sourceGraph: IGraph
The graph to copy the contents from.
itemsToCopy?: IEnumerable<IModelItem>
The source graph's items which should be copied. Items which are not in the sourceGraph are ignored. If none are provided, the entire sourceGraph is copied.
Factory method that creates the context for the upcoming calls to the IClipboardHelper methods.
protected

Parameters

sourceGraph: IGraph
The source graph of the operation.
targetGraph: IGraph
The target graph of the operation.
context?: IInputModeContext
A valid input mode context the lookup method should return or null if no such context is available.

Return Value

IGraphClipboardContext
A context that has the properties configured according to the parameters.
Cuts the items indicated by itemsToCut to the clipboard and removes them from the graph.
This method delegates the core work to onCopy which will use the toClipboardCopier to copy the cut items to the clipboard.

Parameters

sourceGraph: IGraph
The graph to cut the items from.
itemsToCut: IEnumerable<IModelItem>
The items to cut. Items which are not in the sourceGraph are ignored. If none are provided, the entire sourceGraph will be cut.
Duplicates the itemsToDuplicate from and to the graph.
The clipboardGraph is not altered by this operation.

Parameters

context: IInputModeContext
The current IInputModeContext.
graph: IGraph
The graph whose items should be duplicated.
itemsToDuplicate?: IEnumerable<IModelItem>
The items which should be duplicated. If none are provided the entire graph is duplicated.
itemDuplicated?: function(IModelItem, IModelItem): void
An item copied callback which gets invoked for each item which has been duplicated. The two parameters passed into the callback are guaranteed to be part of the graph.
Provides the original parent group node or its ancestor for the given sourceNode.

This method is called by getTargetNode if parentNodeDetection contains PREVIOUS_PARENT and detection modes with higher priority didn't detect a suitable new parent.

If the original parent has been removed from the graph or ignoreDistance is false and it has been moved too far away in between the copy and paste operation, the parent's parent will be checked instead.

protectedfinal

Parameters

context: ClipboardOperationContext
The information which items to copy.
sourceNode: INode
The node to be duplicated from the source graph or copied from the clipboardGraph for which the parent shall be found.
ignoreDistance: boolean
Whether the distance, the previous parent might have been moved away in between the copy and paste operation, is ignored. Note that this might increase the parent's size considerably.

Return Value

INode
The parent or its ancestor node of the given sourceNode.
Gets a folding state of an edge for a given FoldingEdgeStateId.
This method might be overridden to map folding states for edges whose source or target node's hierarchy might have changed during a paste operation.
protected

Parameters

edge: IEdge
The edge to get the folding state for.
id: FoldingEdgeStateId
The original FoldingEdgeStateId to get the folding state for. Passing null will return the folding state which was visible when the edge was copied into the clipboard.

Return Value

IEdge
The folding state which is mapped to the given id. May be null.
Returns the ID which is linked with the given clipboard item.
Meant for use in methods getTargetNode, getTargetPort, getTargetLabeledItem, getTargetPortOwner , or getTargetEdge. Can be used together with the idProvider to retrieve the item in the original graph from which the clipboardItem has been copied.
protectedfinal

Parameters

clipboardItem: IModelItem
An IModelItem which lives in the clipboard graph.

Return Value

any
The ID which represents the item from which clipboardItem has originally been copied into the clipboard. idProvider's getItem can be used to retrieve the original item. Note that both, the returned ID and the item returned by getItem might be null.

Examples

Retrieving the original item which has been copied into the clipboard
/**
 * @param _context - The information which items to copy.
 * @param sourceLabel - The label to be duplicated from the source graph or copied from the ClipboardGraph.
 */
getTarget(
  _context: ClipboardOperationContext,
  sourceLabel: ILabel,
): ILabelOwner | null {
  // sourceLabel lives in the clipboard graph

  // get the original label, i.e. the label which has been copied from the original graph
  const originalLabel = this.idProvider.getItem(
    this.clipboardContext!,
    this.getId(sourceLabel),
  ) as ILabel

  // return the original label's owner as the pasted label's owner
  return originalLabel.owner
}
Gets an ILabelModelParameter for the given sourceLabel to be placed at the given newTargetOwner.
Implementations might delegate to copyLabelLayoutParameter to copy the existing parameter or use the nodeDefaults or edgeDefaults to create a new one. Note that the type of the owner might have changed during the copy operation.
protected

Parameters

copier: ClipboardGraphCopier
The GraphCopier whose copyLabelLayoutParameter method can be used to copy the existing parameter.
targetGraph: IGraph
The targetGraph whose nodeDefaults or edgeDefaults can be used to create a new parameter.
sourceLabel: ILabel
The label in the sourceGraph to be copied.
newTargetOwner: ILabelOwner
The new owner in the targetGraph for the label.

Return Value

ILabelModelParameter
An ILabelModelParameter for the copied label.
Gets an IPortLocationModelParameter for the given sourcePort to be placed at the given newTargetOwner.
Implementations might delegate to copyPortLocationParameter to copy the existing parameter or use the nodeDefaults or edgeDefaults to create a new one. Note that the type of the owner might have changed during the copy operation.
protected

Parameters

copier: ClipboardGraphCopier
The GraphCopier whose copyPortLocationParameter method can be used to copy the existing parameter.
targetGraph: IGraph
The targetGraph whose nodeDefaults or edgeDefaults can be used to create a new parameter.
sourcePort: IPort
The port sourceGraph to be copied.
newTargetOwner: IPortOwner
The new owner in the targetGraph for the port.

Return Value

IPortLocationModelParameter
An IPortLocationModelParameter for the copied port.
Provides an IEdge where the given sourceBend can be added to.
Called from within paste or duplicate for IBends whose edge is not copied to provide a new owner. Might return null if no target for the given sourceBend is found. In this case the bend will not be copied.
protected

Parameters

context: ClipboardOperationContext
The information which items to copy.
sourceBend: IBend
The bend to be duplicated from the source graph or copied from the clipboardGraph.

Return Value

IEdge
An IEdge for the bend to be added to or null if the bend should not be copied.

See Also

Developer's Guide
Provides an ILabelOwner where the given sourceLabel can be added to.
Called from within paste or duplicate for ILabels whose owners are not copied to provide a new owner. Might return null if no target for the given sourceLabel is found. In this case the label will not be copied.
protected

Parameters

context: ClipboardOperationContext
The information which items to copy.
sourceLabel: ILabel
The label to be duplicated from the source graph or copied from the clipboardGraph.

Return Value

ILabelOwner
An ILabelOwner for the label to be added to or null if the label should not be copied.

Examples

Retrieving the original item which has been copied into the clipboard
/**
 * @param _context - The information which items to copy.
 * @param sourceLabel - The label to be duplicated from the source graph or copied from the ClipboardGraph.
 */
getTarget(
  _context: ClipboardOperationContext,
  sourceLabel: ILabel,
): ILabelOwner | null {
  // sourceLabel lives in the clipboard graph

  // get the original label, i.e. the label which has been copied from the original graph
  const originalLabel = this.idProvider.getItem(
    this.clipboardContext!,
    this.getId(sourceLabel),
  ) as ILabel

  // return the original label's owner as the pasted label's owner
  return originalLabel.owner
}

See Also

Developer's Guide
Provides a parent group node for the given sourceNode considering the parentNodeDetection.
Called from within paste or duplicate for INodes to place them inside a group node. Might return null if the given node should be placed at the root or if the graph is not grouped.
protected

Parameters

context: ClipboardOperationContext
The information which items to copy.
sourceNode: INode
The node to be duplicated from the source graph or copied from the clipboardGraph.
pasteLocation: Point
The location to look for the parent group if parentNodeDetection contains AT_LOCATION

Return Value

INode
The new parent group of the node or null if the node should be placed at the root of the hierarchy or if the graph is not grouped.

See Also

Developer's Guide
API
parentNodeDetection
Provides an IPort where the given sourceEdge can be added to.
Called from within paste or duplicate for IEdges whose source or target ports are not copied to provide a new port. Might return null if no target for the given sourceEdge is found. In this case, the edge will not be copied.
protected

Parameters

context: ClipboardOperationContext
The information which items to copy.
sourceEdge: IEdge
The edge to be duplicated from the source graph or copied from the clipboardGraph.
atSource: boolean
Whether to look for a source port.

Return Value

IPort
An IPort for the edge to be added to or null if the edge should not be copied.

See Also

Developer's Guide
Provides an IPortOwner where the given sourcePort can be added to.
Called from within paste or duplicate for IPorts whose owners are not copied to provide a new owner. Might return null if no target for the given sourcePort is found. In this case the port will not be copied.
protected

Parameters

context: ClipboardOperationContext
The information which items to copy.
sourcePort: IPort
The port to be duplicated from the source graph or copied from the clipboardGraph.

Return Value

IPortOwner
An IPortOwner for the port to be added to or null if the port should not be copied.

See Also

Developer's Guide
Whether the given clipboardItem of the clipboardGraph was copied from a folding state of its owner.
protectedfinal

Parameters

clipboardItem: IModelItem

Return Value

boolean
true if the given item was copied from a folding state.
Whether the given clipboardItem is a "helper" item which should not be pasted.
A helper item is used to keep IModelItems which cannot exist without an owner in the clipboardGraph (e.g. ILabels).
final

Parameters

clipboardItem: IModelItem
The item to test.

Return Value

boolean
true if the item is a "helper" item.
Called from copy and delegates to copy on the current toClipboardCopier instance.
protected

Parameters

copyContext: ClipboardOperationContext
Contains the information on which items to copy.
targetRootNode?: INode
The node to use as the root node in the grouped targetGraph.
itemCopiedCallback?: function(IModelItem, IModelItem): void
The delegate to pass on. For each item that is copied during the operation to the clipboard, this callback will be passed the original and the copy of the item. In case the source graph is a folding view graph both items are passed as master items or folding state items if a master item does not exist.
Called from duplicate and delegates to copy on the current duplicateCopier instance.
protected

Parameters

duplicateContext: ClipboardOperationContext
Contains the information which items to duplicate.
itemDuplicatedCallback: function(IModelItem, IModelItem): void
The delegate to pass on. For each item that is duplicated during the operation, this callback will be passed the original and the copy of the item. In case the source graph is a folding view graph, both items are passed as master items or folding state items if a master item does not exist.
Invoked for each item that has been copied into the clipboard graph in response to a copy operation.
This implementation tries to retrieve an IClipboardHelper from the context which itself retrieved it originally from the original item's lookup. If one is found, onCopied is called. The found instance is kept until the next onCopy or cut and its onPasted method is invoked upon onItemPasted later.
protected

Parameters

context: ClipboardOperationContext
The context to get the IClipboardHelper from.
original: IModelItem
The original item from the source graph instance. If the source graph is a managed folding view, this is always a master item.
copy: IModelItem
The copy from the clipboard graph.
Invoked for each item that has been copied into the clipboard graph in response to a cut operation.
This implementation tries to retrieve an IClipboardHelper from the context which itself retrieved it originally from the original item's lookup. If one is found, onCut is called. The found instance is kept until the next onCopy or cut and its onPasted method is invoked upon onItemPasted later.
protected

Parameters

context: ClipboardOperationContext
The context to get the IClipboardHelper from.
original: IModelItem
The original item from the source graph instance. If the source graph is a managed folding view, this is always a master item.
copy: IModelItem
The copy from the clipboard graph.
Invoked for each item that has been duplicated into the target graph in response to a duplicate operation.
This method will query the context for an IClipboardHelper. If one is found, onDuplicated is called.
protected

Parameters

context: ClipboardOperationContext
The context to get the IClipboardHelper from.
original: IModelItem
The original item from the source graph instance. If the source graph is a managed folding view, this is always a master item.
copy: IModelItem
The copy from the target graph.
Invoked for each item that has been pasted into the target graph in response to a onPaste operation.
This method will use a previously stored IClipboardHelper to let it finish its work.
protected

Parameters

context: ClipboardOperationContext
A context which provides additional information.
original: IModelItem
The original item from the clipboard graph instance. If the target graph is a managed folding view, this is always a master item.
copy: IModelItem
The copy from the target graph.
Called during paste operation to call copy on the current fromClipboardCopier instance.
protected

Parameters

context: ClipboardOperationContext
The operation context to get, e.g., the targetGraph from.
itemCopiedCallback: function(IModelItem, IModelItem): void
The delegate to pass on. For each item that is copied during the operation from the clipboard, this callback will be passed the original and the copy of the item. In case the targetGraph is a folding view graph, the original item is passed as master items or folding state items if a master item does not exist. The copied item is always part of the targetGraph.
targetRootNode?: INode
The node to use as the root node in the grouped targetGraph.
targetOwners?: IEnumerable<IModelItem>
Model items which can be used as target for pasted clipboard items which need an owner (e.g., ILabels which were copied without their owner). If null, the previous owners are used if they are available in the targetGraph or items may not be pasted if no target owner could be found. Often the graphSelection is used as possible target owners.
pasteLocation?: Point
The location to look for the parent group of a pasted node if parentNodeDetection contains AT_LOCATION.

See Also

Developer's Guide
Pastes the itemsToPaste from the clipboardGraph to the targetGraph.

For each item pasted into the graph, the itemPasted delegate will be invoked, and the onItemPasted method will be called. The actual work of this method is delegated to the fromClipboardCopier's copy method.

Providing valid targetOwners allows for pasting ILabels, IPorts, IBends, and IEdges without valid owners.

Parameters

targetGraph: IGraph
The graph to paste the contents in.
itemsToPaste?: IEnumerable<IModelItem>
The items to copy from the clipboard graph. If none are provided, all items in the clipboard graph are pasted.
itemPasted?: function(IModelItem, IModelItem): void
The callback to use for each item that has been pasted. For each item that is copied during the operation from the clipboard, this callback will be passed the original and the copy of the item. In case the targetGraph is a folding view graph, the original item is passed as master items or folding state items if a master item does not exist. The copied item is always part of the targetGraph.
targetOwners?: IEnumerable<IModelItem>
Model items which can be used as a target for clipboard items that need an owner (e.g. ILabels which were copied without their owner). If null, the previous owners are used if they are available in the targetGraph or items may not be pasted if no target owner could be found. Often the graphSelection is used as possible target owners.
pasteLocation?: Point
The location at which the center of the clipboard's contents should be positioned or null if their original location moved by the pasteOffset should be used.
context?: IInputModeContext
A valid input mode context. Passing a valid input mode context is required for keeping orthogonal edges at group nodes whose size might be adjusted after the paste operation.
Removes the itemsToRemove from the graph during a cut operation.
protected

Parameters

graph: IGraph
The graph to remove items from.
itemsToRemove: IEnumerable<IModelItem>
The items to remove.

See Also

API
cut

Events

Occurs when the copy operation finished successfully.
All items which were copied into the clipboardGraph are provided in items. Since the clipboard operation has finished, modifying the items does not have any effect.
context: IGraphClipboardContext
The IGraphClipboardContext which is valid for the current clipboard operation.
items: List<IModelItem>
The items which are or were copied during this clipboard operation.

See Also

Developer's Guide
Occurs before the copy operation starts.
IModelItems can be added or removed from the items list. Note that items which are not from the sourceGraph will not be copied.
context: IGraphClipboardContext
The IGraphClipboardContext which is valid for the current clipboard operation.
items: List<IModelItem>
The items which are or were copied during this clipboard operation.

See Also

Developer's Guide
Occurs when the cut operation finished successfully.
All items which were copied into the clipboardGraph are provided in items. Since the clipboard operation has finished, modifying the items does not have any effect.
context: IGraphClipboardContext
The IGraphClipboardContext which is valid for the current clipboard operation.
items: List<IModelItem>
The items which are or were copied during this clipboard operation.

See Also

Developer's Guide
Occurs before the cut operation starts.
IModelItems can be added or removed from the items list. Note that items which are not from the sourceGraph will not be cut.
context: IGraphClipboardContext
The IGraphClipboardContext which is valid for the current clipboard operation.
items: List<IModelItem>
The items which are or were copied during this clipboard operation.

See Also

Developer's Guide
Occurs when the duplicate operation finished successfully.
The duplicates of all duplicated items are provided in items Since the clipboard operation has finished, modifying the items does not have any effect.
context: IGraphClipboardContext
The IGraphClipboardContext which is valid for the current clipboard operation.
items: List<IModelItem>
The items which are or were copied during this clipboard operation.

See Also

Developer's Guide
Occurs before the duplicate operation starts.
IModelItems can be added or removed from the items list. Note that items which are not from the sourceGraph will not be duplicated.
context: IGraphClipboardContext
The IGraphClipboardContext which is valid for the current clipboard operation.
items: List<IModelItem>
The items which are or were copied during this clipboard operation.

See Also

Developer's Guide
Occurs when the onPaste operation finished successfully.
All items which were copied from the clipboardGraph are provided in items. Since the clipboard operation has finished, modifying the items does not have any effect.
context: IGraphClipboardContext
The IGraphClipboardContext which is valid for the current clipboard operation.
items: List<IModelItem>
The items which are or were copied during this clipboard operation.

See Also

Developer's Guide
Occurs before the onPaste operation starts.
IModelItems can be removed from the items list. Note that items which are not from the clipboardGraph will not be pasted.
context: IGraphClipboardContext
The IGraphClipboardContext which is valid for the current clipboard operation.
items: List<IModelItem>
The items which are or were copied during this clipboard operation.

See Also

Developer's Guide

Constants

Gets a GraphClipboard instance that is used by default for clipboard so that it is shared between multiple GraphComponent instances.