command elementMetadata element, and strictly inline-level content.
type
label
icon
hidden
disabled
checked
radiogroup
default
title attribute has special semantics on this
element.
interface HTMLCommandElement : HTMLElement {
attribute DOMString type;
attribute DOMString label;
attribute DOMString icon;
attribute boolean hidden;
attribute boolean disabled;
attribute boolean checked;
attribute DOMString radiogroup;
attribute boolean default;
void click(); // shadows HTMLElement.click()
};
The Command
interface must also be implemented by this element.
The command element represents a
command that the user can invoke.
The type
attribute indicates the kind of command: either a normal command with an
associated action, or a state or option that can be toggled, or a
selection of one item from a list of items.
The attribute's value must be either "command",
"checkbox", or "radio",
denoting each of these three types of commands respectively. The attribute
may also be omitted if the element is to represent the first of these
types, a simple command.
The label
attribute gives the name of the command, as shown to the user.
The title
attribute gives a hint describing the command, which might be shown to the
user to help him.
The icon
attribute gives a picture that represents the command. If the attribute is
specified, the attribute's value must contain a URI (or IRI).
The hidden
attribute is a boolean attribute that, if present,
indicates that the command is not relevant and is to be hidden.
The disabled attribute is a boolean attribute that, if present, indicates that
the command is not available in the current state.
The distinction between Disabled State and Hidden State is subtle. A command should be Disabled if, in the same context, it could be enabled if only certain aspects of the situation were changed. A command should be marked as Hidden if, in that situation, the command will never be enabled. For example, in the context menu for a water faucet, the command "open" might be Disabled if the faucet is already open, but the command "eat" would be marked Hidden since the faucet could never be eaten.
The checked attribute is a boolean attribute that, if present, indicates that
the command is selected.
The radiogroup attribute
gives the name of the group of commands that will be toggled when the
command itself is toggled, for commands whose type attribute has
the value "radio". The scope of the name is the
child list of the parent element.
If the command element is used when
generating a context
menu, then the default attribute indicates,
if present, that the command is the one that would have been invoked if
the user had directly activated the menu's subject instead of using its
context menu. The default attribute is a boolean attribute.
Need an example that shows an element that, if
double-clicked, invokes an action, but that also has a context menu,
showing the various command
attributes off, and that has a default command.
The type, label, icon, hidden, disabled, checked, radiogroup, and default DOM
attributes must reflect their respective namesake
content attributes.
The click()
method's behaviour depends on the value of the type attribute of the
element, as follows:
type
attribute has the value checkbox
If the element has a checked attribute, the UA must remove that
attribute. Otherwise, the UA must add a checked
attribute, with the literal value checked. The UA
must then fire a click event
at the element.
type
attribute has the value radio
If the element has a parent, then the UA must walk the list of child
nodes of that parent element, and for each node that is a command element, if that element has a radiogroup attribute whose value exactly
matches the current element's (treating missing radiogroup attributes as if they were the
empty string), and has a checked attribute, must remove that
attribute and fire a click
event at the element.
Then, the element's checked attribute attribute must be set to
the literal value checked and a click event must be fired at
the element.
The UA must fire a click
event at the element.
Firing a synthetic click event
at the element does not cause any of the actions described above to
happen.
should change all the above so it actually is just trigged by a click event, then we could remove the shadowing click() method and rely on actual events.
Need to define the command="" attribute
command elements are not
rendered unless they form part of a menu.
menu elementBlock-level element, and structured inline-level element.
li elements, or inline-level content (but not both).
type
label
autosubmit
interface HTMLMenuElement : HTMLElement {
attribute DOMString type;
attribute DOMString label;
attribute boolean autosubmit;
};
The menu element represents a list of
commands.
The type
attribute is an enumerated attribute indicating
the kind of menu being declared. The attribute has three states. The context keyword maps to the context menu state, in which
the element is declaring a context menu. The toolbar keyword maps to the tool bar state, in which the
element is declaraing a tool bar. The attribute may also be omitted. The
missing value default is the list state, which indicates that the element is merely a list
of commands that is neither declaring a context menu nor defining a tool
bar.
If a menu element's type attribute is in the
context menu state,
then the element represents the commands of a context menu, and the user
can only interact with the commands if that context menu is activated.
If a menu element's type attribute is in the
tool bar state, then the
element represents a list of active commands that the user can immediately
interact with.
If a menu element's type attribute is in the
list state, then the element either
represents an unordered list of items (each represented by an li element), each of which represents a command that
the user may perform or activate, or, if the element has no li element children, a paragraph describing available commands.
The label
attribute gives the label of the menu. It is used by user agents to
display nested menus in the UI. For example, a context menu containing
another menu would use the nested menu's label attribute for the submenu's menu label.
The autosubmit attribute is a boolean attribute that, if present, indicates that
selections made to form controls in this menu are to result in the
control's form being immediately submitted.
If a change event bubbles through a
menu element, then, in addition to any
other default action that that event might have, the UA must act as if the
following was an additional default action for that event: if (when it
comes time to execute the default action) the menu element has an autosubmit
attribute, and the target of the event is an input element,
and that element has a type attribute
whose value is either radio or checkbox, and the input element in question
has a non-null form DOM attribute, then
the UA must invoke the submit() method
of the form element indicated by that DOM attribute.
This section is non-normative.
...
A menu (or tool bar) consists of a list of zero or more of the following components:
The list corresponding to a particular menu element is built by iterating over its child
nodes. For each child node in tree order, the
required behaviour depends on what the node is, as follows:
command element with a default
attribute, mark the command as being a default command.
hr element
option element that has a value attribute set to the empty string,
and has a disabled attribute, and
whose textContent consists of a
string of one or more hyphens (U+002D HYPHEN-MINUS)
li element
li
element.
menu element with no label attribute
select element
menu or select element,
then append another separator.
menu element with a label attribute
optgroup element
label attribute as the label of the menu. The submenu
must be constructed by taking the element and creating a new menu for it
using the complete process described in this section.
We should support label in the algorithm above
-- just iterate through the contents like with li, to support input elements in
label elements. Also, optgroup elements without
labels should be ignored (maybe? or at least should say they have no label
so that they are dropped below), and select elements inside
label elements may need special processing.
Once all the nodes have been processed as described above, the user agent must the post-process the menu as follows:
The contextmenu attribute gives the
element's context menu. The
value must be the ID of a menu element in
the DOM. If the node that would be obtained by the invoking the
getElementById() method using the attribute's value as the
only argument is null or not a menu
element, then the element has no assigned context menu. Otherwise, the
element's assigned context menu is the element so identified.
When an element's context menu is requested (e.g. by the user
right-clicking the element, or pressing a context menu key), the UA must
fire a contextmenu event on
the element for which the menu was requested.
Typically, therefore, the firing of the contextmenu event will be the default
action of a mouseup or keyup event. The exact sequence of events is
UA-dependent, as it will vary based on platform conventions.
The default action of the contextmenu event depends on whether the
element has a context menu assigned (using the contextmenu
attribute) or not. If it does not, the default action must be for the user
agent to show its default context menu, if it has one.
If the element does have a context menu assigned, then the user
agent must fire a show event
on the relevant menu element.
The default action of this event is that the user agent must
show a context menu built from the menu element.
The user agent may also provide access to its default context menu, if any, with the context menu shown. For example, it could merge the menu items from the two menus together, or provide the page's context menu as a submenu of the default menu.
If the user dismisses the menu without making a selection, nothing in particular happens.
If the user selects a menu item that represents a command, then the UA must invoke that command's Action.
Context menus must not, while being shown, reflect changes in the DOM;
they are constructed as the default action of the show event and must remain like that until
dismissed.
User agents may provide means for bypassing the context menu processing
model, ensuring that the user can always access the UA's default context
menus. For example, the user agent could handle right-clicks that have the
Shift key depressed in such a way that it does not fire the contextmenu event and instead always shows
the default context menu.
The contextMenu attribute must reflect the contextmenu content attribute.
Toolbars are a kind of menu that is always visible.
When a menu element has a type attribute with the
value toolbar, then the user agent must build the menu
for that menu element and render it in the document in
a position appropriate for that menu
element.
The user agent must reflect changes made to the menu's DOM immediately in the UI.
A command is the abstraction behind menu items, buttons, and links. Once a command is defined, other parts of the interface can refer to the same command, allowing many access points to a single feature to share aspects such as the disabled state.
Commands are defined to have the following facets:
Commands are represented by elements in the DOM. Any element that can
define a command also implements the Command interface:
interface Command {
readonly attribute DOMString commandType;
readonly attribute DOMString id;
readonly attribute DOMString label;
readonly attribute DOMString title;
readonly attribute DOMString icon;
readonly attribute boolean hidden;
readonly attribute boolean disabled;
readonly attribute boolean checked;
void click();
readonly attribute HTMLCollection triggers;
readonly attribute Command command;
};
The Command
interface is implemented by any element capable of defining a command. (If
an element can define a command, its definition will list this interface
explicitly.) All the attributes of the Command interface are read-only. Elements
implementing this interface may implement other interfaces that have
attributes with identical names but that are mutable; in bindings that
simply flatten all supported interfaces on the object, the mutable
attributes must shadow the readonly attributes defined in the Command interface.
The commandType attribute
must return a string whose value is either "command", "radio", or "checked", depending on whether the Type of the command defined by the element is
"command", "radio", or "checked" respectively. If the element does not
define a command, it must return null.
The id attribute
must return the command's ID, or
null if the element does not define a command or defines an anonymous command. This attribute will be shadowed
by the id DOM attribute on
the HTMLElement interface.
The label
attribute must return the command's Label, or null if the element does not
define a command or does not specify a Label. This attribute will be shadowed by
the label DOM attribute on option and
command elements.
The title
attribute must return the command's Hint, or null if the element does not define
a command or does not specify a Hint. This attribute will be shadowed by the
title DOM attribute on
the HTMLElement interface.
The icon
attribute must return an absolute URI to the command's Icon. If the element does not specify an
icon, or if the element does not define a command, then the attribute must
return null. This attribute will be shadowed by the icon DOM attribute on
command elements.
The hidden attribute must
return true if the command's Hidden State is that the command is
hidden, and false if it is that the command is not hidden. If the element
does not define a command, the attribute must return false. This attribute
will be shadowed by the hidden DOM attribute on command elements.
The disabled attribute must
return true if the command's Disabled State is that the command
is disabled, and false if the command is not disabled. This attribute is
not affected by the command's Hidden State. If the element does not
define a command, the attribute must return false. This attribute will be
shadowed by the disabled attribute on
button, input, option, and command elements.
The checked attribute must
return true if the command's Checked State is that the command is
checked, and false if it is that the command is not checked. If the
element does not define a command, the attribute must return false. This
attribute will be shadowed by the checked attribute
on input and command
elements.
The click()
method must trigger the Action for the command. If the element does
not define a command, this method must do nothing. This method will be
shadowed by the click()
method on HTML elements, and is included only for completeness.
The triggers attribute must
return a list containing the elements that can trigger the command (the
command's Triggers).
The list must be live. While the element does not
define a command, the list must be empty.
The commands attribute of the
document's HTMLDocument interface
must return an HTMLCollection
rooted at the Document node, whose filter matches only
elements that define commands and have IDs.
The following elements can define commands: a, button, input, option, command.
a element to define a commandAn a element with an href attribute defines a command.
The Type of the command is "command".
The ID of the command is the
value of the id attribute of
the element, if the attribute is present and not empty. Otherwise the
command is an anonymous command.
The Label of the command
is the string given by the element's textContent DOM attribute.
The Hint of the command is
the value of the title
attribute of the a element. If the attribute
is not present, the Hint is
the empty string.
The Icon of the command is
the absolute URI of the first image in the element. Specifically, in a
depth-first search of the children of the element, the first element that
is img element with a
src attribute
is the one that is used as the image.
The URI must be taken
from the element's src attribute.
Relative URIs must be resolved relative to the base URI of the image
element.
If no image is found, then the Icon facet is left blank.
The Hidden State and Disabled State facets of the command are always false. (The command is always enabled.)
The Checked State of the command is always false. (The command is never checked.)
The Action of the
command is to fire a click event at the element.
button element to define a
commandA button element always defines a command.
The Type, ID, Label, Hint, Icon, Hidden State, Checked State, and Action facets of the command are determined
as for a elements (see
the previous section).
The Disabled
State of the command mirrors the disabled state of the button.
Typically this is given by the element's disabled attribute, but certain button
types become disabled at other times too (for example, the
move-up button type is disabled when it would have no
effect).
input element to define a
commandAn input element whose type attribute is one of submit,
reset, button, radio,
checkbox, move-up, move-down,
add, and remove defines a command.
The Type of the command
is "radio" if the type attribute has
the value radio, "checkbox" if the type
attribute has the value checkbox, and "command" otherwise.
The ID of the command is the
value of the id attribute of
the element, if the attribute is present and not empty. Otherwise the
command is an anonymous command.
The Label of the command depends on the Type of the command:
If the Type is "command",
then it is the string given by the value attribute, if any, and a
UA-dependent value that the UA uses to label
the button itself if the attribute is absent.
Otherwise, the Type is
"radio" or "checkbox". If the element has a label element
associated with it, the textContent of the first such element is
the Label (in DOM terms,
this the string given by element.labels[0].textContent). Otherwise, the value
of the value attribute, if present, is the Label. Otherwise, the Label is the empty string.
The Hint of the command is
the value of the title
attribute of the input element. If the attribute is not
present, the Hint is the
empty string.
There is no Icon for the command.
The Hidden State of the command is always false. (The command is never hidden.)
The Disabled
State of the command mirrors the disabled state of the control.
Typically this is given by the element's disabled attribute, but certain input
types become disabled at other times too (for example, the
move-up input type is disabled when it would have no effect).
The Checked
State of the command is true if the command is of Type "radio" or "checkbox" and the element
has a checked attribute, and false
otherwise.
The Action of the
command is to fire a click event at the element.
option element to define a
commandAn option element with an ancestor select
element and either no value attribute
or a value attribute that is not the
empty string defines a
command.
The Type of the command
is "radio" if the option's nearest ancestor
select element has no multiple attribute, and "checkbox" if it
does.
The ID of the command is the
value of the id attribute of
the element, if the attribute is present and not empty. Otherwise the
command is an anonymous command.
The Label of the command
is the value of the option element's label attribute, if there is one, or the
value of the option element's textContent DOM attribute if it doesn't.
The Hint of the command is
the string given by the element's title attribute, if any, and the empty string if
the attribute is absent.
There is no Icon for the command.
The Hidden State of the command is always false. (The command is never hidden.)
The Disabled
State of the command is true (disabled) if the element has a disabled attribute, and false otherwise.
The Checked
State of the command is true (checked) if the element's selected DOM attribute is true, and false
otherwise.
The Action of the
command depends on its Type. If the command is of Type "radio" then this must set the selected DOM attribute of the
option element to true, otherwise it must toggle the state of
the selected DOM attribute (set it
to true if it is false and vice versa). Then a change event must be
fired on the option element's nearest ancestor
select element (if there is one), as if the selection had
been changed directly.
command element to define a
commandA command element defines a command.
The Type of the command
is "radio" if the command's type attribute is
"radio", "checkbox" if the attribute's value is
"checkbox", and "command" otherwise.
The ID of the command is the
value of the id attribute of
the element, if the attribute is present and not empty. Otherwise the
command is an anonymous command.
The Label of the command
is the value of the element's label attribute, if there is one, or the empty
string if it doesn't.
The Hint of the command is
the string given by the element's title attribute, if any, and the empty string if
the attribute is absent.
The Icon for the command
is the absolute URI resulting from resolving the value of the element's
icon attribute as
a URI relative to the element's base URI. If the element has no icon attribute then the
command has no Icon.
The Hidden State
of the command is true (hidden) if the element has a hidden attribute,
and false otherwise.
The Disabled
State of the command is true (disabled) if the element has either a
disabled
attribute or a hidden attribute (or both), and false otherwise.
The Checked
State of the command is true (checked) if the element has a checked
attribute, and false otherwise.
The Action of the
command is to invoke the behaviour described in the definition of the
click() method
of the HTMLCommandElement
interface.