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.os.clipboard. The jetpack.os will provide access to anything that relates to the OS (file access, OS info, etc.)

Setting the clipboard

jetpack.os.clipboard.set( data, [dataType] )

Arguments

data: The value to be placed into the system clipboard. 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.

dataType (optional): Let's Jetpack know what kind of data is being passed in, in mime-type format. For example, a plain string would take "text/plain", HTML would be "text/html", and an PNG would be "image/png". If dataType isn't passed in, Jetpack makes its best guess or defaults to text.

jetpack.os.clipboard.set( options )

Often it is necessary to put multiple formats/views of the same data into the clipboard. This way, when another program tries to access the data stored in the system clipboard, it can get the data in the format it knows how to handle.

Arguments

options: A dictionary containing key-value pairs of data and dataType clipboard some operating systems have more than one clipboard: the "global" clipboard and the "selection" clipboard. You can pass in either "global" or "selection". If you pass in a non-existent clipboard, an error is thrown.

Examples

An example of setting the clipboard in action is as follows:

var words = "The quick brown fox jumped over the lazy dog.";
jetpack.os.clipboard.set( words );

var html = "<div>Hello <i>there!</i></div>";
jetpack.os.clipboard.set( html, "text/html" );

jetpack.os.clipboard.set({
  "text/plain": "hai2u",
  "text/html": "hai<b>2u</b>",
  "text/unicode": "はい２u"
});

Getting the clipboard

jetpack.os.clipboard.get()

Return value

Returns a dictionary of {dataType: data} pairs. If there is nothing in the clipboard, null is returned.

jetpack.os.clipboard.get( dataType )

Arguments

dataType: The MIME-type of the data-type desired. Unlike other instances of dataType, everything after the "/" can be omitted, and Jetpack will choose the best available match given an internally pecking order of MIME-types (e.g., unicode is better than plain text, etc.). 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.

Return value

The single value of the requested MIME-type stored in the clipboard. If nothing of that type exists, null is returned.

jetpack.os.clipboard.get( [dataType], callback )

There are cases where an application can asynchronously place data in the clipboard. For example, when a copy action is taken on a 50MB picture in Photoshop, instead of the 50MB being placed in the clipboard, Photoshop can place register a "deffered" so that the data isn't actually copied until another application tries to paste. That shuffling of data can take a while, which is why an asynchronous callback is required. However, most of the time this is over-kill as a Jetpack author is normally just copying and pasting text.

Arguments

dataType optional: The MIME-type of data being requested. Like the other signatures of clipboard.get, if the first half of the MIME-type is passed in (e.g., "image"), Jetpack returns the best match of that type.

callback( value ): Gets called when the data available. If dataType was provided, then value is the the value in the clipboard. If it was not provided, then value a dictionary of {data:dataType} pairs. If nothing is in the clipboard null is returned.

Examples

var clip = jetpack.os.clipboard.get();
if( clip["text/plain"] )
  jetpack.notifications.show( clip["text/plain"] );

var img = jetpack.os.clipboard.get( "image" );
$("body").append( img );

jetpack.os.clipboard.get( "image", function(img){
  document.body.appendChild( img );
});