Selection object

Selection object

Represents textual (and block) selection inside element that has either htmlarea or richtext behaviors attached.

To access the selection object of the element use its selection property.

Properties

type
null | symbol, read-only property. Reports type of the selection: #text, #cells, #blocks.
isCollapsed
true | false, read-only property. true if the selection is represented by only caret so selection.start == selection.end.
anchor
null | bookmark, read-only property. DOM position of selection anchor.
caret
null | bookmark, read-only property. DOM position of selection caret.
start
null | bookmark, read-only property. DOM position of either caret or anchor, whichever is lower in DOM order.
end
null | bookmark, read-only property. DOM position of either caret or anchor, whichever is greater in DOM order.
text
string, read-only property. text contained in the selection.
html
string, read-only property. selected html fragment.

Enumeration

for … in
for(var (pos,char) in element.selection) { /* loop body */ }

TBD. (enumerates caret positions and characters in the selection)

Methods

collapse
( towhat:symbol ) returns: bookmark.

Collapse selection range to single caret position. towhat is one of: #toCaret, #toAnchor,#toStart or #toEnd

select
( caret:bookmark [ , anchor:bookmark ] ) returns: true | false

Set’s selection to the range or single caret position.

advance
( step:symbol [, target:symbol] ) returns: true | false.

Advances target to new position by step. The target defines what end of selection to advance, can be one of:

  • #both – default, caret and anchor is moved to new position, collapses the selection;
  • #caret – caret position, changes the selection;
  • #anchor – anchor position, changes the selection;
  • #start – start position (either anchor or caret), changes the selection;
  • #end – end position (either anchor or caret), changes the selection

The step is one of:

  • #next – next caret position;
  • #prior – previous caret position;
  • #wordStart – start of the word;
  • #wordEnd – end of the word;
  • #lineStart – start of the line;
  • #lineEnd – end of the line;
  • #first – first caret position of the element having the selection;
  • #last – last caret position of the element having the selection.
applyMark
(start: bookmark, end: bookmark, markName: string): returns: integer

marks region of text from start to end by mark name that can be styled in CSS by ::mark(markName) { ... } selector/rule.

The function returns number of changes made.

clearMark
(start: bookmark, end: bookmark, markName: string): returns: integer

clears mentioned mark from the region.
The function returns number of changes made.

Bookmark

Some methods above use so called bookmark object that is a tuple (of length 3) having tag #bookmark. Usually you will get ready to use bookmarks from various properties or  methods but if needed bookmarks can be constructed literally as:

var bm = [bookmark: node, index, after];

Where:

  • node – Element or Node object.
  • index – index of the position inside the node. В for Element it is nodeIndex of its child node and for Nodes it is character index.
  • after – true | false, if true then this bookmark marks "past edge" of the entity marked by node/index pair.