Labs/Jetpack/JEP/10: Difference between revisions

From MozillaWiki
< Labs‎ | Jetpack‎ | JEP
Jump to navigation Jump to search
Line 43: Line 43:
<code>options</code>: A dictionary containing key-value pairs of <code>data</code> and <code>dataType</code>.
<code>options</code>: A dictionary containing key-value pairs of <code>data</code> and <code>dataType</code>.


''Examples''
'''Examples'''


An example of setting the clipboard in action is as follows:
An example of setting the clipboard in action is as follows:
Line 61: Line 61:
</pre>
</pre>


'''Getting the clipboard'''
==== Getting the clipboard ====


<pre class="brush:js;toolbar:false;">var value = jetpack.os.clipboard.get()</pre>
<pre class="brush:js;toolbar:false;">jetpack.os.clipboard.get()</pre>
 
''Return value''
 
Returns a dictionary of <code>{data:dataType}</code> pairs. If there is nothing in the clipboard, <code>null</code> is returned.
 
<pre class="brush:js;toolbar:false;">jetpack.os.clipboard.get( dataType )</pre>
 
''Arguments''
 
<code>dataType</code>: The MIME-type of the data-type desired. Unlike other instances of <code>dataType</code>, 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 <code>var img = jetpack.os.clipboard.get( "image" );</code> 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, <code>null</code> is returned.
 
'''Examples'''
 
<pre class="brush:js;">
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 );
</pre>

Revision as of 11:53, 27 May 2009

Draft-template-image.png THIS PAGE IS A WORKING DRAFT Pencil-emoji U270F-gray.png
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

  • Author: Aza Raskin <aza at mozilla dot com>
  • Champion: Aza Raskin <aza at mozilla dot com>
  • Status: Draft
  • Type: API Track
  • Created: 26 May 2009

Introduction and Rationale

This JEP describes OS clipboard access to 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.

As part of this proposal is adding a jetpack.os namespace.

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( options )

Arguments

data: The value to be placed into the system clipboard. It can be anything, a string, a unicode string, a number, an image, and HTML fragment, etc.

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

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.

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({
  "hai2u", "text/plain",
  "hai<b>2u</b>", "text/html",
  "はい2u", "text/unicode"
});

Getting the clipboard

jetpack.os.clipboard.get()

Return value

Returns a dictionary of {data:dataType} 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.

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