Clipboard Support

Clipboard Support
Prev	Chapter 19. Infrastructure	Next

The top-level VisualGraph class VisualGraphView offers a number of methods that provide support for clipboard functionality (such as cut(), copy() and paste()). These methods operate on an internal clipboard that is shared amongst all instances of class VisualGraphView that exist in the current JVM instance. Note that these methods are part of the VisualGraphView interface only; hence it is not possible to use the clipboard programmatically on nested instances of VisualSubgraph. To use the clipboard, therefore, a top level view must exist. It is possible to perform a cut() or copy() operation on one instance of VisualGraphView and to perform one or more paste() operations on any other instance of VisualGraphView, including the instance that the cut() or copy() operation was initially performed on.

The three fundamental methods for clipboard support are the methods cut(), copy() and paste(). The cut() method will make independent copies of all currently selected items and place the copies on the clipboard. Afterwards, the currently selected items are deleted from the view. Since selections can extend to arbitrarily nested elements which are part of one or more VisualSubgraph objects, it is sufficient to provide these methods for the top-level view interface only. Because clipboard actions are controlled by the current selection, it is possible to perform any kind of clipboard operation on a VisualSubgraph instance without having such methods defined in that interface.

The items that are subject to clipboard operations may therefore be nested and are chosen for cut(), copy() or paste() by means of selecting them accordingly. In this manner all of the clipboard functionality can be accessed programmatically with the methods defined in the VisualGraphView interface. It is important to keep in mind that the set of objects that are affected by a clipboard operation is determined by the current selection.

Clipboard Methods

The following methods are provided by interface VisualGraphView for triggering clipboard operations and for retrieving information about the current clipboard status:

void clearClipboard()
Clears the clipboard.
void copy()
Copies the selection into the internal clipboard.
void cut()
Cuts the selection into the internal clipboard.
int getClipboardSize()
Returns the size of the clipboard.
int getPasteOrientation()
Returns the current mode for pasting orientation. This mode determines the order in which objects are pasted if multiple objects are pasted at once.
void setPasteOrientation(int)
Sets the current mode for pasting orientation. This mode determines the order in which objects are pasted if multiple objects are pasted at once. Three different modi are defined:
1. PASTE_ORIENTATION_LEFT_TO_RIGHT Preserve horizontal order
2. PASTE_ORIENTATION_TOP_TO_BOTTOM Preserve vertical order
3. PASTE_ORIENTATION_NONE Strictly coordinate based
void setUndoRedoLimit(int)
Sets the maximum amount of steps that are available for undo/redo
void paste()
Pastes the contents of the internal clipboard into the VisualGraphView.
void paste(Coordinate)
Pastes the contents of the internal clipboard into the VisualGraphView at the specified mouse position, which is given in platform pixel coordinates and automatically converted to view-coordinates internally. If the coordinates are null then a regular paste is made.
void paste(ViewBuilderFilter)
Same as paste() except the pasted objects can be modified through the given ViewBuilderFilter. The ViewBuilderFilter is only taken into account when the system clipboard is used for the clipboard operations.
void paste(Coordinate, ViewBuilderFilter)
Same as paste(Coordinate) except the pasted objects can be modified through the given ViewBuilderFilter. The ViewBuilderFilter is only taken into account when the system clipboard is used for the clipboard operations.

Cut And Copy

For both cut() and copy() operations, the currently selected items are copied onto the clipboard, overriding its previous content. The cut() method can be thought of as a copy() operation that is succeeded by a deletion of the selected items. Since it is possible to select both parent containers and their children simultaneously, an internal logic will skip clipboard processing for all selected elements whose parents are selected as well. This is necessary to prevent unexpected results.

Paste

Upon invocation of the paste() method, the clipboard contents are copied again and the resulting copies are inserted into the VisualGraphView or nested VisualSubgraph objects. This additional copy is required since it is possible to paste the same clipboard contents multiple times.

Not including the special paste() methods discussed in the next section, the following events happen when a normal paste() method is invoked. Please note that there are two paste() methods, one accepting no parameters and one of which takes an argument of type Coordinate that specifies a geometric reference point for the paste() operation.

If reference coordinates are given (typically mouse coordinates), then the following happens: (This means the version of paste that takes a Coordinate instance as an argument was invoked.)

If the mouse is positioned within the region of a VisualSubGraph, then the clipboard contents are pasted at the mouse position as children of the particular VisualSubGraph.
If the mouse is not positioned within the region of a VisualSubGraph, then the clipboard contents are pasted at the mouse position in the top-level VisualGraphView.

If no reference coordinates are given, then the following happens: (This means the no-argument version of paste() was invoked.)

If exactly one element is selected in the entire hierarchy of the destination VisualGraphView and this element is not of type VisualSubGraph, then the bounding box of the clipboard' contents is positioned at the position of the selected element plus an additional offset. If all inserted items are invisible, the visible region of the VisualGraphView is translated so that the center of the bounding box of the clipboards contents is positioned at the center of the visible region.
If exactly one element is selected in the entire hierarchy of the destination VisualGraphView and this element is of type VisualSubGraph, then a region R is determined by intersecting the visible region and the boundary of the selected VisualSubGraph. If the region R is not empty, then the bounding box of the clipboards contents is positioned at the center of R. If R is the empty region, then the contents of the clipboard are positioned so that the bounding box is centered at the selected VisualSubGraph. Afterwards, the center of the visible region is moved so that it is positioned on top of the bounding box of the clipboards contents.
If multiple items are selected or no item is selected at all, the clipboards contents are inserted into the top-level VisualGraphView instance at the center of the visible region.

Special Paste Methods

In certain scenarios it might be beneficial for the user to invoke more specific operations than just a simple paste(). The following methods are provided that support more advanced features.

void pasteBefore(VisualNode)
This method pastes the contents of the clipboard before the specified VisualNode argument. VisualEdge instances that may be on the clipboard are not processed by this special paste operation.
void pasteBehind(VisualNode)
This method pastes the contents of the clipboard behind the specified VisualNode argument. VisualEdge instances that may be on the clipboard are not processed by this special paste operation.
void pasteStart()
This method pastes the contents of the clipboard at the beginning of the the VisualSubgraph, which means that the contents of the clipboard are inserted on the first edge of the container. This first edge is obtained by scanning the container for an edge whose source node has an in degree of zero. VisualEdge instances that may be on the clipboard are not processed by this special paste operation, however.
void pasteStop()
This method pastes the contents of the clipboard at the end of the VisualSubgraph, which means that the contents of the clipboard are inserted on the last edge of the container. This last edge is obtained by scanning the container for an edge whose target node has an out degree of zero. VisualEdge instances that may be on the clipboard are not processed by this special paste operation, however.

Auxiliary Methods

For enabling and disabling buttons and menu items in a GUI, it is necessary to programatically determine if anything is currently available from the clipboard. The getClipboardSize method provides exactly this functionality. If the returned size is larger than zero, you should enable the paste button and/or menu item.

The methods setSelectPastedElements and isSelectPastedElements are used for setting and getting that property of the VisualGraphView which determines whether pasted items are to be selected after the operation or not.

The methods getPasteOrientation and setPasteOrientation are used for getting and setting the view orientation. Setting it specifies a sorting order when multiple nodes are inserted before or behind a reference node by means of the pasteBefore and pasteBehind methods. Also the methods pasteStart and pasteStop are dependent on this sorting order. If only the plain paste methods are used, it is not required to set this data.