Using the Pasteboard From JavaScript
Safari, Dashboard, and WebKit-based applications include support to let you handle cut, copy, and paste operations of your HTML content.
Contents:
Introduction to JavaScript Pasteboard Operations
Adding Pasteboard Handlers to Elements
Manipulating Pasteboard Data
Introduction to JavaScript Pasteboard Operations
Support for pasteboard operations is implemented in JavaScript and may be applied to any element of your HTML page. To handle these operations, you provide functions to handle any of six JavaScript events:
onbeforecutoncutonbeforecopyoncopyonbeforepasteonpaste
You can provide handlers for the oncut, oncopy, and onpaste events if you want to define custom behavior for the corresponding operations. You can also provide handlers for the onbeforecut, onbeforecopy, and onbeforepaste events if you want to manipulate the target data before it is actually cut, copied, or pasted.
If your oncut, oncopy, and onpaste handlers do the actual work of cutting, copying, or pasting the data, your handler must call the preventDefault method of the event object. This method takes no parameters and notifies WebKit that your handler takes care of moving the data to or from the pasteboard. If you do not call this method, WebKit takes responsibility for moving the data. You do not need to call preventDefault if you simply want to be notified when the events occur.
Adding Pasteboard Handlers to Elements
You can add handlers for pasteboard events to any element in a web page. When a pasteboard operation begins, WebKit looks for the appropriate handler on the element that is the focus of the operation. If that element does not define a handler, WebKit walks up the list of parent elements until it finds one that does. (If no element defines a handler, WebKit applies the default behavior.) To demonstrate this process, suppose you have the following basic HTML in a web page:
<body oncut="MyBodyCutFunction()" |
oncopy="MyBodyCopyFunction()" |
onpaste="MyBodyPasteFunction()"> |
<span onpaste="MySpanPasteFunction()">Cut, copy, or paste here.</span> |
</body> |
If a user initiates a cut or copy operation on the text in the span tag, WebKit calls MyBodyCutFunction or MyBodyCopyFunction to handle the event. However, if the user tries to paste text into the span tag, WebKit calls the MySpanPasteFunction to handle the event. The MyBodyPasteFunction function would be called only if the paste operation occurred outside of the span tag.
Manipulating Pasteboard Data
When an event occurs, your handler uses the clipboardData object attached to the event to get and set the clipboard data. This object defines the clearData, getData, and setData methods to allow you to clear, get, and set the clipboard data.
Note: For security purposes, the getData method can be called only from within the onpaste event handler.
WebKit’s pasteboard implementation supports data types beyond those that are typically found in HTML documents. When you call either getData or setData, you specify the MIME type of the target data. For types it recognizes, including standard types found in HTML documents, WebKit maps the type to a known pasteboard type. However, you can also specify MIME types that correspond to any custom data formats your application understands. For most pasteboard operations, you will probably want to work with simple data types, such as plain text or a list of URIs.
WebKit also supports the ability to post the same data to the pasteboard in multiple formats. To add another format, you simply call setData once for each format, specifying the format’s MIME type and a string of data that conforms to that type.
To get a list of types currently available on the pasteboard, you can use the types property of the clipboardData object. This property contains an array of strings with the MIME types of the available data.
© 2004, 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)