We use cookies to make our website more effective. By using our website you agree to our privacy policy.

Namespace: selection-change


selection-change.js is part of Aloha Editor project http://www.alohaeditor.org

Aloha Editor ● JavaScript Content Editing Library
Copyright (c) 2010-2015 Gentics Software GmbH, Vienna, Austria.
Contributors http://www.alohaeditor.org/docs/contributing.html


addHandler(doc, watchSelection, mousemove)

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)

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

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)

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
comments powered by Disqus