Labs/Jetpack/JEP/10: Difference between revisions

From MozillaWiki
< Labs‎ | Jetpack‎ | JEP
Jump to navigation Jump to search
No edit summary
Line 19: Line 19:
=== Proposal ===
=== Proposal ===


Clipboard access will live at <code>jetpack.os.clipboard</code>. The <code>jetpack.os</code> will provide access to anything that relates to the OS (file access, OS info, etc.)
Clipboard access will live at <code>jetpack.clipboard</code>.


==== Setting the clipboard ====
==== Setting the clipboard ====


<pre class="brush:js;toolbar:false;">
== Setting the clipboard ==
jetpack.os.clipboard.set( data, [dataType] )
</pre>
 
''Arguments''
 
<code>data</code>: 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.
 
<code>dataType</code> (optional): Let's Jetpack know what kind of data is being passed in, in [http://en.wikipedia.org/wiki/Internet_media_type mime-type format]. For example, a plain string would take <code>"text/plain"</code>, HTML would be <code>"text/html"</code>, and an PNG would be <code>"image/png"</code>. If <code>dataType</code> isn't passed in, Jetpack makes its best guess or defaults to text.


<pre class="brush:js;toolbar:false;">
<pre class="brush:js;toolbar:false;">
jetpack.os.clipboard.set( options )
jetpack.clipboard.set( content )
jetpack.clipboard.set( content, flavor )
</pre>
</pre>


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.  
*'''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).
''Arguments''
 
<code>options</code>: A dictionary containing key-value pairs of <code>data</code> and <code>dataType</code>
<code>clipboard</code> 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'''
'''Examples'''


An example of setting the clipboard in action is as follows:
<pre class="brush:js;toolbar:false;">
 
jetpack.clipboard.set('hello');
<pre class="brush:js;">
jetpack.clipboard.set('<b>Hello</b>', 'html');
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"
});
</pre>
</pre>


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


<pre class="brush:js;toolbar:false;">jetpack.os.clipboard.get()</pre>
<pre class="brush:js;toolbar:false;">
var content = jetpack.clipboard.get();
var content = jetpack.clipboard.get( flavor );
</pre>


''Return value''
*'''No arguments''': Assumes a flavor of "plain".
*'''flavor''': A Jetpack clipboard flavor.


Returns a dictionary of <code>{dataType: data}</code> pairs. If there is nothing in the clipboard, <code>null</code> is returned.
You can figure out what flavors are currently on the clipboard by using


<pre class="brush:js;toolbar:false;">jetpack.os.clipboard.get( dataType )</pre>
<pre class="brush:js;toolbar:false;">var flavors = jetpack.clipboard.getCurrentFlavors();</pre>


''Arguments''
* '''returns''': An array of Jetpack clipboard flavors.


<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.
'''Examples''':


''Return value''
<pre class="brush:js;toolbar:false;">
var contents = jetpack.clipboard.get();
var img = jetpack.clipboard.get( "png" );
</pre>


The single value of the requested MIME-type stored in the clipboard. If nothing of that type exists, <code>null</code> is returned.
== Notes on Clipboard Flavors ==


<pre class="brush:js;toolbar:false;">jetpack.os.clipboard.get( [dataType], callback )</pre>
Optional:


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.
Reading/setting the clipboard requires asking for/giving the format of the data. This is done through "flavors", or slightly modified [http://en.wikipedia.org/wiki/Internet_media_type Internet media types].


''Arguments''
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.


<code>dataType</code> ''optional'': The MIME-type of data being requested. Like the other signatures of <code>clipboard.get</code>, if the first half of the MIME-type is passed in (e.g., "image"), Jetpack returns the best match of that type.
For Jetpack clipboard flavors, the before-the-slash type is left off unless needed to resolve a rare ambiguity.


<code>callback( value )</code>: Gets called when the data available. If <code>dataType</code> was provided, then <code>value</code> is the the value in the clipboard. If it was not provided, then <code>value</code> a dictionary of <code>{data:dataType}</code> pairs. If nothing is in the clipboard <code>null</code> is returned.
E.g., plain, html, png, gif, video/ogg, audio/ogg


'''Examples'''
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 <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.
 
<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 );


jetpack.os.clipboard.get( "image", function(img){
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.
  document.body.appendChild( img );
});
</pre>

Revision as of 22:05, 15 June 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

  • 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

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.

Retrieved from "https://wiki.mozilla.org/index.php?title=Labs/Jetpack/JEP/10&oldid=149431"