Labs/Jetpack/JEP/10: Difference between revisions

From MozillaWiki
< Labs‎ | Jetpack‎ | JEP
Jump to navigation Jump to search
 
(8 intermediate revisions by 2 users not shown)
Line 4: Line 4:


* Champion: Aza Raskin <aza at mozilla dot com>
* Champion: Aza Raskin <aza at mozilla dot com>
* Editors: Paul O’Shannessy <poshannessy@mozilla.com>
* Editors: Paul O’Shannessy <paul at oshannessy dot com>
* Status: Implementing
* Status: Implementing
* Type: API Track
* Type: API Track
* Created: 26 May 2009
* Created: 26 May 2009
* Reference Implementation: None
* Reference Implementation: None
* Relevant Bugs: {{bug|495532}} and {{bug|499368}}
* [[Labs/Jetpack/JEPs|JEP Index]]
* [[Labs/Jetpack/JEPs|JEP Index]]


Line 19: Line 20:
=== 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;">
<pre class="brush:js;toolbar:false;">
jetpack.os.clipboard.set( data, [dataType] )
jetpack.clipboard.set( content )
jetpack.clipboard.set( content, flavor )
</pre>
</pre>


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


<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.
'''Examples'''
 
<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('hello');
jetpack.clipboard.set('<b>Hello</b>', 'html');
</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.
==== Getting the clipboard ====


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


<code>options</code>: A dictionary containing key-value pairs of <code>data</code> and <code>dataType</code>
*'''No arguments''': Assumes a flavor of "plain".
<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.
*'''flavor''': A Jetpack clipboard flavor.


'''Examples'''
* '''returns''': The data on the clipboard if available in provided flavor


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


<pre class="brush:js;">
<pre class="brush:js;toolbar:false;">
var words = "The quick brown fox jumped over the lazy dog.";
var contents = jetpack.clipboard.get();
jetpack.os.clipboard.set( words );
var html = jetpack.clipboard.get( "html" );
 
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 ====
==== Current Flavors ====


<pre class="brush:js;toolbar:false;">jetpack.os.clipboard.get()</pre>
You can figure out what flavors are currently on the clipboard by using


''Return value''
<pre class="brush:js;toolbar:false;">
var flavors = jetpack.clipboard.getCurrentFlavors();
</pre>


Returns a dictionary of <code>{dataType: data}</code> pairs. If there is nothing in the clipboard, <code>null</code> is returned.
* '''returns''': An array of Jetpack clipboard flavors.


<pre class="brush:js;toolbar:false;">jetpack.os.clipboard.get( dataType )</pre>
=== Notes on Clipboard Flavors ===


''Arguments''
==== Additional Reading ====


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


''Return value''
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.


The single value of the requested MIME-type stored in the clipboard. If nothing of that type exists, <code>null</code> is returned.
For Jetpack clipboard flavors, the before-the-slash type is left off unless needed to resolve a rare ambiguity.


<pre class="brush:js;toolbar:false;">jetpack.os.clipboard.get( [dataType], callback )</pre>
E.g., plain, html, png, gif, video/ogg, audio/ogg


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


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


<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.
==== Jetpack Clipboard Flavors ====


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


'''Examples'''
* '''plain''' - This is normal plain text. It is in unicode (internally equivalent to text/unicode)
* '''html''' - This is HTML.


<pre class="brush:js;">
=== Image Support ===
var clip = jetpack.os.clipboard.get();
if( clip["text/plain"] )
  jetpack.notifications.show( clip["text/plain"] );


var img = jetpack.os.clipboard.get( "image" );
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.
$("body").append( img );


jetpack.os.clipboard.get( "image", function(img){
Another JEP will be created soon with more information.
  document.body.appendChild( img );
});
</pre>

Latest revision as of 00:04, 11 July 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 <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.

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.
  • returns: The data on the clipboard if available in provided flavor

Examples: 

var contents = jetpack.clipboard.get();
var html = jetpack.clipboard.get( "html" );

Current Flavors

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

Additional Reading

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.

Image Support

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.

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