Labs/Jetpack/Reboot/JEP/111: Difference between revisions

Labs/Jetpack/Reboot/JEP/111 (view source)

Revision as of 00:54, 5 February 2010

1,334 bytes added , 5 February 2010

basic selection JEP

MykMelez

canmove, Confirmed users

2,056

edits

@@ Line 1: / Line 1: @@
-== JEP 111 - Selection ==
+= JEP 111 - Selection =
-* Champion: Myk Melez - myk@mozilla.com
+* Champion: Myk Melez <myk@mozilla.org>
 * Status: Accepted/In-Queue
 * Bug Ticket:
 * Type: API
+= Introduction =
-=== Proposal ===
+Jetpacks should be able to set, get, and listen for selection events.
-* What will it do?
-* What does it enable internally/externally?
-* How hard is it to implement?
+= selection Module =
-=== Dependencies & Requirements ===
+The <code>selection</code> module gives extensions access to the selection.
-* Are there any Firefox platform bugs blocking it?
-* Does other Jetpack platform code need to be modified or added?
-* Does its implementation affect any other projects or code?
-=== Internal Methods ===
+The module defines two properties, <code>text</code> and <code>html</code>, which represent plaintext and HTML versions of the selection:
-* What methods, mechanisms, or resources does this provide internally within the Jetpack platform code.
+ let selection = require("selection");
+ selection.text; // the text version
+ selection.html; // the HTML version
-=== API Methods ===
+Neither property is guaranteed to be defined, as there may not be a selection, and a selection may not have an HTML version.
-* What are the pretty API wrapped methods externally exposed to Jetpack developers?
+= Getting the Selection =
+Extensions get the selection by accessing the module's <code>text</code> or <code>html</code> properties:
+ let text = selection.text;
+ let html = selection.html;
+= Setting the Selection =
+Extensions set the selection by setting the module's <code>text</code> or <code>html</code> properties:
+ selection.text = "Hello";
+ selection.html = "&lt;b>Hello&lt;/b>";
+Setting the <code>text</code> property automatically updates the <code>html</code> property to be undefined. Setting the <code>html</code> property automatically updates the <code>text</code> property to be the plaintext version of the HTML to which the <code>html</code> property was set.
+= onSelect =
+The onSelect method enables registration of a callback to be notified when the user makes a selection.
+ selection.onSelect(callback);
+''Arguments''
+* '''callback''': Is the function to be called when a selection is made. It receives no arguments.
+To remove an event handler is done the normal Jetpack way:
+ selection.onSelect.unbind( callback );
+''Arguments''
+* '''callback''': A pointer to the event handler to be unbound.
+= Example =
+ let selection = require("selection");
+ selection.onSelect(function() {
+   let html = selection.html;
+   selection.html = ">>>" + html + "<<<";
+ });
+= References =
+* [[Labs/Jetpack/JEP/12]]