Clipboard implementation for IGraph instances.
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.
Related Programming Samples
- Graph Editor
- Shows the graph editing features of the graph component.
Type Details
- yFiles module
- view
See Also
Constructors
Creates a new initially empty clipboard.
Parameters
A map of options to pass to the method.
- pasteOffset - Point
- A vector that will be used to move nodes and bends by after they have been pasted to the target graph. This option sets the pasteOffset property on the created object.
- pasteOffsetIncrement - Point
- The increment the pasteOffset is increased by after a paste operation. This option sets the pasteOffsetIncrement property on the created object.
- toClipboardCopier - ClipboardGraphCopier
- The ClipboardGraphCopier instance that will be used to copy the graph to the clipboard. This option either sets the value directly or recursively sets properties to the instance of the toClipboardCopier property on the created object.
- fromClipboardCopier - ClipboardGraphCopier
- The ClipboardGraphCopier instance that will be used to copy the graph from the clipboard to the target graph. This option either sets the value directly or recursively sets properties to the instance of the fromClipboardCopier property on the created object.
- duplicateCopier - ClipboardGraphCopier
- The ClipboardGraphCopier instance that will be used to duplicate items inside the graph. This option either sets the value directly or recursively sets properties to the instance of the duplicateCopier property on the created object.
- idProvider - IClipboardIdProvider
- The IClipboardIdProvider used by this instance to provide IDs for copied items. This option sets the idProvider property on the created object.
- parentNodeDetection - ParentNodeDetectionModes
- Whether nodes should be automatically put into a group node and if so how this group will be determined. This option sets the parentNodeDetection property on the created object.
- dependentCopyItems - GraphItemTypes
- 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. This option sets the dependentCopyItems property on the created object.
- independentCopyItems - GraphItemTypes
- The type of items that can be copied and pasted independently of their owning item. This option sets the independentCopyItems property on the created object.
- copyItems - GraphItemTypes
- The type of items that can be copied and pasted using the clipboard. This option sets the copyItems property on the created object.
- ignoreEdgesWithOneNode - boolean
- Whether to paste edges where either its source or target node was copied while the other was not. This option sets the ignoreEdgesWithOneNode property on the created object.
Properties
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.
Remarks
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.
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.
Remarks
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.
Gets or sets the ClipboardGraphCopier instance that will be used to duplicate items inside the graph.
Gets or sets the ClipboardGraphCopier instance that will be used to copy the graph from the clipboard to the target graph.
Gets or sets the IClipboardIdProvider used by this instance to provide IDs for copied items.
Remarks
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.
Gets or sets the type of items that can be copied and pasted independently of their owning item.
Remarks
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.
Gets or sets whether nodes should be automatically put into a group node and if so how this group will be determined.
Remarks
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.
Gets or sets a vector that will be used to move nodes and bends by after they have been pasted to the target graph.
Remarks
- The cut operation resets it to ORIGIN.
- The copy operation resets it to pasteOffsetIncrement.
- The duplicate operation sets it temporarily to pasteOffsetIncrement and restores the old value after the operation has finished.
- The paste operation increases the value by pasteOffsetIncrement after the operation has finished.
Gets or sets the increment the pasteOffset is increased by after a paste operation.
Remarks
The offset is incremented to avoid that repeatedly pasted items are pasted exactly over the last pasted ones.
Default is (15, 15).
Examples
clipboard.pasteOffsetIncrement = Point.ORIGINGets or sets the ClipboardGraphCopier instance that will be used to copy the graph to the clipboard.
Methods
Copies the itemsToCopy to the clipboard graph.
Remarks
Parameters
A map of options to pass to the method.
- 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
sourceGraphare ignored. If none are provided, the entiresourceGraphis copied.
createContext
(sourceGraph: IGraph, targetGraph: IGraph, context?: IInputModeContext) : IGraphClipboardContextFactory method that creates the context for the upcoming calls to the IClipboardHelper methods.
Parameters
A map of options to pass to the method.
- 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
nullif no such context is available.
Returns
- ↪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.
Remarks
Parameters
A map of options to pass to the method.
- sourceGraph - IGraph
- The graph to cut the items from.
- itemsToCut - IEnumerable<IModelItem>
- The items to cut. Items which are not in the
sourceGraphare ignored. If none are provided, the entiresourceGraphwill be cut.
duplicate
(context: IInputModeContext, graph: IGraph, itemsToDuplicate?: IEnumerable<IModelItem>, itemDuplicated?: function(IModelItem, IModelItem):void)Duplicates the itemsToDuplicate from and to the graph.
Remarks
Parameters
A map of options to pass to the method.
- 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
graphis 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.Signature Details
function(original: IModelItem, copy: IModelItem)Callback delegate used by GraphCopier, ClipboardGraphCopier, and the like.Parameters
- original - IModelItem
- The element that has been copied.
- copy - IModelItem
- The copy of the original element.
findParentByPreviousParent
(context: ClipboardOperationContext, sourceNode: INode, ignoreDistance: boolean) : INodeProvides the original parent group node or its ancestor for the given sourceNode.
Remarks
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.
Parameters
A map of options to pass to the method.
- 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.
Returns
- ↪INode?
- The parent or its ancestor node of the given
sourceNode.
Gets a folding state of an edge for a given FoldingEdgeStateId.
Remarks
Parameters
A map of options to pass to the method.
- edge - IEdge
- The edge to get the folding state for.
- id - FoldingEdgeStateId
- The original FoldingEdgeStateId to get the folding state for. Passing
nullwill return the folding state which was visible when the edge was copied into the clipboard.
Returns
- ↪IEdge?
- The folding state which is mapped to the given
id. May benull.
Returns the ID which is linked with the given clipboard item.
Remarks
clipboardItem has been copied.Parameters
A map of options to pass to the method.
- clipboardItem - IModelItem
- An IModelItem which lives in the clipboard graph.
Returns
- ↪any?
- The ID which represents the item from which
clipboardItemhas 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 benull.
Examples
/**
* @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
}getLabelLayoutParameter
(copier: ClipboardGraphCopier, targetGraph: IGraph, sourceLabel: ILabel, newTargetOwner: ILabelOwner) : ILabelModelParameterGets an ILabelModelParameter for the given sourceLabel to be placed at the given newTargetOwner.
Remarks
Parameters
A map of options to pass to the method.
- copier - ClipboardGraphCopier
- The GraphCopier whose copyLabelLayoutParameter method can be used to copy the existing parameter.
- targetGraph - IGraph
- sourceLabel - ILabel
- The label in the sourceGraph to be copied.
- newTargetOwner - ILabelOwner
- The new owner in the targetGraph for the label.
Returns
- ↪ILabelModelParameter
- An ILabelModelParameter for the copied label.
getPortLocationParameter
(copier: ClipboardGraphCopier, targetGraph: IGraph, sourcePort: IPort, newTargetOwner: IPortOwner) : IPortLocationModelParameterGets an IPortLocationModelParameter for the given sourcePort to be placed at the given newTargetOwner.
Remarks
Parameters
A map of options to pass to the method.
- copier - ClipboardGraphCopier
- The GraphCopier whose copyPortLocationParameter method can be used to copy the existing parameter.
- targetGraph - IGraph
- sourcePort - IPort
- The port sourceGraph to be copied.
- newTargetOwner - IPortOwner
- The new owner in the targetGraph for the port.
Returns
- ↪IPortLocationModelParameter
- An IPortLocationModelParameter for the copied port.
Provides an IEdge where the given sourceBend can be added to.
Remarks
null if no target for the given sourceBend is found. In this case the bend will not be copied.Parameters
A map of options to pass to the method.
- context - ClipboardOperationContext
- The information which items to copy.
- sourceBend - IBend
- The bend to be duplicated from the source graph or copied from the clipboardGraph.
Returns
Provides an ILabelOwner where the given sourceLabel can be added to.
Remarks
null if no target for the given sourceLabel is found. In this case the label will not be copied.Parameters
A map of options to pass to the method.
- context - ClipboardOperationContext
- The information which items to copy.
- sourceLabel - ILabel
- The label to be duplicated from the source graph or copied from the clipboardGraph.
Returns
- ↪ILabelOwner?
- An ILabelOwner for the label to be added to or
nullif the label should not be copied.
Examples
/**
* @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
}Provides a parent group node for the given sourceNode considering the parentNodeDetection.
Remarks
null if the given node should be placed at the root or if the graph is not grouped.Parameters
A map of options to pass to the method.
- 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
Returns
- ↪INode?
- The new parent group of the node or
nullif the node should be placed at the root of the hierarchy or if the graph is not grouped.
See Also
Provides an IPort where the given sourceEdge can be added to.
Remarks
null if no target for the given sourceEdge is found. In this case, the edge will not be copied.Parameters
A map of options to pass to the method.
- 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.
Returns
Provides an IPortOwner where the given sourcePort can be added to.
Remarks
null if no target for the given sourcePort is found. In this case the port will not be copied.Parameters
A map of options to pass to the method.
- context - ClipboardOperationContext
- The information which items to copy.
- sourcePort - IPort
- The port to be duplicated from the source graph or copied from the clipboardGraph.
Returns
- ↪IPortOwner?
- An IPortOwner for the port to be added to or
nullif the port should not be copied.
Whether the given clipboardItem of the clipboardGraph was copied from a folding state of its owner.
Parameters
A map of options to pass to the method.
- clipboardItem - IModelItem
Returns
- ↪boolean
trueif the given item was copied from a folding state.
Whether the given clipboardItem is a "helper" item which should not be pasted.
Remarks
Parameters
A map of options to pass to the method.
- clipboardItem - IModelItem
- The item to test.
Returns
- ↪boolean
trueif the item is a "helper" item.
onCopy
(copyContext: ClipboardOperationContext, targetRootNode?: INode, itemCopiedCallback?: function(IModelItem, IModelItem):void)Called from copy and delegates to copy on the current toClipboardCopier instance.
Parameters
A map of options to pass to the method.
- 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.
Signature Details
function(original: IModelItem, copy: IModelItem)Callback delegate used by GraphCopier, ClipboardGraphCopier, and the like.Parameters
- original - IModelItem
- The element that has been copied.
- copy - IModelItem
- The copy of the original element.
onDuplicate
(duplicateContext: ClipboardOperationContext, itemDuplicatedCallback: function(IModelItem, IModelItem):void)Called from duplicate and delegates to copy on the current duplicateCopier instance.
Parameters
A map of options to pass to the method.
- 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.
Signature Details
function(original: IModelItem, copy: IModelItem)Callback delegate used by GraphCopier, ClipboardGraphCopier, and the like.Parameters
- original - IModelItem
- The element that has been copied.
- copy - IModelItem
- The copy of the original element.
Invoked for each item that has been copied into the clipboard graph in response to a copy operation.
Remarks
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.Parameters
A map of options to pass to the method.
- 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.
Remarks
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.Parameters
A map of options to pass to the method.
- 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.
Remarks
context for an IClipboardHelper. If one is found, onDuplicated is called.Parameters
A map of options to pass to the method.
- 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.
Remarks
Parameters
A map of options to pass to the method.
- 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.
onPaste
(context: ClipboardOperationContext, itemCopiedCallback: function(IModelItem, IModelItem):void, targetRootNode?: INode, targetOwners?: IEnumerable<IModelItem>, pasteLocation?: Point)Called during paste operation to call copy on the current fromClipboardCopier instance.
Parameters
A map of options to pass to the method.
- 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.
Signature Details
function(original: IModelItem, copy: IModelItem)Callback delegate used by GraphCopier, ClipboardGraphCopier, and the like.Parameters
- original - IModelItem
- The element that has been copied.
- copy - IModelItem
- The copy of the original element.
- 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.
paste
(targetGraph: IGraph, itemsToPaste?: IEnumerable<IModelItem>, itemPasted?: function(IModelItem, IModelItem):void, targetOwners?: IEnumerable<IModelItem>, pasteLocation?: Point, context?: IInputModeContext)Pastes the itemsToPaste from the clipboardGraph to the targetGraph.
Remarks
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
A map of options to pass to the method.
- 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
targetGraphis 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 thetargetGraph.Signature Details
function(original: IModelItem, copy: IModelItem)Callback delegate used by GraphCopier, ClipboardGraphCopier, and the like.Parameters
- original - IModelItem
- The element that has been copied.
- copy - IModelItem
- The copy of the original element.
- 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 thetargetGraphor 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
nullif 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.
Parameters
A map of options to pass to the method.
- graph - IGraph
- The graph to remove items from.
- itemsToRemove - IEnumerable<IModelItem>
- The items to remove.
See Also
Events
Occurs when the copy operation finished successfully.
Remarks
Occurs before the copy operation starts.
Remarks
Occurs when the cut operation finished successfully.
Remarks
Occurs before the cut operation starts.
Remarks
Occurs before the duplicate operation starts.
Remarks
Occurs when the onPaste operation finished successfully.
Remarks
Occurs before the onPaste operation starts.
Remarks
Constants
Gets a GraphClipboard instance that is used by default for clipboard so that it is shared between multiple GraphComponent instances.