Copyright © 2006 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document describes apis for clipboard operations such as copy/cut and paste, or drag and drop in web applications.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is the First Public Working Draft prepared of Clipboard Operations from the Web API group, part of the Rich Web Client Activity. In large part it describes the functionalities as implemented in Internet Explorer, and has not been sufficiently tested in other browsers yet. The intention of this document is where possible to specify what actually works in current browsers, or is a simple target for them to improve interoperability, rather than adding new features. A second version of this specification may be produced which extends that functionality in various ways which have proven useful.
This document is published to solicit comments from interested parties. All comments are welcome and may be sent to public-webapi@w3.org. All messages received at this address are viewable in a public archive. After reviewing comments and further feedback, the Working Group intends to publish a new Working Draft of this document at the beginning of 2007.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This section is informative
This specification defines the common clipboard operations of cutting, copying and pasting, in such a way that they are exposed to Web Applications and can be adapted to provide advanced functionalities. Its goal is to provide for compatibility where possible with existing implmentations.
Recognising that "drag and drop" operations are essentially a common user interface extension of cut or copy, move, and paste, it also defines how the events currently implemented for "drag and drop" operations relate to the less device-specific approach of general clipboard operations.
A common interface design in the traditional WIMP (Windows, Icons, Mouse Pointer) interface is to move the pointer to an icon or to a highlighted selection, press the mouse key and drag a copy of the icon to the target where s/he wants to drop the object, then release the mouse key. There are, of course, many alternatives. In a graphic user interface without a mouse a user might select an object for dragging through a context menu, navigate to another object through standard navigation, and then select to drop the held object.
This section is informative
There are many use cases for being able to change the default clipboard operations (cut/copy/paste, and the related drag-and-drop). We have colected a few samples to demonstrate possible uses, although these may not all be supoprted by this specification.
Allowing for interfaces that use a thumbnail image to refer to a block of content, which can then be dragged to insert the block of content represented in another part of a web page. The common Drag-and-drop pardigm must be implementable in such a way that it is accessible to users who are unable to use a mouse (such as those on a phone where there is no mouse) and must rely on keyboard or other interfaces.
With content such as mathematics, simply copying rendered text and pasting it into another application generally leads to most of the semantics being lost. The following example, when copied, typically adds two lines containing the text "2 x = 7" to the clipboard. But in the MathML source of this text, and for any human reader familiar with normal western conventions for mathematical layout, this leads to incorrect copying. The first line would often be better, if copied as plain text, as "2^x = 7", or if the XML source could be placed in the clipboard with the appropriate transformation occurring when pasting.
Example 1: Mathematical information
Similarly, when copying text which contains hyperlinks or other structure, it is often useful to be able to reformat the content to preserve important information.
And in order to make web applications which allow the manipulation of rich text, or of graphic content such as SVG, it is useful to provide a mechanism that allows for copying more than just the rendered content.
The terms must, should, may, must not, should not, are used in this document in accordance with [RFC2119]. A conformant implementation of this specification meets all requirements identified by the use of these terms.
Enabling authors to change what is copied by a user, or to make an automated copy of something that was never selected and allowing unrestricted calls to paste information can raise various security concerns. If these operations are allowed to transfer data across documents from different sources then there are even greater risks imaginable. On the other hand there are valid reasons for allowing this in the right circumstances.
An example scenario of a problem is where a user selects a link and copies it, but a different link is copied to the clipboard. The effect of this can range from an unexpected result on pasting to an attempted "phishing" attack.
Authors be aware that User Agents will typically restrict what is possible to content they consider "safe", or trusted by the user. For example, it may not be possible to launch some of the operations from script, such as requiring an actual (not simulated or script-generated) user action to paste or drop.
Implementors should carefully consider the security implications of implementing this specification, and provide appropriate protection for users against malicious use, such as restricting access to the functionalities according to how trusted the source of a function call is, or informing the user when something other than rendered content is copied to the clipboard.
This specification will attempt to highlight all areas where possible security issues arise, but the final responsibility for making decisions about what to allow rests with user agent implementors. Note that this is not done in the current draft.
@@Issue: identify what the restrictions generally used are, as some guidance on interoperability
This section is informative
This specification does not define all the user interface modes that can be used to select content, but this section attempts to provide a survey of some common ones. Authors and implementors should be aware that the precise User Interface details will vary according to the use case and platform, with different methods applying for
Many of these user interfaces have developed common interaction paradigms (in the case of the common mouse/keyboard/window interface there are several which are expected to interact seamlessly) for copy and paste at least. Other may be less common and have no emerging convention, while other interfaces may be developed. In each case, the events and results described below should be mapped by the platform to particular user interaction.
Another method that can be used is to provide a copy/paste and copy special/paste special set of operations, to distinguish between copying simple or structured content to the clipboard.
These are well-understood operations for users. There are events fired during selection, cut/copy and paste in some systems already which can be captured, cancelled, and whose effects can be overwritten. In particular, what is copied to the clipboard may be the rendered content that is selected, or may be some other modified version. (See security implications and annoying the user, and the setData method's ).
Each copy-paste operation has 4 distinct phases:
setData method to copy the
source node to the
clipboardData object. It may also
copy the data to a dataTransfer object.
@@Issue: This makes drag and drop more
flexible, e.g. for accessibility. What is the
downside?current
target.paste event on the current target. The default effect is that
where applicable (for example in editable text such as an
input) the content which is held in the clipboard is
inserted at the target.The source content may be either structured or unstructured. Unstructured content is of a single simple type such as text or an image bitmap. Structured content is composed either of mixed content types, or a combination of several items of the same content type. @@Issue: Actually, this isn't how it works in IE. We should think about this bit more...
Selection may be accomplished by a number of means - see User Interface Issues above.
copy places a copy of the object selected
into a clipboard. The current selection must not be
affected.
cut should delete the object
selected, and place it into the clipboard. In the case of
read-only content (such as a document which is not editable
by the user) the content should not be removed, but
a copy should be placed in the keyboard as for a
copy operation. [@@Issue: nice idea, does
it reflect current reality? Opera/Safari on Mac don't do
that...].
paste triggers an event on the current target
(usually the current selection). @@Issue:
For drag and drop compatibility should it trigger
drop and paste, or vice
versa?
Drag and drop is essentially a special case of a cut or copy, moving to select some new target, and then a paste operation, which is implemented for mouse-based devices. The main differences in drag-and-drop are that the object being dragged is can fire a dragover event on various possible targets before being dropped onto them, and that the object selected may be copied to a temporary drag-specific clipboard. Compare the following phases with those in copy and paste:
dragstart event. It
must copy the source node into
dataTransfer. It should set the
effectAllowed property to determine whether a
drag operation copies, moves, links, etc the source node. See
[MDT] for further documentation of how
this works in Internet Explorer. (@@Issue: Can it just use the copy interface? Where
does dataTransfer come from? Can you start a drag using the
existing copy buffer?)dragenter, dragover, and
dragleave. This may be the same
mechanism as used for selection, although typical
implementations provide a seperate mechanism. These events
should not fired on the source, so until there
is a dragenter event fired, a drop
event should not be fired. Any action which would
have caused a drop to be fired before any
dragenter event has fired should cancel
the drag.drop
event is fired at the target. In order to protect the user
from pasting unexpected content, user agents may not
allow this event to be fired when not triggered by direct
user interaction. In a drag operation this normally destroys
the dataTransfer object. @@Issue: what if
the operation is not successful?However it is implemented in an interface, drag and drop
operations must have a starting point (e.g. where the mouse was
clicked, or the when a selection or element is
selected for the drag), may have any number of intermediate
steps (elements that the mouse moves over during a drag, or
elements that the user picks as possible drop points as she
cycles through possibilities), and must either have an end
point (the element above which the mouse button was released,
or the element that was finally selected), or be canceled. The
end point must be the last element selected as a possible drop
point before the drop occurs. If there is no
dragenter event fired after a
dragstart, then the drop event
should be cancelled, but may be fired on the
source node.
Then, regardless of whether the event was canceled or not,
drag feedback (e.g. the mouse cursor or other clear indication
to the user) should be updated to match the kind of
operation indicated by the event's dataTransfer object's dropEffect attribute, as
follows: @@Issue: More info about setting
the dropEffect would be useful
dropEffect |
Drag operation |
|---|---|
none |
No operation allowed. |
copy |
Data will be copied. |
link |
Data will be linked. |
move |
Data will be moved. |
The following events are involved in the drag-and-drop
model. They all use the DragEvent interface.
(these fire
on-* events in IE 5+ @@Issue: and
IE7?
| Event Name | Target | Bubbles/Cancelable? (yes/yes unless noted) | dataTransfer |
dropEffect |
Default Action |
|---|---|---|---|---|---|
dragstart |
Source node | The setData method places the source node in either clipboardData or dataTransfer. @@Issue: if it sets clipboardData is should also set dataTransfer, no? | none |
Initiate the drag-and-drop operation | |
drag |
Source node | âÄî | none |
Continue the drag-and-drop operation | |
dragenter |
Immediate user
selection or the
body element |
âÄî | Based on effectAllowed value |
Change the current target
element from the immediate user selection to the
element this event is fired on. @@Issue: If it is fired on the body, this text
isn't right... |
|
dragleave |
Previous
target element |
Not cancelable | âÄî | none |
None |
dragover |
Current target
element |
âÄî | Based on effectAllowed value |
Reset dropEffect based on
effectAllowed value |
|
drop |
Current target
element |
getData() returns data set in
dragstart event |
Current drag operation | Varies | |
dragend |
Source node | âÄî | none |
Varies |
Internet Explorer provides 3 methods for the
clipboardData and dataTransfer
objects:
setData()getData()clearData()Don't extend this yet, we haven't even specified it. Thanks!!!
paste or drop
event will be fired.This section is informative
The editors would like to acknowledge their intellectual debt to the documentation of Data Transfer functionalities from Microsoft [MDT]. The draft specification of them from the WHAT Working Group published as part of their draft "Web Applications 1.0" [WHAT-WA] which essentially repeats the drag-and-drop-specific parts of that were heavily used to prepare the initial drafts of this specification. We are also grateful for the draft "safe copy and paste" [SCP] from Paul Libbrecht.
We would like to acknowledge the contributions made by the following:
Shawn Carnell, Daniel Dardailler, Al Gilman, Lachlan Hunt, Aaron Leventhal, Jim Ley, Paul Libbrecht, "Martijn", Dave Poehlman, "ROBO Design", Janina Sajka, Rich Schwerdtfeger, Jonas Sicking, Maciej Stachowiak, Mihai Sucan, Tom Wlodkowski