This is revision 1.5612.
The input
and textarea
elements define
the following members in their DOM interfaces for handling their
selection:
void select(); attribute unsigned long selectionStart; attribute unsigned long selectionEnd; attribute DOMString selectionDirection; void setSelectionRange(unsigned long start, unsigned long end, optional DOMString direction);
These methods and attributes expose and control the selection of
input
and textarea
text fields.
select
()Selects everything in the text field.
selectionStart
[ = value ]Returns the offset to the start of the selection.
Can be set, to change the start of the selection.
selectionEnd
[ = value ]Returns the offset to the end of the selection.
Can be set, to change the end of the selection.
selectionDirection
[ = value ]Returns the current direction of the selection.
Can be set, to change the direction of the selection.
The possible values are "forward
", "backward
", and "none
".
setSelectionRange
(start, end [, direction] )Changes the selection to cover the given substring in the given direction. If the direction is omitted, it will be reset to be the platform default (none or forward).
When these methods and attributes are used with
input
elements while they don't apply, they must throw
an InvalidStateError
exception. Otherwise, they must
act as described below.
For input
elements, these methods and attributes
must operate on the element's value. For textarea
elements, these methods and attributes must operate on the element's
raw value.
Where possible, user interface features for changing the text
selection in input
and textarea
elements
must be implemented in terms of the DOM API described in this
section, so that, e.g., all the same events fire.
The selections of input
and textarea
elements have a direction, which is either forward,
backward, or none. This direction is set when the user
manipulates the selection. The exact meaning of the selection
direction depends on the platform.
On Windows, the direction indicates the position of the caret relative to the selection: a forward selection has the caret at the end of the selection and a backward selection has the caret at the start of the selection. Windows has no none direction. On Mac, the direction indicates which end of the selection is affected when the user adjusts the size of the selection using the arrow keys with the Shift modifier: the forward direction means the end of the selection is modified, and the backwards direction means the start of the selection is modified. The none direction is the default on Mac, it indicates that no particular direction has yet been selected. The user sets the direction implicitly when first adjusting the selection, based on which directional arrow key was used.
The select()
method
must cause the contents of the text field to be fully selected, with
the selection direction being none, if the platform support
selections with the direction none, or otherwise
forward. The user agent must then queue a task
to fire a simple event that bubbles named select
at the element, using the
user interaction task source as the task source.
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;
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; and the current value of the selectionDirection
as the third argument.
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, the new value as the second
argument, and the current value of the selectionDirection
as the third argument.
The selectionDirection
attribute must, on getting, return the string corresponding to the
current selection direction: if the direction is forward,
"forward
"; if the direction is
backward, "backward
"; and otherwise,
"none
".
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, the current value of the selectionEnd
attribute as the second argument, and the new value as the third
argument.
The setSelectionRange(start, end, direction)
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. The direction of the selection
must be set to backward if direction is a
case-sensitive match for the string "backward
", forward if direction is a case-sensitive match for
the string "forward
" or if the platform does
not support selections with the direction none, and
none otherwise (including if the argument is omitted). The
user agent must then queue a task to fire a
simple event that bubbles named select
at the element, using the
user interaction task source as the task source.
All elements to which this API applies have either a selection or a text entry cursor position at all times (even for elements that are not being rendered). User agents should follow platform conventions to determine their initial state.
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.
To obtain the currently selected text, the following JavaScript suffices:
var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);
To add some text at the start of a text control, while maintaining the text selection, the three attributes must be preserved:
var oldStart = control.selectionStart; var oldEnd = control.selectionEnd; var oldDirection = control.selectionDirection; var prefix = "http://"; control.value = prefix + control.value; control.setSelectionRange(oldStart + prefix.length, oldEnd + prefix.length, oldDirection);