6.1 Actions

Each action has two flags called script-triggered and script-may-access-clipboard.

The script-triggered flag is set if the action runs because of a script, for example a document.execCommand() call. Future scripting APIs that interact with the clipboard should also use these actions, and the script-triggered flag must be set accordingly.

The script-may-access-clipboard flag is set as follows:

If action is copy or cut and the script thread is allowed to modify the clipboard

Set the action's script-may-access-clipboard flag

If action is paste and the script thread is allowed to read from clipboard

set the action's script-may-access-clipboard flag.

document.addEventListener('copy', function(e){
    e.clipboardData.setData('text/plain', 'Hello, world!');
    e.clipboardData.setData('text/html', '<b>Hello, world!</b>');
    e.preventDefault(); // We want our data, not data from any selection, to be written to the clipboard
});

document.addEventListener('paste', function(e){
    if(e.clipboardData.types.indexOf('text/html') > -1){
        processDataFromClipboard(e.clipboardData.getData('text/html'));
        e.preventDefault(); // We are already handling the data from the clipboard, we do not want it inserted into the document
    }
});

6.2 Processing model for event dispatch

To fire a clipboard event of type e,

1. Let clear-was-called be false
2. Let types-to-clear be an empty list
3. Let clipboard-entry be the sequence number of the current clipboard content, or null if the OS clipboard does not support sequence numbers
4. Let trusted be true if the event is generated by the user agent, false otherwise
5. Set target as follows:

   If the context is editable:

   Let target be the element that contains the start of the selection in document order, or the body element if there is no selection or cursor.

   Else, if the context is not editable

   Let target be the focused node, or the body element if no node has focus.

6. If e is paste

   Set the associated DataTransfer object's drag data store mode flag to read-only

   If trusted is true, or the implementation is configured to give script-generated events read access to the OS clipboard

   For each part on the OS clipboard, carry out these steps:

   If the current clipboard part contains plain text:

   1. Ensure the text is in the encoding the scripting engine uses internally
   2. Add one entry for the text to the DataTransferItemList with drag data item kind set to string and drag data item type string set to text/plain

   If the current clipboard part represents file references:

   1. Determine MIME type of referenced files
   2. Add one entry per file reference to the DataTransferItemList with drag data item kind set to file and drag data item type string set to the corresponding MIME type, or application/octet-stream if the file's type is unknown.

   If the current clipboard part contains HTML- or XHTML-formatted text, according to the operating system's convention for describing such clipboard formats

   If the implementation supports pasting HTML, the implementation must process the markup according to the following steps:

   1. Add one entry to the DataTransferItemList with drag data item kind set to Plain Unicode string, drag data item type string set to text/html or application/xhtml+xml accordingly. Let mainPartIndex be the index of this entry in the DataTransferItemList.
   2. Extract the markup from the clipboard and use the relevant parser to construct a DOM tree
   3. If the markup's source URL is known, resolve all relative URLs in HREF and SRC attributes using the source URL as base URL, and set the respective attributes to the resolved absolute URL
   4. If the markup's origin is from a local application, check whether there are references to local files and/or other parts of the OS clipboard's contents. If such references are found, references to sub-parts must be replaced by content-id references using the cid: URL scheme [RFC2392]. To do so, process each attribute referencing a local file or clipboard part according to the following steps:
      Issue 1

      Are these steps necessary? Do we know about native (platform) clipboard implementations that support multiple parts with internal references?

      Issue 2

      This feature is at risk because it's unclear whether it is required, and because it's hard to test in a cross-platform way.

      1. Let itemNumber be the number of items on the DataTransferItemList

      2. Choose the appropriate steps from this list:

         If the DataTransferItemList of the current DataTransfer object already contains an entry for the referenced file or clipboard part

         set itemNumber to the index of the existing entry

         Otherwise

         1. Add a new entry to the DataTransferItemList with index set to itemNumber, drag data item kind set to "file", and drag data item type string set to the MIME type of the file or clipboard part if known, or application/octet-stream if the file's type is unknown.
         2. Let the new entry's internal file name be the file name part of the HTML attribute contents
         3. Let the new entry's last modified date be the timestamp of the referenced file or 0 if the entry references a clipboard part

      3. Update the DOM attribute that referenced the local file or clipboard part to contain the string 'cid:' followed by itemNumber.
   5. Serialize the processed DOM and update the DataTransferItemList entry referenced by mainPartIndex with the resulting HTML code

   If the current clipboard part contains data in another supported binary or text-based format:

   1. Determine the MIME type of the data
   2. Add one entry to the DataTransferItemList with drag data item kind set to file, drag data item type string set to the corresponding MIME type

   Update the files property to match entries in the DataTransferItemList.

   Update the types property to match entries in the DataTransferItemList.

   If e is copy or cut

   Set the associated DataTransfer object's drag data store mode flag to read/write

7. Dispatch an event named e which bubbles and is cancelable and which uses the ClipboardEvent interface, with isTrusted set to trusted, at target.

   Implementation requirements for access to data during event dispatch are defined in [HTMLLS]. Some additional clipboard event-specific processing rules are given below:

   Issue 3

   Why here? Why not in the HTML spec?

   If a script calls clearData() or items.clear() and the DataTransfer object's drag data store mode flag is read/write

   set the clear-was-called flag to true. If an argument is given, add the argument to the types-to-clear list.

   If a script calls setData() or modifies items and the clear-was-called flag is true

   If the types-to-clear list is empty

   set the clear-was-called flag to false

   else, if setData()'s type argument or the new item's drag data item type string is found in the types-to-clear list

   remove it from the list. If the list is now empty, set the clear-was-called flag to false

   If a script calls getData() or accesses items in the DataTransferItemList and clipboard-entry is set

   check that the clipboard data's sequence number matches clipboard-entry. If the clipboard no longer contains the same entry, set the DataTransferItemList object's drag data store mode to the disabled mode

   Warning: Long-running clipboard reading threads

   A malicious script listening to a paste event may set up a never-ending loop in order to read what the user places on the clipboard in the future. On platforms where a clipboard sequence number is not available, other limitations should be implemented.

7.1 Dictionary ClipboardEventInit Members

clipboardData of type DataTransfer, nullable, defaulting to null

A DataTransfer object to hold data and meta data related to the event

7.2 Attributes

clipboardData of type DataTransfer, readonly , nullable

The clipboardData attribute is an instance of the DataTransfer interface which lets a script read and manipulate values on the system clipboard during user-initiated copy, cut and paste operations. The associated drag data store is a live but filtered view of the system clipboard, exposing data types the implementation knows the script can safely access. For synthetic events, the drag data store contains the data added by the script that created the event.

The clipboardData object's items and files properties enable processing of multi-part or non-textual data from the clipboard.

9.1 Event handlers that are allowed to modify the clipboard

Event handlers may write to the clipboard if any of the following is true:

• The action which triggers the event is invoked from the user-agent's own user interface, e.g. from a "Copy" menu entry or shortcut key.
• The action which triggers the event is invoked from a scripting thread which is allowed to show a popup.

The implementation may allow other trusted event types to modify the clipboard if the implementation authors believe that those event types are likely to express user intention. The implementation may also support configuration that trusts specific sites or apps to modify the clipboard regardless of the origin of the scripting thread.

Synthetic cut and copy events must not modify data on the system clipboard.

9.2 Event handlers that are allowed to read from clipboard

Event handlers may read data from the system clipboard if either of the following is true

• The action that triggers the event is invoked from the user-agent's own user interface, e.g. a "Paste" menu entry or shortcut key.
• The script that triggers the action is running on a site which through an implementation-dependant mechanism is given permission to read data from the clipboard.
• The action that triggers the event is triggered in an app with permissions to read the clipboard.

Synthetic paste events must not give a script access to data on the real system clipboard.

9.3 Integration with rich text editing APIs

If an implementation supports ways to execute clipboard commands through scripting, for example by calling the document.execCommand() method with the commands "cut", "copy" and "paste", the implementation must trigger the corresponding action, which again will dispatch the associated clipboard event.

These are the steps to follow when triggering copy, cut or paste actions through a scripting API:

1. Execute the corresponding action synchronously.
2. Use the action's return value as the return value for the API call.

9.4 Interaction with other events

If the clipboard operation is triggered by keyboard input, the implementation must fire the corresponding event as the default action of the keydown event that initiates the clipboard operation. For example, if the user presses Ctrl-C to copy, dispatching a copy event must be the default action of the C key's keydown event. The event is asynchronous but must be dispatched before keyup events for the relevant keys.

The cut and paste actions may cause the implementation to dispatch other supported events, such as textInput, input, change, validation events, DOMCharacterDataModified and DOMNodeRemoved / DOMNodeInserted. Any such events are queued up to fire after processing of the cut/paste event is finished.

The implementation must not dispatch other input-related events like textInput, input, change, and validation events in response to the copy operation.

9.5 Event listeners that modify selection or focus

If the event listener modifies the selection or focus, the clipboard action must be completed on the modified selection.

10.2 General security policies

The implementation must not download referenced online resources, or expose their contents in the files list or DataTransferItemList.

If the data on the clipboard is not from a local application, the implementation must not give access to any referenced local files. For example, if the data contains <img src="file://localhost/example.jpg"> but the data's origin is an online resource, the implementation must not add an entry for example.jpg to the clipboardData.items list.

11.1 Privacy concerns

Untrusted scripts should not get uncontrolled access to a user's clipboard data. This specification assumes that granting access to the current clipboard data when a user explicitly initiates a paste operation from the user agent's trusted chrome is acceptable. However, implementors must proceed carefully, and as a minimum implement the precautions below:

• Objects implementing the DataTransfer interface to return clipboard data must not be available outside the ClipboardEvent event handler.
• If a script stores a reference to an object implementing the DataTransfer interface to use from outside the ClipboardEvent event handler, all methods must be no-ops when called outside the expected context.
• Implementations must not let scripts create synthetic clipboard events to get access to real clipboard data except if configured to do so.
• Implementations should not let scripts call document.execCommand('paste') unless the user has explicitly allowed it.

Implementations may choose to further limit the functionality provided by the DataTransfer interface. For example, an implementation may allow the user to disable this API, or configure which web sites should be granted access to it.

11.2 Nuisance considerations

Scripts may use the DataTransfer API to annoy and confuse users by altering the data on the system clipboard from copy and cut events. This specification does not attempt to prevent such nuisances, though implementations may add additional restrictions.

Implementations must handle scripts that try to place excessive amounts of data on the clipboard gracefully.