This section describes various features that allow authors to enable users to edit documents and parts of documents interactively.
This section is non-normative.
Would be nice to explain how these features work together.
contenteditable attributeThe contenteditable attribute is
a common attribute. User agents must support this attribute on all HTML elements.
The contenteditable attribute is an enumerated attribute whose keywords are the empty
string, true, and false. The
empty string and the true keyword map to the
true state. The false keyword maps to the
false state. In addition, there is a third state, the
inherit state, which is the missing value default (and
the invalid value default).
If an HTML element
has a contenteditable attribute set to the
true state, or it has its contenteditable attribute set to the
inherit state and if its nearest ancestor HTML element with the contenteditable attribute set to a
state other than the inherit state has its attribute set to the true
state, or if it and its ancestors all have their contenteditable attribute set to the
inherit state but the Document has designMode
enabled, then the UA must treat the element as editable (as described below).
Otherwise, either the HTML element has a contenteditable attribute set to the
false state, or its contenteditable attribute is set to
the inherit state and its nearest ancestor HTML element with the contenteditable attribute set to a
state other than the inherit state has its attribute set to the false
state, or all its ancestors have their contenteditable attribute set to the
inherit state and the Document itself has designMode
disabled; either way, the element is not editable.
The contentEditable DOM
attribute, on getting, must return the string "true"
if the content attribute is set to the true state, false" if the content attribute is set to the false state,
and "inherit" otherwise. On setting, if the new
value is case-insensitively equal to the string "inherit" then the content attribute must be removed, if
the new value is case-insensitively equal to the string
"true" then the content attribute must be set to the
string "true", if the new value is
case-insensitively equal to the string "false" then the content attribute must be set to the
string "false", and otherwise the attribute setter
must raise a SYNTAX_ERR exception.
The isContentEditable DOM
attribute, on getting, must return true if the element is editable, and false otherwise.
If an element is editable and its parent element is not, or if an element is editable and it has no parent element, then the element is an editing host. Editable elements can be nested. User agents must make editing hosts focusable (which typically means they enter the tab order). An editing host can contain non-editable sections, these are handled as described below. An editing host can contain non-editable sections that contain further editing hosts.
When an editing host has focus, it must have a caret position that specifies where the current editing position is. It may also have a selection.
How the caret and selection are represented depends entirely on the UA.
There are several actions that the user agent should allow the user to perform while the user is interacting with an editing host. How exactly each action is triggered is not defined for every action, but when it is not defined, suggested key bindings are provided to guide implementors.
User agents must allow users to move the caret to any position within
an editing host, even into nested editable elements. This could be
triggered as the default action of keydown events with various key identifiers
and as the default action of mousedown events.
User agents must allow users to change the
selection within an editing host, even into nested editable
elements. User agents may prevent selections from being made in ways
that cross from editable elements into non-editable elements (e.g. by
making each non-editable descendant atomically selectable, but not
allowing text selection within them). This could be triggered as the
default action of keydown events with
various key identifiers and as the default action of mousedown events.
This action must be triggered as the default action of a textInput event, and may be triggered by
other commands as well. It must cause the user agent to insert the
specified text (given by the event object's data
attribute in the case of the textInput event) at the caret.
If the caret is positioned somewhere where phrasing content is not allowed (e.g. inside an
empty ol element), then the user agent
must not insert the text directly at the caret position. In such cases
the behavior is UA-dependent, but user agents must not, in response to a
request to insert text, generate a DOM that is less conformant than the
DOM prior to the request.
User agents should allow users to insert new paragraphs into elements that contains only content other than paragraphs.
UAs should offer a way for the user to request that the current
paragraph be broken at the caret, e.g. as the default action of a keydown event whose identifier is the "Enter"
key and that has no modifiers set.
The exact behavior is UA-dependent, but user agents must not, in response to a request to break a paragraph, generate a DOM that is less conformant than the DOM prior to the request.
UAs should offer a way for the user to request an explicit line break
at the caret position without breaking the paragraph, e.g. as the
default action of a keydown event whose
identifier is the "Enter" key and that has a shift modifier set. Line
separators are typically found within a poem verse or an address. To
insert a line break, the user agent must insert a br element.
If the caret is positioned somewhere where phrasing content is not allowed (e.g. in an empty
ol element), then the user agent must not
insert the br element directly at the
caret position. In such cases the behavior is UA-dependent, but user
agents must not, in response to a request to insert a line separator,
generate a DOM that is less conformant than the DOM prior to the
request.
UAs should offer a way for the user to delete text and elements,
including non-editable descendants, e.g. as the default action of keydown events whose identifiers are "U+0008"
or "U+007F".
Five edge cases in particular need to be considered carefully when implementing this feature: backspacing at the start of an element, backspacing when the caret is immediately after an element, forward-deleting at the end of an element, forward-deleting when the caret is immediately before an element, and deleting a selection whose start and end points do not share a common parent node.
In any case, the exact behavior is UA-dependent, but user agents must not, in response to a request to delete text or an element, generate a DOM that is less conformant than the DOM prior to the request.
UAs should offer the user the ability to mark text and paragraphs with semantics that HTML can express.
UAs should similarly offer a way for the user to insert empty semantic elements to subsequently fill by entering text manually.
UAs should also offer a way to remove those semantics from marked up text, and to remove empty semantic element that have been inserted.
In response to a request from a user to mark text up in italics, user
agents should use the i element to
represent the semantic. The em element
should be used only if the user agent is sure that the user means to
indicate stress emphasis.
In response to a request from a user to mark text up in bold, user
agents should use the b element to
represent the semantic. The strong
element should be used only if the user agent is sure that the user
means to indicate importance.
The exact behavior is UA-dependent, but user agents must not, in response to a request to wrap semantics around some text or to insert or remove a semantic element, generate a DOM that is less conformant than the DOM prior to the request.
UAs should offer a way for the user to move images and other non-editable parts around the content within an editing host. This may be done using the drag and drop mechanism. User agents must not, in response to a request to move non-editable elements nested inside editing hosts, generate a DOM that is less conformant than the DOM prior to the request.
When an editable form control is edited, the
changes must be reflected in both its current value and its
default value. For input elements this means updating the
defaultValue DOM attribute as
well as the value DOM attribute; for
select elements it means updating the option
elements' defaultSelected
DOM attribute as well as the selected DOM attribute; for
textarea elements this means updating the defaultValue DOM attribute as
well as the value DOM attribute.
(Updating the default* DOM attributes causes
content attributes to be updated as well.)
User agents may perform several commands per user request; for example if the user selects a block of text and hits Enter, the UA might interpret that as a request to delete the content of the selection followed by a request to break the paragraph at that position.
Documents have a designMode, which can be
either enabled or disabled.
The designMode DOM attribute on the
Document object takes two values, "on"
and "off". When it is set, the new value must be
case-insensitively compared to these two
values. If it matches the "on" value, then designMode
must be enabled, and if it matches the "off" value,
then designMode must be disabled. Other values
must be ignored.
When designMode is enabled, the DOM attribute
must return the value "on", and when it is disabled,
it must return the value "off".
The last state set must persist until the document is destroyed or the
state is changed. Initially, documents must have their designMode
disabled.
Enabling designMode causes scripts in general to be
disabled and the document to become editable.
This section defines an event-based drag-and-drop mechanism.
This specification does not define exactly what a drag-and-drop operation actually is.
On a visual medium with a pointing device, a drag operation could be the
default action of a mousedown event
that is followed by a series of mousemove events, and the drop could be
triggered by the mouse being released.
On media without a pointing device, the user would probably have to explicitly indicate his intention to perform a drag-and-drop operation, stating what he wishes to drag and what he wishes to drop, respectively.
However it is implemented, drag-and-drop operations must have a starting point (e.g. where the mouse was clicked, or the start of the selection or element that was selected for the drag), may have any number of intermediate steps (elements that the mouse moves over during a drag, or elements that the user picks as possible drop points as he cycles through possibilities), and must either have an end point (the element above which the mouse button was released, or the element that was finally selected), or be canceled. The end point must be the last element selected as a possible drop point before the drop occurs (so if the operation is not canceled, there must be at least one element in the middle step).
This section is non-normative.
It's also currently non-existent.
DragEvent and DataTransfer interfacesThe drag-and-drop processing model involves several events. They all use
the DragEvent interface.
interface DragEvent : UIEvent {
readonly attribute DataTransfer dataTransfer;
void initDragEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in AbstractView viewArg, in long detailArg, in DataTransfer dataTransferArg);
void initDragEventNS(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in AbstractView viewArg, in long detailArg, in DataTransfer dataTransferArg);
};
We should have modifier key information in here too (shift/ctrl, etc), like with mouse events and like with the context menu event.
The initDragEvent() and
initDragEventNS()
methods must initialise the event in a manner analogous to the
similarly-named methods in the DOM3 Events interfaces. [DOM3EVENTS]
The dataTransfer attribute
of the DragEvent interface
represents the context information for the event.
interface DataTransfer {
attribute DOMString dropEffect;
attribute DOMString effectAllowed;
readonly attribute DOMStringList types;
void clearData(in DOMString format);
void setData(in DOMString format, in DOMString data);
DOMString getData(in DOMString format);
void setDragImage(in Element image, in long x, in long y);
void addElement(in Element element);
};
DataTransfer objects can
conceptually contain various kinds of data.
When a DataTransfer object is
created, it must be initialized as follows:
DataTransfer object must
initially contain no data, no elements, and have no associated image.
DataTransfer object's
effectAllowed attribute must be set to
"uninitialized".
dropEffect attribute must be set to "none".
The dropEffect attribute
controls the drag-and-drop feedback that the user is given during a
drag-and-drop operation.
The attribute must ignore any attempts to set it to a value other than
none, copy, link, and move. On getting, the
attribute must return the last of those four values that it was set to.
The effectAllowed
attribute is used in the drag-and-drop processing model to initialise the
dropEffect attribute during the dragenter and dragover events.
The attribute must ignore any attempts to set it to a value other than
none, copy, copyLink, copyMove, link, linkMove, move, all, and uninitialized. On getting, the attribute must return the
last of those values that it was set to.
DataTransfer objects can hold
pieces of data, each associated with a unique format. Formats are
generally given by MIME types, with some values special-cased for legacy
reasons.
The clearData(format) method must clear the DataTransfer object of any data
associated with the given format. If format is the value "Text", then it
must be treated as "text/plain". If the format is "URL", then it must be
treated as "text/uri-list".
The setData(format, data) method must
add data to the data stored in the DataTransfer object, labeled as being of
the type format. This must replace any previous data
that had been set for that format. If format is the
value "Text", then it must be treated as "text/plain". If the format is "URL", then it must be treated as "text/uri-list".
The getData(format) method must return the data that is
associated with the type format, if any, and must
return the empty string otherwise. If format is the
value "Text", then it must be treated as "text/plain". If the format is "URL", then the data associated with the "text/uri-list" format must be parsed as appropriate for
text/uri-list data, and the first URI from the list
must be returned. If there is no data with that format, or if there is but
it has no URIs, then the method must return the empty string. [RFC2483]
The types
attribute must return a live DOMStringList that contains the
list of formats that are stored in the DataTransfer object.
The setDragImage(element, x, y) method sets which element to use to generate the drag feedback. The element argument can be any Element; if it is
an img element, then the user agent should
use the element's image (at its intrinsic size) to generate the feedback,
otherwise the user agent should base the feedback on the given element
(but the exact mechanism for doing so is not specified).
The addElement(element) method is an alternative way of
specifying how the user agent is to render
the drag feedback. It adds an element to the DataTransfer object.
The following events are involved in the drag-and-drop model. Whenever
the processing model described below causes one of these events to be
fired, the event fired must use the DragEvent interface defined above, must have
the bubbling and cancelable behaviors given in the table below, and must
have the context information set up as described after the table, with the
view attribute set to the view with
which the user interacted to trigger the drag-and-drop event, and the
detail attribute set to zero.
| Event Name | Target | Bubbles? | Cancelable? | dataTransfer
| effectAllowed
| dropEffect
| Default Action |
|---|---|---|---|---|---|---|---|
dragstart
| Source node | ✓ Bubbles | ✓ Cancelable | Contains source node unless a selection is being dragged, in which case it is empty | uninitialized
| none
| Initiate the drag-and-drop operation |
drag
| Source node | ✓ Bubbles | ✓ Cancelable | Empty | Same as last event | none
| Continue the drag-and-drop operation |
dragenter
| Immediate user selection or the body element | ✓ Bubbles | ✓ Cancelable | Empty | Same as last event | Based on
effectAllowed value
| Reject immediate user selection as potential target element |
dragleave
| Previous target element | ✓ Bubbles | — | Empty | Same as last event | none
| None |
dragover
| Current target element | ✓ Bubbles | ✓ Cancelable | Empty | Same as last event | Based on
effectAllowed value
| Reset the current drag operation to "none" |
drop
| Current target element | ✓ Bubbles | ✓ Cancelable | getData() returns data set in dragstart event
| Same as last event | Current drag operation | Varies |
dragend
| Source node | ✓ Bubbles | — | Empty | Same as last event | Current drag operation | Varies |
The dataTransfer object's contents are empty
except for dragstart events and drop events, for which the
contents are set as described in the processing model, below.
The effectAllowed attribute must be set to
"uninitialized" for dragstart events, and to whatever value the
field had after the last drag-and-drop event was fired for all other
events (only counting events fired by the user agent for the purposes of
the drag-and-drop model described below).
The dropEffect attribute must be set to "none" for dragstart, drag, and dragleave events (except when stated
otherwise in the algorithms given in the sections below), to the value
corresponding to the current drag operation for
drop and dragend events, and to a
value based on the effectAllowed attribute's value and to
the drag-and-drop source, as given by the following table, for the
remaining events (dragenter and dragover):
effectAllowed
| dropEffect
|
|---|---|
none
| none
|
copy, copyLink, copyMove, all
| copy
|
link, linkMove
| link
|
move
| move
|
uninitialized when what is being dragged is a
selection from a text field
| move
|
uninitialized when what is being dragged is a
selection
| copy
|
uninitialized when what is being dragged is an
a element with an href
attribute
| link
|
| Any other case | copy
|
When the user attempts to begin a drag operation, the user agent must
first determine what is being dragged. If the drag operation was invoked
on a selection, then it is the selection that is being dragged. Otherwise,
it is the first element, going up the ancestor chain, starting at the node
that the user tried to drag, that has the DOM attribute draggable set to
true. If there is no such element, then nothing is being dragged, the
drag-and-drop operation is never started, and the user agent must not
continue with this algorithm.
img elements and a elements with an href attribute have their draggable attribute
set to true by default.
If the user agent determines that something can be dragged, a dragstart event must
then be fired.
If it is a selection that is being dragged, then this event must be fired on the node that the user started the drag on (typically the text node that the user originally clicked). If the user did not specify a particular node, for example if the user just told the user agent to begin a drag of "the selection", then the event must be fired on the deepest node that is a common ancestor of all parts of the selection.
We should look into how browsers do other types (e.g. Firefox apparently also adds text/html for internal drag and drop of a selection).
If it is not a selection that is being dragged, then the event must be fired on the element that is being dragged.
The node on which the event is fired is the source node. Multiple events are fired on this node during the course of the drag-and-drop operation.
If it is a selection that is being dragged, the dataTransfer member of the event must be
created with no nodes. Otherwise, it must be created containing just the
source node. Script can use the addElement() method to add further elements
to the list of what is being dragged.
If it is a selection that is being dragged, the dataTransfer member of the event must have
the text of the selection added to it as the data associated with the
text/plain format. Otherwise, if it is an img element being dragged, then the value of the
element's src DOM
attribute must be added, associated with the text/uri-list format. Otherwise, if it is an a element being dragged, then the value of the
element's href DOM
attribute must be added, associated with the text/uri-list format. Otherwise, no data is added to the
object by the user agent.
If the event is canceled, then the drag-and-drop operation must not occur; the user agent must not continue with this algorithm.
If it is not canceled, then the drag-and-drop operation must be initiated.
Since events with no event handlers registered are, almost by definition, never canceled, drag-and-drop is always available to the user if the author does not specifically prevent it.
The drag-and-drop feedback must be generated from the first of the following sources that is available:
setDragImage() method of the dataTransfer object of the dragstart event, if
the method was called. In visual media, if this is used, the x and y arguments that were passed to
that method should be used as hints for where to put the cursor relative
to the resulting image. The values are expressed as distances in CSS
pixels from the left side and from the top side of the image
respectively. [CSS21]dataTransfer object, both before the
event was fired, and during the handling of the event using the addElement() method, if any such elements
were indeed added.
The user agent must take a note of the data that was placed in the dataTransfer object. This data will be
made available again when the drop event is fired.
From this point until the end of the drag-and-drop operation, device input events (e.g. mouse and keyboard events) must be suppressed. In addition, the user agent must track all DOM changes made during the drag-and-drop operation, and add them to its undo history as one atomic operation once the drag-and-drop operation has ended.
During the drag operation, the element directly indicated by the user as the drop target is called the immediate user selection. (Only elements can be selected by the user; other nodes must not be made available as drop targets.) However, the immediate user selection is not necessarily the current target element, which is the element currently selected for the drop part of the drag-and-drop operation. The immediate user selection changes as the user selects different elements (either by pointing at them with a pointing device, or by selecting them in some other way). The current target element changes when the immediate user selection changes, based on the results of event handlers in the document, as described below.
Both the current target element and the immediate user selection can be null, which means no target element is selected. They can also both be elements in other (DOM-based) documents, or other (non-Web) programs altogether. (For example, a user could drag text to a word-processor.) The current target element is initially null.
In addition, there is also a current drag operation, which can take on the values "none", "copy", "link", and "move". Initially it has the value "none". It is updated by the user agent as described in the steps below.
User agents must, every 350ms (±200ms), perform the following steps in sequence. (If the user agent is still performing the previous iteration of the sequence when the next iteration becomes due, the user agent must not execute the overdue iteration, effectively "skipping missed frames" of the drag-and-drop operation.)
First, the user agent must fire a drag event at the source
node. If this event is canceled, the user agent must set the current drag operation to none (no drag operation).
Next, if the drag
event was not canceled and the user has not ended the drag-and-drop
operation, the user agent must check the state of the drag-and-drop
operation, as follows:
First, if the user is indicating a different immediate user selection than during the last iteration (or if this is the first iteration), and if this immediate user selection is not the same as the current target element, then the current target element must be updated, as follows:
If the new immediate user selection is null, or is in a non-DOM document or application, then set the current target element to the same value.
Otherwise, the user agent must fire a dragenter
event at the immediate user selection.
If the event is canceled, then the current target element must be set to the immediate user selection.
Otherwise, if the current target element
is not the body element, the user agent
must fire a dragenter event at the body element, and the current target element must be set to the body element, regardless of whether that
event was canceled or not. (If the body
element is null, then the current target
element would be set to null too in this case, it wouldn't be
set to the Document object.)
If the previous step caused the current target
element to change, and if the previous target element was not null
or a part of a non-DOM document, the user agent must fire a dragleave event
at the previous target element.
If the current target element is a DOM
element, the user agent must fire a dragover event at this current target element.
If the dragover event is not canceled, the current drag operation must be reset to "none".
Otherwise, the current drag operation must
be set based on the values the effectAllowed and dropEffect attributes of the dataTransfer object had after the
event was handled, as per the following table:
effectAllowed
| dropEffect
| Drag operation |
|---|---|---|
uninitialized, copy,
copyLink, copyMove, or
all
| copy
| "copy" |
uninitialized, link,
copyLink, linkMove, or
all
| link
| "link" |
uninitialized, move,
copyMove, linkMove, or
all
| move
| "move" |
| Any other case | "none" | |
Then, regardless of whether the dragover event was canceled or not, the
drag feedback (e.g. the mouse cursor) must be updated to match the current drag operation, as follows:
| Drag operation | Feedback |
|---|---|
| "copy" | Data will be copied if dropped here. |
| "link" | Data will be linked if dropped here. |
| "move" | Data will be moved if dropped here. |
| "none" | No operation allowed, dropping here will cancel the drag-and-drop operation. |
Otherwise, if the current target element is not a DOM element, the user agent must use platform-specific mechanisms to determine what drag operation is being performed (none, copy, link, or move). This sets the current drag operation.
Otherwise, if the user ended the drag-and-drop operation (e.g. by
releasing the mouse button in a mouse-driven drag-and-drop interface),
or if the drag event
was canceled, then this will be the last iteration. The user agent must
execute the following steps, then stop looping.
If the current drag operation is none (no
drag operation), or, if the user ended the drag-and-drop operation by
canceling it (e.g. by hitting the Escape key), or if the current target element is null, then the drag
operation failed. If the current target
element is a DOM element, the user agent must fire a dragleave event
at it; otherwise, if it is not null, it must use platform-specific
conventions for drag cancellation.
Otherwise, the drag operation was as success. If the current target element is a DOM element, the user
agent must fire a drop event at it; otherwise, it must use
platform-specific conventions for indicating a drop.
When the target is a DOM element, the dropEffect attribute of the event's
dataTransfer object must be given the
value representing the current drag operation
(copy, link, or move), and the object must be set up so that the getData()
method will return the data that was added during the dragstart event.
If the event is canceled, the current drag
operation must be set to the value of the dropEffect attribute of the event's
dataTransfer object as it stood after
the event was handled.
Otherwise, the event is not canceled, and the user agent must perform the event's default action, which depends on the exact target as follows:
textarea, or an input element
with type="text")
text/plain format, if any, into the text field in a
manner consistent with platform-specific conventions (e.g. inserting
it at the current mouse cursor position, or inserting it at the end
of the field).
Finally, the user agent must fire a dragend event at the source node, with the dropEffect attribute of the event's
dataTransfer object being set to the
value corresponding to the current drag
operation.
The current drag operation can
change during the processing of the drop event, if one was fired.
The event is not cancelable. After the event has been handled, the user agent must act as follows:
textarea, or an input element
with type="text"), and a drop event was fired in
the previous step, and the current drag
operation is "move", and the source of the drag-and-drop
operation is a selection in the DOM
textarea, or an input element
with type="text"), and a drop event was fired in
the previous step, and the current drag
operation is "move", and the source of the drag-and-drop
operation is a selection in a text field
The model described above is independent of which Document
object the nodes involved are from; the events must be fired as described
above and the rest of the processing model must be followed as described
above, irrespective of how many documents are involved in the operation.
If the drag is initiated in another application, the source node is not a DOM node, and the user agent must
use platform-specific conventions instead when the requirements above
involve the source node. User agents in this situation must act as if the
dragged data had been added to the DataTransfer object when the drag
started, even though no dragstart event was actually fired; user
agents must similarly use platform-specific conventions when deciding on
what drag feedback to use.
If a drag is started in a document but ends in another application, then the user agent must instead replace the parts of the processing model relating to handling the target according to platform-specific conventions.
In any case, scripts running in the context of the document must not be able to distinguish the case of a drag-and-drop operation being started or ended in another application from the case of a drag-and-drop operation being started or ended in another document from another domain.
draggable attributeAll elements may have the draggable content attribute set. The draggable attribute
is an enumerated attribute. It has three states.
The first state is true and it has the keyword true. The second state is false and it has the
keyword false. The third state is auto; it
has no keywords but it is the missing value default.
The draggable
DOM attribute, whose value depends on the content attribute's in the way
described below, controls whether or not the element is draggable.
Generally, only text selections are draggable, but elements whose draggable DOM
attribute is true become draggable as well.
If an element's draggable content attribute has the state
true, the draggable DOM attribute must return true.
Otherwise, if the element's draggable content attribute has the state
false, the draggable DOM attribute must return false.
Otherwise, the element's draggable content attribute has the state
auto. If the element is an img
element, or, if the element is an a element
with an href
content attribute, the draggable DOM attribute must return true.
Otherwise, the draggable DOM must return false.
If the draggable DOM attribute is set to the value
false, the draggable content attribute must be set to
the literal value false. If the draggable DOM
attribute is set to the value true, the draggable content attribute must be set to
the literal value true.
Copy-and-paste is a form of drag-and-drop: the "copy" part is equivalent to dragging content to another application (the "clipboard"), and the "paste" part is equivalent to dragging content from another application.
Select-and-paste (a model used by mouse operations in the X Window System) is equivalent to a drag-and-drop operation where the source is the selection.
When the user invokes a copy operation, the user agent must act as if the user had invoked a drag on the current selection. If the drag-and-drop operation initiates, then the user agent must act as if the user had indicated (as the immediate user selection) a hypothetical application representing the clipboard. Then, the user agent must act as if the user had ended the drag-and-drop operation without canceling it. If the drag-and-drop operation didn't get canceled, the user agent should then follow the relevant platform-specific conventions for copy operations (e.g. updating the clipboard).
When the user invokes a cut operation, the user agent must act as if the user had invoked a copy operation (see the previous section), followed, if the copy was completed successfully, by a selection delete operation.
When the user invokes a clipboard paste operation, the user agent must act as if the user had invoked a drag on a hypothetical application representing the clipboard, setting the data associated with the drag as the content on the clipboard (in whatever formats are available).
Then, the user agent must act as if the user had indicated (as the immediate user selection) the element with the keyboard focus, and then ended the drag-and-drop operation without canceling it.
When the user invokes a selection paste operation, the user agent must act as if the user had invoked a drag on the current selection, then indicated (as the immediate user selection) the element with the keyboard focus, and then ended the drag-and-drop operation without canceling it.
User agents must not make the data added to the DataTransfer object during the dragstart event
available to scripts until the drop event, because otherwise, if a user were to
drag sensitive information from one document to a second document,
crossing a hostile third document in the process, the hostile document
could intercept the data.
For the same reason, user agents must consider a drop to be successful
only if the user specifically ended the drag operation — if any
scripts end the drag operation, it must be considered unsuccessful
(canceled) and the drop
event must not be fired.
User agents should take care to not start drag-and-drop operations in response to script actions. For example, in a mouse-and-window environment, if a script moves a window while the user has his mouse button depressed, the UA would not consider that to start a drag. This is important because otherwise UAs could cause data to be dragged from sensitive sources and dropped into hostile documents without the user's consent.
There has got to be a better way of doing this, surely.
The user agent must associate an undo
transaction history with each HTMLDocument object.
The undo transaction history is a list of entries. The entries are of two type: DOM changes and undo objects.
Each DOM changes entry in the undo transaction history consists of batches of one or more of the following:
Element node.
Node.HTMLDocument object
(parentNode, childNodes).
Undo object entries consist of objects representing state that scripts running in the document are managing. For example, a Web mail application could use an undo object to keep track of the fact that a user has moved an e-mail to a particular folder, so that the user can undo the action and have the e-mail return to its former location.
Broadly speaking, DOM changes entries are handled by the UA in response to user edits of form controls and editing hosts on the page, and undo object entries are handled by script in response to higher-level user actions (such as interactions with server-side state, or in the implementation of a drawing tool).
UndoManager interfaceThis API sucks. Seriously. It's a terrible API. Really bad. I hate it. Here are the requirements:
To manage undo object entries in the undo transaction history, the UndoManager interface can be used:
interface UndoManager {
unsigned long add(in DOMObject data, in DOMString title);
[XXX] void remove(in unsigned long index);
void clearUndo();
void clearRedo();
[IndexGetter] DOMObject item(in unsigned long index);
readonly attribute unsigned long length;
readonly attribute unsigned long position;
};
The undoManager attribute of the
Window interface must return the object
implementing the UndoManager
interface for that Window object's
associated HTMLDocument object.
UndoManager objects represent
their document's undo transaction history.
Only undo object entries are visible with this
API, but this does not mean that DOM changes
entries are absent from the undo transaction
history.
The length attribute must
return the number of undo object entries in the
undo transaction history.
The item(n) method must return the nth undo object entry in the undo transaction history.
The undo transaction history has a current position. This is the position between two entries in the undo transaction history's list where the previous entry represents what needs to happen if the user invokes the "undo" command (the "undo" side, lower numbers), and the next entry represents what needs to happen if the user invokes the "redo" command (the "redo" side, higher numbers).
The position attribute must
return the index of the undo object entry
nearest to the undo position, on the "redo" side.
If there are no undo object entries on the
"redo" side, then the attribute must return the same as the length
attribute. If there are no undo object entries
on the "undo" side of the undo position, the position
attribute returns zero.
Since the undo transaction
history contains both undo object entries
and DOM changes entries, but the position
attribute only returns indices relative to undo
object entries, it is possible for several "undo" or "redo" actions to
be performed without the value of the position
attribute changing.
The add(data, title) method's
behavior depends on the current state. Normally, it must insert the data object passed as an argument into the undo transaction history immediately before
the undo position, optionally remembering the
given title to use in the UI. If the method is called
during an undo operation,
however, the object must instead be added immediately after the
undo position.
If the method is called and there is neither an undo operation in progress nor a redo operation in progress then
any entries in the undo transaction
history after the undo position must be
removed (as if clearRedo() had been called).
We could fire events when someone adds something to the undo history -- one event per undo object entry before the position (or after, during redo addition), allowing the script to decide if that entry should remain or not. Or something. Would make it potentially easier to expire server-held state when the server limitations come into play.
The remove(index) method must remove the undo object entry with the specified index. If the index is less than zero or greater than or
equal to length then the method must raise an
INDEX_SIZE_ERR exception. DOM
changes entries are unaffected by this method.
The clearUndo() method must
remove all entries in the undo transaction
history before the undo position, be they DOM changes entries or undo
object entries.
The clearRedo() method must
remove all entries in the undo transaction
history after the undo position, be they DOM changes entries or undo
object entries.
Another idea is to have a way for scripts to say "startBatchingDOMChangesForUndo()" and after that the changes to the DOM go in as if the user had done them.
When the user invokes an undo operation, or when the execCommand() method is called with the
undo command, the
user agent must perform an undo operation.
If the undo position is at the start of the undo transaction history, then the user agent must do nothing.
If the entry immediately before the undo position is a DOM changes entry, then the user agent must remove that DOM changes entry, reverse the DOM changes that were listed in that entry, and, if the changes were reversed with no problems, add a new DOM changes entry (consisting of the opposite of those DOM changes) to the undo transaction history on the other side of the undo position.
If the DOM changes cannot be undone (e.g. because the DOM state is no longer consistent with the changes represented in the entry), then the user agent must simply remove the DOM changes entry, without doing anything else.
If the entry immediately before the undo
position is an undo object entry, then the
user agent must first remove that undo object
entry from the undo transaction history,
and then must fire an undo event on the Document object,
using the undo object entry's associated undo
object as the event's data.
Any calls to add() while the event is being handled will be
used to populate the redo history, and will then be used if the user
invokes the "redo" command to undo his undo.
When the user invokes a redo operation, or when the execCommand() method is called with the
redo command, the
user agent must perform a redo operation.
This is mostly the opposite of an undo operation, but the full definition is included here for completeness.
If the undo position is at the end of the undo transaction history, then the user agent must do nothing.
If the entry immediately after the undo position is a DOM changes entry, then the user agent must remove that DOM changes entry, reverse the DOM changes that were listed in that entry, and, if the changes were reversed with no problems, add a new DOM changes entry (consisting of the opposite of those DOM changes) to the undo transaction history on the other side of the undo position.
If the DOM changes cannot be redone (e.g. because the DOM state is no longer consistent with the changes represented in the entry), then the user agent must simply remove the DOM changes entry, without doing anything else.
If the entry immediately after the undo position
is an undo object entry, then the user agent
must first remove that undo object entry from
the undo transaction history, and then
must fire a redo event
on the Document object, using the undo
object entry's associated undo object as the event's data.
UndoManagerEvent interface and the
undo and redo eventsinterface UndoManagerEvent : Event {
readonly attribute DOMObject data;
void initUndoManagerEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMObject dataArg);
void initUndoManagerEventNS(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMObject dataArg);
};
The initUndoManagerEvent()
and initUndoManagerEventNS()
methods must initialise the event in a manner analogous to the
similarly-named methods in the DOM3 Events interfaces. [DOM3EVENTS]
The data attribute
represents the undo object for the event.
The undo and redo events do not bubble,
cannot be canceled, and have no default action. When the user agent fires
one of these events it must use the UndoManagerEvent interface, with the
data
field containing the relevant undo object.
How user agents present the above conceptual model to the user is not defined. The undo interface could be a filtered view of the undo transaction history, it could manipulate the undo transaction history in ways not described above, and so forth. For example, it is possible to design a UA that appears to have separate undo transaction histories for each form control; similarly, it is possible to design systems where the user has access to more undo information than is present in the official (as described above) undo transaction history (such as providing a tree-based approach to document state). Such UI models should be based upon the single undo transaction history described in this section, however, such that to a script there is no detectable difference.
Every browsing context has a selection. The selection can be empty, and the selection can 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.
User agents may selectively ignore attempts to use the API to adjust the selection made after the user has modified the selection. For example, if the user has just selected part of a word, the user agent could ignore attempts to use the API call to immediately unselect the selection altogether, but could allow attempts to change the selection to select the entire word.
User agents may also allow the user to create selections that are not exposed to the API.
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.
[Stringifies] 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();
};
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 stringification 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).
Objects implementing this interface must stringify to 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 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.
The execCommand(commandId, showUI, value) method on the HTMLDocument interface allows scripts to
perform actions on the current selection or at the current caret position.
Generally, these commands would be used to implement editor UI, for
example having a "delete" button on a toolbar.
There are three variants to this method, with one, two, and three arguments respectively. The showUI and value parameters, even if specified, are ignored unless otherwise stated.
When execCommand() is invoked, the user agent
must follow the following steps:
A document is ready for editing host commands if it has a selection that is entirely within an editing host, or if it has no selection but its caret is inside an editing host.
The queryCommandEnabled(commandId) method, when invoked, must return
true if the condition listed below under "Enabled When" for the given commandId is true, and false otherwise.
The queryCommandIndeterm(commandId) method, when invoked, must return
true if the condition listed below under "Indeterminate When" for the
given commandId is true, and false otherwise.
The queryCommandState(commandId) method, when invoked, must return
the value expressed below under "State" for the given commandId.
The queryCommandSupported(commandId) method, when invoked, must return
true if the given commandId is in the list below, and
false otherwise.
The queryCommandValue(commandId) method, when invoked, must return
the value expressed below under "Value" for the given commandId.
The possible values for commandId, and their corresponding meanings, are as follows. These values are case-insensitive.
bold
b element (or, again, unwrapped, or have that
semantic inserted or removed, as defined by the UA).
b element. False otherwise.
true" if the
expression given for the "State" above is true, the string "false" otherwise.
createLink
a element (or, again, unwrapped, or have that
semantic inserted or removed, as defined by the UA). If the user agent
creates an a element or modifies an
existing a element, then if the showUI argument is present and has the value false, then
the value of the value argument must be used as the
URI of the link. Otherwise, the user should be prompted for the URI of
the link.
false".
delete
false".
formatBlock
Action: The user agent must run the following steps:
If the value argument wasn't specified, abort these steps without doing anything.
If the value argument has a leading U+003C LESS-THAN SIGN character ('<') and a trailing U+003E GREATER-THAN SIGN character ('>'), then remove the first and last characters from value.
If value is (now) a case-insensitive
match for the tag name of an element defined by this specification
that is defined to be a prose element but not a
phrasing element, then, for every position in the
selection, take the furthest flow content
ancestor element of that position that contains only phrasing content, and, if that element is editable, and has a content model that allows it
to contain prose content other than phrasing content, and has a parent element whose
content model allows that parent to contain any prose
content, rename the element (as if the Element.renameNode() method had been used) to value, using the HTML namespace.
If there is no selection, then, where in the description above refers to the selection, the user agent must act as if the selection was an empty range (with just one position) at the caret position.
false".
forwardDelete
false".
insertImage
img element (or, again, unwrapped, or have
that semantic inserted or removed, as defined by the UA). If the user
agent creates an img element or modifies
an existing img element, then if the showUI argument is present and has the value false, then
the value of the value argument must be used as the
URI of the image. Otherwise, the user should be prompted for the URI of
the image.
false".
insertHTML
Action: The user agent must run the following steps:
If the value argument wasn't specified, abort these steps without doing anything.
If there is a selection, act as if the user had requested that the selection be deleted.
Invoke the HTML fragment parsing
algorithm with an arbitrary orphan body element as the context element and with the value argument as input.
Insert the nodes returned by the previous step into the document at the location of the caret.
false".
insertLineBreak
false".
insertOrderedList
ol
element (or unwrapped, or, if there is no selection, have that semantic
inserted or removed — the exact behavior is UA-defined).
false".
insertOrderedList
ul
element (or unwrapped, or, if there is no selection, have that semantic
inserted or removed — the exact behavior is UA-defined).
false".
insertParagraph
false".
insertText
false".
italic
i element (or, again, unwrapped, or have that
semantic inserted or removed, as defined by the UA).
i element. False otherwise.
true" if the
expression given for the "State" above is true, the string "false" otherwise.
redo
false".
selectAll
false".
subscript
sub element (or, again, unwrapped, or have
that semantic inserted or removed, as defined by the UA).
sub element. False otherwise.
true" if the
expression given for the "State" above is true, the string "false" otherwise.
superscript
sup
element (or unwrapped, or, if there is no selection, have that semantic
inserted or removed — the exact behavior is UA-defined).
sup element. False otherwise.
true" if the
expression given for the "State" above is true, the string "false" otherwise.
undo
false".
unlink
a elements that have href attributes and that are partially or
completely included in the current selection.
false".
unselect
false".
vendorID-customCommandID
vendorID-customCommandID so as to prevent clashes between
extensions from different vendors and future additions to this
specification.
false".