JEP 10 - Clipboard Support
- Champion: Aza Raskin <aza at mozilla dot com>
- Editors: Paul O’Shannessy <paul at oshannessy dot com>
- Status: Implementing
- Type: API Track
- Created: 26 May 2009
- Reference Implementation: None
- Relevant Bugs: bug 495532 and bug 499368
- JEP Index
Introduction and Rationale
This JEP describes OS clipboard access for the Jetpack API.
A number of Jetpacks have already implemented their own versions of clipboard access. It makes sense to unify the API and allow for a clean way for Jetpacks to get and set the clipboard in a variety of formats. The proposed API is informed by the MDC clipboard documentation.
Clipboard access will live at
Setting the clipboard
jetpack.clipboard.set( content ) jetpack.clipboard.set( content, flavor )
- content: The content to put on the clipboard. If no other arguments are supplied, the content is assumed to be of flavor "plain". For now, this can only be text or an image. In the future, it can be anything that is place-able on the system clipboard.
- flavor: A Jetpack clipboard flavor (see below).
jetpack.clipboard.set('hello'); jetpack.clipboard.set('<b>Hello</b>', 'html');
Getting the clipboard
var content = jetpack.clipboard.get(); var content = jetpack.clipboard.get( flavor );
- No arguments: Assumes a flavor of "plain".
- flavor: A Jetpack clipboard flavor.
- returns: The data on the clipboard if available in provided flavor
var contents = jetpack.clipboard.get(); var html = jetpack.clipboard.get( "html" );
You can figure out what flavors are currently on the clipboard by using
var flavors = jetpack.clipboard.getCurrentFlavors();
- returns: An array of Jetpack clipboard flavors.
Notes on Clipboard Flavors
Reading/setting the clipboard requires asking for/giving the format of the data. This is done through "flavors", or slightly modified Internet media types.
Mime-types are often redundant, though. Take for example, "text/html". There are no other mime-types ending in "html" so "html" is enough to uniquely identify the flavor. In fact, it appears that the only ambiguity exists around some "audio/" and "video/" mime-types which share the same after-the-slash type.
For Jetpack clipboard flavors, the before-the-slash type is left off unless needed to resolve a rare ambiguity.
E.g., plain, html, png, gif, video/ogg, audio/ogg
On the flip side. Everything after the "/" can be omitted if you don't care about a specific type being returned. Jetpack will choose an available match given a possibly arbitrary ordering MIME-types (e.g., if you pass in "image" Jetpack may return an image in PNG format). This enables an author to simple write
var img = jetpack.os.clipboard.get( "image" ); and not have to worry about what particular image format the clipboard was storing the image in.
Odd footnote: It appears in the documentation for the clipboard on MDC that there exists a "text/unicode" flavor. However, I can find no mention of it in the Internet media type spec.
Jetpack Clipboard Flavors
As mentioned above, we've made it a bit easier to use flavors. We haven't implemented all flavors, so for now there are only the text related flavors.
- plain - This is normal plain text. It is in unicode (internally equivalent to text/unicode)
- html - This is HTML.
Images are not supported yet. We have yet to finalize the API around image use & the clipboard. For now you should get errors if you try to set or get the clipboard with an image.
Another JEP will be created soon with more information.