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.
hidden
attributeAll elements may have the hidden
content attribute set. The hidden
attribute is a boolean attribute. When specified on an
element, it indicates that the element is not yet, or is no longer,
relevant. User agents should not render elements that have the hidden
attribute specified.
In the following skeletal example, the attribute is used to hide the Web game's main screen until the user logs in:
<h1>The Example Game</h1> <section id="login"> <h2>Login</h2> <form> ... <!-- calls login() once the user's credentials have been checked --> </form> <script> function login() { // switch screens document.getElementById('login').hidden = true; document.getElementById('game').hidden = false; } </script> </section> <section id="game" hidden> ... </section>
The hidden
attribute must not be
used to hide content that could legitimately be shown in another
presentation. For example, it is incorrect to use hidden
to hide panels in a tabbed dialog,
because the tabbed interface is merely a kind of overflow
presentation — showing all the form controls in one big page
with a scrollbar would be equivalent, and no less correct.
Elements in a section hidden by the hidden
attribute are still active,
e.g. scripts and form controls in such sections still render execute
and submit respectively. Only their presentation to the user
changes.
The hidden
DOM
attribute must reflect the content attribute of the
same name.
Each element has a click in progress flag, initially set to false.
The click() method must run these steps:
If the element's click in progress flag is set to true, then abort these steps.
Set the click in progress flag on the element to true.
If the element has a defined activation behavior,
run synthetic click activation steps on the
element. Otherwise, fire a click
event at
the element.
Set the click in progress flag on the element to false.
The scrollIntoView([top])
method, when called, must cause
the element on which the method was called to have the attention of
the user called to it.
In a speech browser, this could happen by having the current playback position move to the start of the given element.
In visual user agents, if the argument is present and has the value false, the user agent should scroll the element into view such that both the bottom and the top of the element are in the viewport, with the bottom of the element aligned with the bottom of the viewport. If it isn't possible to show the entire element in that way, or if the argument is omitted or is true, then the user agent should instead align the top of the element with the top of the viewport. If the entire scrollable part of the content is visible all at once (e.g. if a page is shorter than the viewport), then the user agent should not scroll anything. Visual user agents should further scroll horizontally as necessary to bring the element to the attention of the user.
Non-visual user agents may ignore the argument, or may treat it in some media-specific manner most useful to the user.
When an element is focused, key events received by the document must be targeted at that element. There may be no element focused; when no element is focused, key events received by the document must be targetted at the body element.
User agents may track focus for each browsing
context or Document
individually, or may support
only one focused elment per top-level browsing context
— user agents should follow platform conventions in this
regard.
Which elements within a top-level browsing context currently have focus must be independent of whether or not the top-level browsing context itself has the system focus.
When an element is focused, the element matches the
CSS :focus
pseudo-class.
The tabindex
content attribute specifies whether the element is focusable,
whether it can be reached using sequential focus navigation, and the
relative order of the element for the purposes of sequential focus
navigation. The name "tab index" comes from the common use of the
"tab" key to navigate through the focusable elements. The term
"tabbing" refers to moving forward through the focusable elements
that can be reached using sequential focus navigation.
The tabindex
attribute, if
specified, must have a value that is a valid
integer.
If the attribute is specified, it must be parsed using the rules for parsing integers. The attribute's values have the following meanings:
The user agent should follow platform conventions to determine if the element is to be focusable and, if so, whether the element can be reached using sequential focus navigation, and if so, what its relative order should be.
The user agent must allow the element to be focused, but should not allow the element to be reached using sequential focus navigation.
The user agent must allow the element to be focused, should allow the element to be reached using sequential focus navigation, and should follow platform conventions to determine the element's relative order.
The user agent must allow the element to be focused, should allow the element to be reached using sequential focus navigation, and should place the element in the sequential focus navigation order so that it is:
tabindex
attribute has been
omitted or whose value, when parsed, returns an error,tabindex
attribute has a value equal
to or less than zero,tabindex
attribute has a value
greater than zero but less than the value of the tabindex
attribute on the
element,tabindex
attribute has a value equal
to the value of the tabindex
attribute on the element but that is earlier in the document in
tree order than the element,tabindex
attribute has a value equal
to the value of the tabindex
attribute on the element but that is later in the document in
tree order than the element, andtabindex
attribute has a value
greater than the value of the tabindex
attribute on the
element.An element is focusable if the tabindex
attribute's definition above
defines the element to be focusable and the element is
being rendered.
An element that is focusable but does not otherwise have an activation behavior defined has an activation behavior that does nothing.
This means that an element that is only focusable
because of its tabindex
attribute
will fire a click
event in response
to a non-mouse activation (e.g. hitting the "enter" key while the
element is focused).
The tabIndex
DOM
attribute must reflect the value of the tabindex
content attribute. If the
attribute is not present, or parsing its value returns an error,
then the DOM attribute must return 0 for elements that are focusable
and −1 for elements that are not focusable.
The focusing steps are as follows:
If focusing the element will remove the focus from another element, then run the unfocusing steps for that element.
Make the element the currently focused element in its top-level browsing context.
Some elements, most notably area
, can correspond
to more than one distinct focusable area. If a particular area was
indicated when the element was focused, then that is the area that
must get focus; otherwise, e.g. when using the focus()
method, the first such region in
tree order is the one that must be focused.
Fire a simple event that doesn't bubble called
focus
at the element.
User agents must run the focusing steps for an element whenever the user moves the focus to a focusable element.
The unfocusing steps are as follows:
If the element is an input
element, and the
change
event applies to the
element, and the element does not have a defined activation
behavior, and the user has changed the element's value or its list of selected files
while the control was focused without committing that change, then
fire a simple event called change
at the element, then
broadcast formchange
events at the element's form owner.
Unfocus the element.
Fire a simple event that doesn't bubble called
blur
at the element.
User agents should run the unfocusing steps for an element whenever the user moves the focus away from any focusable element.
The activeElement
attribute on DocumentHTML
objects must return the
element in the document that is focused. If no element in the
Document
is focused, this must return the body
element.
The hasFocus()
method
on DocumentHTML
objects must return true if the
document's browsing context is focused, and all its
ancestor browsing
contexts are also focused, and the top-level browsing
context has the system focus.
The focus()
method on the Window
object, when invoked, provides a
hint to the user agent that the script believes the user might be
interested in the contents of the browsing context of
the Window
object on which the method was invoked.
User agents are encouraged to have this focus()
method trigger some kind of
notification.
The blur()
method
on the Window
object, when invoked, provides a hint to
the user agent that the script believes the user probably is not
currently interested in the contents of the browsing
context of the Window
object on which the method
was invoked, but that the contents might become interesting again in
the future.
User agents are encouraged to ignore calls to this blur()
method entirely.
Historically the focus()
and blur()
methods actually affected the
system focus, but hostile sites widely abuse this behavior to the
user's detriment.
The focus()
method,
when invoked, must run the following algorithm:
If the element is marked as locked for focus, then abort these steps.
If the element is not focusable, then abort these steps.
Mark the element as locked for focus.
If the element is not already focused, run the focusing steps for the element.
Unmark the element as locked for focus.
The blur()
method, when
invoked, should run the unfocusing steps for the
element. User agents may selectively or uniformly ignore calls to
this method for usability reasons.
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 agent should allow the user 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 Document
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);
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.
contenteditable
attributeThe 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 an ASCII
case-insensitive match for the string "inherit
" then the content attribute must be removed,
if the new value is an ASCII case-insensitive match for
the string "true
" then the content attribute
must be set to the string "true
", if the new
value is an ASCII case-insensitive match for 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 compared in an ASCII
case-insensitive manner 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.
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 : MouseEvent { readonly attribute DataTransfer dataTransfer; void initDragEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in AbstractView viewArg, in long detailArg, in long screenXArg, in long screenYArg, in long clientXArg, in long clientYArg, in boolean ctrlKeyArg, in boolean altKeyArg, in boolean shiftKeyArg, in boolean metaKeyArg, in unsigned short buttonArg, in EventTarget relatedTargetArg, in DataTransfer dataTransferArg); void initDragEventNS(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in AbstractView viewArg, in long detailArg, in long screenXArg, in long screenYArg, in long clientXArg, in long clientYArg, in unsigned short buttonArg, in EventTarget relatedTargetArg, in DOMString modifiersListArg, in DataTransfer dataTransferArg); };
The initDragEvent()
and initDragEventNS()
methods must initialize the event in a manner analogous to the
similarly-named methods in the DOM3 Events interfaces. [DOM3EVENTS]
The initDragEvent()
and initDragEventNS()
methods handle modifier keys differently, much like the equivalent
methods on the MouseEvent
interface.
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([Optional] 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
initialize 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. For the
purposes of this API, however, the format strings are opaque,
case-sensitive, strings, and the empty string is a
valid format string.
The clearData()
method, when called with no arguments, must clear the
DataTransfer
object of al data (for all formats).
When called with an argument, 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 URL from the list
must be returned. If there is no data with that format, or if there
is but it has no URLs, 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 difference between setDragImage()
and
addElement()
is
that the latter automatically generates the image based on the
current rendering of the elements added, whereas the former uses the
exact specified image.
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, the detail
attribute
set to zero, the mouse and key attributes set according to the state
of the input devices as they would be for user interaction events,
and the relatedTarget
attribute set to
null.
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
whose type
attribute is in
the Text state)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
whose type
attribute is in
the Text state), 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 DOMtextarea
, or an input
element
whose type
attribute is in
the Text state), 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 fieldThe 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 { readonly attribute unsigned long length; [IndexGetter] any item(in unsigned long index); readonly attribute unsigned long position; unsigned long add(in any data, in DOMString title); void remove(in unsigned long index); void clearUndo(); void clearRedo(); };
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. This is the length.
The object's indices of the supported indexed properties are the numbers in the range zero to length-1, unless the length is zero, in which case there are no supported indexed properties.
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 any data;
void initUndoManagerEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in any dataArg);
void initUndoManagerEventNS(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in any dataArg);
};
The initUndoManagerEvent()
and initUndoManagerEventNS()
methods must initialize 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.
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 must be compared to the argument in an ASCII case-insensitive manner.
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 URL of the link. Otherwise, the user agent
should prompt the user for the URL 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) an ASCII
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 URL of the image. Otherwise, the user
agent should prompt the user for the URL of the image.false
".insertHTML
Action: The user agent must run the following steps:
If the document is an XML document, then
throw an INVALID_ACCESS_ERR
exception and abort
these 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, without firing any mutation events.
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
".insertUnorderedList
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.a
element that has an href
attribute.false
".unselect
false
".vendorID-customCommandID
vendorID-customCommandID
so as to prevent clashes between extensions from different vendors
and future additions to this specification.false
".