Proposal 

VOTE

Cut, Copy, Paste

Summary

The Eclipse workbench defines global actions for Cut, Copy, and Paste. The goal of this proposal is for all relevant platform workbench parts to provide semantically consistent handlers for these actions. Specifically, the handlers will provide a clipboard-based implementation of cut, copy, and paste. The main benefits of this proposal are:

1. clipboard-based cut, copy, paste for moving and copying resources in the navigator

2. copying textual representations of the selected item in most platform workbench parts (the equivalent of "Copy as text")

3. consistently implementing cut/copy/paste to be the "keyboard equivalent" of drag and drop

By Karice McIntyre and Randy Giffen, OTI
Last Modified: December 14, 2001

---

Proposed Changes

1. Navigator View

• Implement Cut, Copy, and Paste as clipboard related actions.  These actions will be added to the context menu (Copy is already present) and handlers will be supplied for the global actions. These actions will support resource transfers (same workbench), file transfers (different workbench or other app - involves OS file or folder with no meta data), and text transfers (textual description of the selected item). Note that cut/paste will only work within the same workbench. Cut/paste to or from a different workbench or another app will be the same as a copy/paste (the original will not be removed).
• Remove Move from the context menu (the dialog based MoveResourceAction and CopyResourceAction will not be deleted since they are API but they will no longer be used by the workbench). The ability to changing the location of a project will be provided on a property page.

2. Bookmarks View

• Implement a clipboard related Copy. This action will be added to the context menu and a handler will be supplied for the global action.
• This copy action will only support a text transfer of a description of the bookmark to the clipboard (name, filename, line number)
• Drag and Drop will be implemented to do the same (drop a textual description of the of the bookmark)

3. Properties View

• Implement a clipboard related Copy. This action will be added to the context menu and a handler will be supplied for the global action.
• This copy action will only support a text transfer of a description of the bookmark to the clipboard (name: value)

• Drag and Drop will be implemented to do the same (drop the name and value of the property)
• Changes will actually be made to the default PropertySheetPage not the view itself

4. Outline View

• No issues for UI team since we do not contribute an outline page; however, others that implement Outline pages should be encouraged to implement drag and drop and cut/copy/paste (including any new Transfer types that are required).

5. Tasks View

• Implement Cut, Copy, and Paste as clipboard related actions.  These actions will be added to the context menu (Copy is already present) and handlers will be supplied for the global actions.

• Copy will be enabled for tasks and problems and will copy a textual description to the clipboard (as a vertical list of name: value pairs)
• Cut and Copy will be enabled for tasks to put a TaskTransfer on the clipboard.
• Paste will be enabled if there is text on the clipboard. It will be checked for specific name value pairs. If none are found the text will simply be used as the description.
• Paste will be enabled when there is a TaskTransfer on the clipboard (the pasted task will not have a file reference).
• Paste of a task to a file will be enabled in the Navigator.

Changes dependant upon work from other teams

· [CORE – P2]

• In order to transfer files and folders between workbenches as resources (ex. transfer a project rather than just its contents) we need a way of transferring appropriate metadata. In the case of projects, Core is currently considering ways of supporting transfer between workbenches (see the Import/Export RFC on the Core team’s development web page).

[SWT – P1/P2]

• In order for "object" cut/paste to work between workbenches and between a workbench and another app, we need API from SWT for clipboard copy vs. clipboard move (cut).  Consider the case of moving a file form a workbench to MS file explorer.
• we have no way of indicating to MS File Explorer that it should perform a "move paste" rather than a copy paste.
• we have no idea when a move paste occurs and thus cannot "refresh from local" (note that this is more than just updating the display, the workspace must be updated).
• See Bug 5645 for more details on this problem.
• A similar problem occurs when performing a file cut outside of eclipse and then pasting into eclipse. We don't know that it is a move paste
• In addition the clipboard must be cleared after a move paste.
• If/when SWT provides this API we will be able to get rid of the WorkbenchClipboard class.

Discussion

Current issues (this proposal is not intended to address all these issues)

1. Not consistently implementing Cut, Copy, and Paste where drag and drop implemented (e.g. Navigator, Tasks).
2. Requiring user interaction in copy implementation; using dialogs to copy resources (again, see Navigator)
3. Need to be able to Cut, Copy, Paste all resources (projects, files, folders)
1. within a workspace
2. between workspaces
3. between the workspace and other applications
4. Need make sure we have transfer types for all known copy-able objects in the Resource perspective; this will be useful for those who want to use the clipboard to implement cut, copy, paste.
5. Need to implement re-usable cut, copy, paste action handlers for all known objects in all views of the Resource perspective.
6. Need to provide visual indication of cut.
7. Need to be able to cancel Cut or Copy using Esc key. Need to check with SWT if this is currently possible (if not, enter a PR).
8. F2 (Rename) is implemented in the Navigator, but not in the Packages view. Getting ISVs to consistently implement the same keyboard controls seems like a difficult thing to do.

Background

The most interesting case (for the UI team) of the Cut, Copy, and Paste implementation is in the Navigator. The best way to utilize Cut, Copy, and Paste and be consistent with drag and drop is to use the system clipboard to transfer resources within a workspace, between workspaces, and between a workspace and another application.

The clipboard model is fairly well understood by most users; it is frequently used to support text editing. Its use can be extended however, to support the idea of putting objects such as files on a clipboard (ex.MS File Explorer). Moving and copying files for example, can be achieved without requiring the use of a dedicated dialog that typically is used to indicate the destination of the operation. However, not all ISVs who implement Cut, Copy, Paste may want to or will be able to use a conceptual clipboard to perform these actions, so we will not impose this restriction upon everyone implementing these global actions.

The underlying clipboard support in SWT uses the concept of a Transfer (org.eclipse.swt.dnd.Transfer). A Transfer is essentially code that knows how to move something on and off the clipboard as bytes (note it may only put a reference on the clipboard such as a filename). Transfers have a stateless singleton instance accessed via a static getInstance method. SWT provides the following concrete types of transfers:

1. TextTransfer - used to transfer plain text
2. RTFTransfer - used to transfer text with rtf format
3. FileTransfer - used to transfer files

The workbench defines the following transfer types:

1. MarkerTansfer - used to transfer a marker (serializes resource path and marker id)
2. PluginTransfer - used to support the drop action extension (not sure why this is used – Navigator uses this transfer type in DND, along with FileTransfer and ResourceTransfer)
3. ResourceTransfer -used to transfer an IResource (includes path and type information; does not include bookmark or task markers, or metadata for projects – not yet anyway)

Of course if a plug-in wants to transfer an object that is not supported by one of the currently existing Transfer classes, a custom transfer can be implemented (see org.eclipse.ui.part.ResourceTransfer as an example). When one implements a transfer type, they must be sure not to lose any information pertaining to the object being transferred.It does not appear that additional transfer types are required to complete the transfer story for objects that exist in the Resource perspective.

An important point to note is that more than one type of transfer can be placed on the clipboard at a time. For example, performing a copy in the Navigator should cause a ResourceTransfer, a FileTransfer, and a TextTransfer to be placed on the clipboard (see Proposed Changes item 2 below for details on each of these transfer types). The enablement of a paste action, and the type of paste that is actually performed are determined by the target of the paste based on:

1. its state (ex. current selection)

2. the contents of the clipboard (the type of transfers available).

A frequently requested feature is the ability to copy a "selection as text" so that it can be used in a text editor. The use of a simple TextTransfer makes this easy. This should be performed by the Copy action. There is no need to define an additional "Copy Names" action as appears in the Packages view. In the case of a part using a standard JFace StructuredViewer, the copy action would use the labels of the selected items as the text to put on the clipboard but this could be customized as required.

Semantics of Cut/Copy/Paste in the Navigator

• Each time a Cut or Copy is performed, the contents of the Clipboard just prior to the Cut or Copy being performed are replaced with the currently selected contents. There is no concept of a stacked clipboard, where the contents of n previous Cut/Copy actions can be retrieved as the result of a Paste action.
• Selection must be compatible in order for Cut/Copy to be enabled. By compatible we mean that projects and files or folders cannot be selected for one Cut or Copy operation. This is because projects have additional data associated with them, so they must be treated differently then files and folders. There are 2 mutually exclusive, valid types of selections:
• Files and/or folders
• Projects
• Cut + Paste: Places references (path and resource type) to resources on the clipboard (using the 3 transfer types specified above). When Paste is invoked, the resources on the clipboard are moved from the source to the currently selected folder (project or folder). Pending successful move of the resource(s), the source resource(s) are deleted, and clipboard is cleared of its contents (actually, one transfer (a TextTransfer) of the name(s) of the source resource(s) is placed on the clipboard) so as to prevent multiple pasting of the source resources (this cannot be done since the source resources are removed as a result of a Cut + Paste sequence). Note: If resource names conflict in the destination, a dialog will ask the user if they would like to overwrite the resource. In the case where a dialog has to be opened upon a Paste, we could have a workbench preference that, when enabled, will automatically overwrite resources in order to prevent repeatedly annoying the user with this dialog.
• Copy + Paste: Places references (path and resource type) to resources on the clipboard (using the 3 transfer types specified above). When Paste is invoked, a copy of the selected resource(s) is created in the location of the currently selected folder (project or folder). Automatic rename of the copy (e.g. for file.txt new name is Copy of file.txt) occurs if resource names conflict.
• Copying of projects:  First, the user will have to select the project (no other resources can be selected), select Copy from the menu, deselect everything in the Navigator, then select Paste from the menu. At this point, to complete the project copy: 1) If the project to be copied is in the default location, we simply create a copy of the project in the default location. 2) If the project to be copied is in a custom location we will bring up a dialog requesting the location for the copy. Copy of projects between Eclipse and other applications will be treated as FileTransfers (since projects are only recognized by Eclipse). As for the case of copy between Eclipse workspaces, we will want to maintain the metadata. However, without additional API from Core, we will only be able to do a FileTransfer in this case. If Core provides the proper API for project persistence then we will be able to facilitate copy of projects (as projects) between Eclipse workspaces.
• A Note on Paste Special: It was suggested that this menu operation be added since clipboard-based cut/copy/paste often deal with multiple transfer types. We see no need for this in all the UI views/editors since each view should be able to determine which single transfer type to use when a paste occurs. The concept of the target part always being able to determine which transfer type to paste is an important one for ISVs to remember when implementing the Paste global action. The only exception we can see (where a Paste Special menu item is required) would be in the case of an ISV implementing a special editor that deals with more than just textual formats (e.g. one could also paste gifs, graphs, spreadsheets, etc). And in this case, Paste Special could simply be added to the context menu of the editor/view and would never be considered a global action (no accelerator). Each view must determine what transfer types make sense to put on the clipboard and rely on the target part to pick up the one correct transfer type off the clipboard when it does a Paste.
• The Move operation for both projects and files/folders will be taken out of the context menu. A file/folder move can be performed using cut and paste. The semantics of the Move action for a project will be relocated to the Property page of the project and will appear as Change Location (since that is all the project Move really does). The MoveResource/ProjectAction and CopyResource/ProjectAction classes would remain since they are API but we would no longer use them ourselves in the workbench.

Vote Termination Date

The period for voting ends one week from the date the request for vote is submitted to the mailing list.