Labs/Jetpack/JEP/12

	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 12 - jetpack.selection

• Champion: Aza Raskin <aza at mozilla dot com>
• Status: Implementing
• Type: API Track
• Created: 24 June 2009
• Reference Implementation: jetpack.future.import("selection")
• JEP Index

Introduction and Rationale

Performing a selection is one of fundamental computer-human interactions, acting as a close proxy for a users locus of attention. Even at the time of the writing of this JEP, numerous Jetpacks have already implemented disparate ways of getting and detecting selections.

Jetpacks should be able to set, get, and listen for selection events.

Proposal

The functions to manipulate and access the selection lives in jetpack.selection.

Getting and Setting the Selection

Getting and setting the selection live in a family of getters and setters, dependent on the format. For the first version of .selection we include to formats: text, and html.

Setting the selection

jetpack.selection.text = "Hello";
jetpack.selection.html = "<b>Hello</b>";

Getting the selection

var textOfSel = jetpack.selection.text;
var htmlOfSel = jetpack.selection.html;

Eventually, one may be able to do jetpack.selection.fragment which would let you manipulate the selection live. That is, however, outside the scope of JEP 12.

onSelection

A very common desire is to perform some sort of action when a selection is made. Often that is looking up the selection, or creating an actionable nib. jetpack.selection.onSelection enables Jetpack authors to easily get notified when a selection is made.

jetpack.selection.onSelection( callback );

Arguments

• callback: Is the function to be called when a selection is made. It receives no arguments. Instead, use jetpack.selection.*.

To remove an event handler is done the normal Jetpack way:

jetpack.selection.onSelection.unbind( callback );

Arguments

• callback: A pointer to the event handler to be unbound.

Example

jetpack.selection.onSelection(function(){
  var html = jetpack.selection.html;
  jetpack.selection.html = ">>>" + html + "<<<";
});