Namespace: selection-change

Methods

addHandler(doc, watchSelection, mousemove)

selection-change.js, line 145

Adds a handler function to events that may cause a selection-change.

Our strategy

Use the selectionchange event (see below) when available (Chrome, IE) and
additionally hook into keyup, keypress, mouseup, touchend events (other
browsers). We need keyup events even in IE to detect selection changes
caused by text input. Keypress events are necessary to capture selection
changes when the user is auto-repeating text-input by holding down a key,
except in Chrome it's not necessary because there the selectionchange
event fires on text-input (See maybeNextTick() for more information
regarding auto-repeating text-input). Hooking into all events on all
browsers does no harm. Touchend is probably necessary for mobile support
other than webkit, although I only tested it on webkit, where it is not
necessary due to selectionchange support.

For programmatic selection changes we recommend programmatically firing
the selectionchange event on the document element (IE7 needs the document
element, but for IE9+, Chrome and Firefox triggering it on an element
works too).

We set useCapture to true, so that a stopPropagation call in the bubbling
phase will not starve our handlers. In IE < 9 someone may still do it
since useCapture is not supported.

Behaviour of the 'selectionchange' event:
* will be fired on every selection change, including when the user
selects something by pressing and holding the mouse button and
dragging the selection,
* will not be fired when the user enters text e.g. in a content
editable in IE9 and IE10,
* will be fired when the selection is set programatically in Chrome,
but not in IE9 and IE10,
* works in IE as far back as IE7 and Chrome but doesn't work in Firefox or Opera.
* can be feature detected with ('onselectionchange' in document).

Name	Type	Description
doc	Document
watchSelection	function	A handler function like the one returned from handler().
mousemove	boolean	optional Even with all the events above hooked, we only get up-to-date selection change updates when the user presses the mouse and drags the selection in Chrome and IE, but not in Firefox (and probably others). This case can be covered by handling the mousemove event. We don't do it by default because handling the mousemove event could have different implications from handling up/down/press events.

handler(getBoundaries, boundaries, fn)

selection-change.js, line 82

Creates a handler that can be used to listen to selection change events,
and which will call the given handler function when the selection
changes.

See watchSelection().

Name	Type	Description
getBoundaries	function
boundaries	Array.<Boundary>	current selection
fn	function	A handler function that will be called with the changed selection, and the event that caused the selection change.

removeHandler(doc, watchSelection, mousemove)

selection-change.js, line 174

Removes a handler add with addHandler().

All arguments including mousemove must be the same as when the handler
was added.

Expect the handler to be called even after it was removed.

Name	Type	Description
doc	Document
watchSelection	function
mousemove	boolean	optional