JEP 111 - Selection

• Champion: Myk Melez <myk@mozilla.org>
• Status: Under Review
• Bug Ticket: bug 547092
• Type: API

Introduction

Jetpack extensions should be able to get and set the current text selection and observe select events.

Use Cases

• Look-up information depending on what is selected
  • onSelect or sometime afterward
• Retrieving selected content
• Applying changes to the selection

Implementation

Module

The selection module gives extensions access to the selection. Importing the module returns a singleton.

let selection = require("selection");

Properties

text

String; the text version of the selection, if any

html

String; the HTML version of the selection, if any

onSelect

Function; a callback function to call when some text is selected

contiguous

Boolean; whether or not the selection is contiguous (see #Discontiguous Selections)

If there is a selection:

• getting the text property returns the text value of the selection;
• getting the html property returns the HTML value of the selection, if any, otherwise undefined;
• setting the text property replaces the selection with the value to which the property is set and sets the html property to the same value to which the text property is being set;
• setting the html property replaces the selection with the value to which the property is set and sets the text property to the text version of the HTML value.

If there is not a selection:

• getting either property returns undefined;
• setting either property has no effect.

Discontiguous Selections

Discontiguous selections can be accessed by iterating the selection singleton, which returns Selection objects with the same properties as the selection singleton:

let selection = require("selection");
for each (let subselection in selection) {
  console.log(subselection.text);
}

To determine whether or not the selection is discontiguous, check its contiguous property, e.g.:

let sel = require("selection");
if (sel.contiguous)
  console.log("The selection is: " + sel.text);
else
  console.log("The selections are: " + [s.text for each (s in sel)].join(","));

Examples

Log the current selection:

let selection = require("selection");
if (selection.text)
  console.log(selection.text);

Surround HTML selections with delimiters:

let selection = require("selection");
selection.onSelect = function() {
  if (selection.html)
    selection.html = "\\\\\\" + selection.html + "///";
};

Issues

• What happens when the selection changes programmatically? Does onSelect still get called?
• If there is no selection, what should the contiguous property return--false, undefined, something else?
• If contiguous is true but the API user calls the text and html getter properties, what is returned? The text or html of the first selection? undefined?
• What happens if the contiguous selections change while they are being iterated? In java-land, we would throw a ConcurrentModificationException.

References

• Labs/Jetpack/JEP/12