Table of Contents

• 1. Background
• 2. Definition
  • 2.1 Attributes
  • 2.2 Methods
• 3. Extensions to Other Interfaces
  • 3.1 Methods
  • 3.2 Methods
• 4. User Interactions
• A. Acknowledgements
• B. References
  • B.1 Informative references

2. Definition

Every document ([DOM4]) with a browsing context ([HTML5]) has a unique Selection object associated with it. Selection objects are known as selections.

This one selection must be shared by all the content of the document (though not by nested documents), including any editing hosts in the document. Editing hosts (defined in [HTML5]) that are not inside a document cannot have a selection

Each selection can be associated with a single range (defined in [DOM4]). When there is no range associated with the selection, the selection is empty. The selection must be initially empty.

Once a selection is associated with a given range, it must continue to be associated with that same range until this specification requires otherwise.

If the selection's range is not null and is collapsed ([DOM4]), then the caret position must be at that range's boundary point. 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.

Each selection has a direction, forwards, backwards, or directionless. If the user creates a selection by indicating first one boundary point of the range and then the other (such as by clicking on one point and dragging to another), and the first indicated boundary point is after ([DOM4]) the second, then the corresponding selection must initially be backwards. If the first indicated boundary point is before ([DOM4]) the second, then the corresponding selection must initially be forwards. Otherwise, it must be directionless.

Selections also have an anchor and a focus. If the selection's range is null, its anchor and focus are both null. If the selection's range is not null and its direction is forwards, its anchor is the range's start, and its focus is the end. Otherwise, its focus is the start and its anchor is the end.

interface Selection {
    readonly    attribute Node?         anchorNode;
    readonly    attribute unsigned long anchorOffset;
    readonly    attribute Node?         focusNode;
    readonly    attribute unsigned long focusOffset;
    readonly    attribute boolean       isCollapsed;
    readonly    attribute unsigned long rangeCount;
    Range       getRangeAt (unsigned long index);
    void        addRange (Range range);
    void        removeRange (Range range);
    void        removeAllRanges ();
    void        collapse (Node node, unsigned long offset);
    void        collapseToStart ();
    void        collapseToEnd ();
    void        extend (Node node, unsigned long offset);
    void        selectAllChildren (Node node);
    void        deleteFromDocument ();
    stringifier DOMString ();
};

All of the members of the Selection interface are defined in terms of operations on the range object (if any) represented by the object. These operations can raise exceptions, as defined for the Range ([DOM4]) interface; this can therefore result in the members of the Selection interface raising exceptions as well, in addition to any explicitly called out below.

3. Extensions to Other Interfaces

This specification extends several interfaces to provide entry points to the interfaces defined in this specification.

Extensions to Document interface

partial interface Document {
    Selection? getSelection ();
};

Extensions to Window interface

partial interface Window {
    Selection? getSelection ();
};

4. User Interactions

The user agent should allow the user to change the selection associated with the active document (defined in [HTML5]). If the user makes any modification to a selection, the user agent must create a new range with suitable start and end of the range ([DOM4]) and associate the selection with this new range (not modify the existing range).

The user agent must not make a selection empty if it was not already empty in response to any user actions (e.g. clicking on a non-editable region).