Labs/Jetpack/JEP/10

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

JEP 10 - Clipboard Support

• Champion: Aza Raskin <aza at mozilla dot com>
• Editors: Paul O’Shannessy <poshannessy@mozilla.com>
• Status: Implementing
• Type: API Track
• Created: 26 May 2009
• Reference Implementation: None
• 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.

Proposal

Clipboard access will live at jetpack.clipboard.

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).

Examples

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.

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.

Examples:

var contents = jetpack.clipboard.get();
var img = jetpack.clipboard.get( "png" );

Notes on Clipboard Flavors

Optional:

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 retruend. Jetpack will choose an available match given a possibly arbitrary ordering MIME-types (e.g., if you pass in "image" Jetpack may return a "png"). 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.