Every browsing context has a selection. The selection may be empty, and the selection may have more than one range (a disjointed selection). The user should be able to change the selection. User agents are not required to let the user select more than one range, and may collapse multiple ranges in the selection to a single range when the user interacts with the selection. (But, of course, the user agent may let the user create selections with multiple ranges.)
This one selection must be shared by all the content of the browsing context (though not by nested browsing contexts), including any editing hosts in the document. (Editing hosts that are not inside a document cannot have a selection.)
If the selection is empty (collapsed, so that it has only one segment and that segment's start and end points are the same) then the selection's position should equal the caret position. When the selection is not empty, this specification does not define the caret position; user agents should follow platform conventions in deciding whether the caret is at the start of the selection, the end of the selection, or somewhere else.
On some platforms (such as those using Wordstar editing conventions), the caret position is totally independent of the start and end of the selection, even when the selection is empty. On such platforms, user agents may ignore the requirement that the cursor position be linked to the position of the selection altogether.
Mostly for historical reasons, in addition to the browsing context's selection, each textarea and
input element has an independent selection. These are the
text field
selections.
The datagrid and
select elements also have selections, indicating which items
have been picked by the user. These are not discussed in this section.
This specification does not specify how selections are
presented to the user. The Selectors specification, in conjunction with
CSS, can be used to style text selections using the ::selection pseudo-element. [SELECTORS] [CSS21]
The getSelection() method on the
Window interface must return the
Selection object representing the selection of that Window object's browsing
context.
For historical reasons, the getSelection() method
on the HTMLDocument interface
must return the same Selection
object.
interface Selection {
readonly attribute Node anchorNode;
readonly attribute long anchorOffset;
readonly attribute Node focusNode;
readonly attribute long focusOffset;
readonly attribute boolean isCollapsed;
void collapse(in Node parentNode, in long offset);
void collapseToStart();
void collapseToEnd();
void selectAllChildren(in Node parentNode);
void deleteFromDocument();
readonly attribute long rangeCount;
Range getRangeAt(in long index);
void addRange(in Range range);
void removeRange(in Range range);
void removeAllRanges();
DOMString toString();
};
The Selection interface is
represents a list of Range objects. The first item in the
list has index 0, and the last item has index count-1,
where count is the number of ranges in the list. [DOM2RANGE]
All of the members of the Selection interface are defined in terms of
operations on the Range objects represented by this object.
These operations can raise exceptions, as defined for the
Range interface; this can therefore result in the members of
the Selection interface raising
exceptions as well, in addition to any explicitly called out below.
The anchorNode attribute
must return the value returned by the startContainer
attribute of the last Range object in the list, or null if
the list is empty.
The anchorOffset attribute
must return the value returned by the startOffset
attribute of the last Range object in the list, or 0 if the
list is empty.
The focusNode attribute must
return the value returned by the endContainer
attribute of the last Range object in the list, or null if
the list is empty.
The focusOffset attribute
must return the value returned by the endOffset
attribute of the last Range object in the list, or 0 if the
list is empty.
The isCollapsed attribute
must return true if there are zero ranges, or if there is exactly one
range and its collapsed attribute is itself true.
Otherwise it must return false.
The collapse(parentNode, offset) method
must raise a WRONG_DOCUMENT_ERR DOM exception if parentNode's ownerDocument is not the
HTMLDocument object with which
the Selection object is associated.
Otherwise it is, and the method must remove all the ranges in the Selection list, then create a new
Range object, add it to the list, and invoke its setStart() and setEnd() methods with
the parentNode and offset values
as their arguments.
The collapseToStart()
method must raise an INVALID_STATE_ERR DOM exception if there
are no ranges in the list. Otherwise, it must invoke the collapse()
method with the startContainer and startOffset values of the first Range object
in the list as the arguments.
The collapseToEnd()
method must raise an INVALID_STATE_ERR DOM exception if there
are no ranges in the list. Otherwise, it must invoke the collapse()
method with the endContainer and endOffset values of the last Range object in
the list as the arguments.
The selectAllChildren(parentNode) method must invoke the collapse()
method with the parentNode value as the first argument
and 0 as the second argument, and must then invoke the selectNodeContents() method on the first (and only) range
in the list with the parentNode value as the argument.
The deleteFromDocument()
method must invoke the deleteContents() method on
each range in the list, if any, from first to last.
The rangeCount attribute
must return the number of ranges in the list.
The getRangeAt(index) method must return the indexth range in the list. If index is
less than zero or greater or equal to the value returned by the rangeCount
attribute, then the method must raise an INDEX_SIZE_ERR DOM
exception.
The addRange(range) method must add the given range Range object to the list of selections, at the end
(so the newly added range is the new last range). Duplicates are not
prevented; a range may be added more than once in which case it appears in
the list more than once, which (for example) will cause toString() to
return the range's text twice.
The removeRange(range) method must remove the first occurrence
of range in the list of ranges, if it appears at all.
The removeAllRanges()
method must remove all the ranges from the list of ranges, such that the
rangeCount attribute returns 0 after the
removeAllRanges() method is invoked
(and until a new range is added to the list, either through this interface
or via user interaction).
The toString() method must
return a concatenation of the results of invoking the toString() method of the Range object on each
of the ranges of the selection, in the order they appear in the list
(first to last).
In language bindings where this is supported, objects implementing the
Selection interface must stringify
to the value returned by the object's toString()
method.
In the following document fragment, the emphasised parts indicate the selection.
<p>The cute girl likes the <cite>Oxford English Dictionary</cite>.</p>
If a script invoked window.getSelection().toString(), the return value would
be "the Oxford English".
The Selection
interface has no relation to the DataGridSelection interface.
When we define HTMLTextAreaElement and HTMLInputElement we will have to add the IDL given below to both of their IDLs.
The input and textarea elements define four
members in their DOM interfaces for handling their text selection:
void select();
attribute unsigned long selectionStart;
attribute unsigned long selectionEnd;
void setSelectionRange(in unsigned long start, in unsigned long end);
These methods and attributes expose and control the selection of
input and textarea text fields.
The select() method must
cause the contents of the text field to be fully selected.
The selectionStart
attribute must, on getting, return the offset (in logical order) to the
character that immediately follows the start of the selection. If there is
no selection, then it must return the offset (in logical order) to the
character that immediately follows the text entry cursor.
On setting, it must act as if the setSelectionRange() method had been
called, with the new value as the first argument, and the current value of
the selectionEnd attribute as the second
argument, unless the current value of the selectionEnd is less than the new value,
in which case the second argument must also be the new value.
The selectionEnd
attribute must, on getting, return the offset (in logical order) to the
character that immediately follows the end of the selection. If there is
no selection, then it must return the offset (in logical order) to the
character that immediately follows the text entry cursor.
On setting, it must act as if the setSelectionRange() method had been
called, with the current value of the selectionStart attribute as the first
argument, and new value as the second argument.
The setSelectionRange(start, end) method must
set the selection of the text field to the sequence of characters starting
with the character at the startth position (in logical
order) and ending with the character at the (end-1)th position. Arguments greater than the length
of the value in the text field must be treated as pointing at the end of
the text field. If end is less than or equal to start then the start of the selection and the end of the
selection must both be placed immediately before the character with offset
end. In UAs where there is no concept of an empty
selection, this must set the cursor to be just before the character with
offset end.
To obtain the currently selected text, the following JavaScript suffices:
var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);
...where control is the input or
textarea element.
Characters with no visible rendering, such as U+200D ZERO WIDTH JOINER, still count as characters. Thus, for instance, the selection can include just an invisible character, and the text insertion cursor can be placed to one side or another of such a character.
When these methods and attributes are used with input
elements that are not displaying simple text fields, they must raise an
INVALID_STATE_ERR exception.