4.11.3 The command element

Categories:
Metadata content.
Flow content.
Phrasing content.
Contexts in which this element can be used:
Where metadata content is expected.
Where phrasing content is expected.
Content model:
Empty.
Content attributes:
Global attributes
type
label
icon
disabled
checked
radiogroup
command
Also, the title attribute has special semantics on this element.
DOM interface:
interface HTMLCommandElement : HTMLElement {
           attribute DOMString type;
           attribute DOMString label;
           attribute DOMString icon;
           attribute boolean disabled;
           attribute boolean checked;
           attribute DOMString radiogroup;
  readonly attribute HTMLElement? command;
};

The command element represents a command that the user can invoke.

A command can be explicitly part of a context menu or toolbar, using the menu element. It can also be put anywhere else on a page, either just to define a keyboard shortcut, or to define a command that is then referenced from other command elements.

A command element that uses the type, label, icon, disabled, checked, radiogroup, and title attributes defines a new command. A command element that uses the command attribute defines a command by reference to another one. This allows authors to define a command once, and set its state (e.g. whether it is active or disabled) in one place, and have all references to that command in the user interface change at the same time.

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 is an enumerated attribute with three keywords and states. The "command" keyword maps to the Command state, the "checkbox" keyword maps to the Checkbox state, and the "radio" keyword maps to the Radio state. The missing value default is the Command state.

The Command state

The element represents a normal command with an associated action.

The Checkbox state

The element represents a state or option that can be toggled.

The Radio state

The element represents a selection of one item from a list of items.

The label attribute gives the name of the command, as shown to the user. The label attribute must be specified and must have a value that is not the empty string.

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 valid non-empty URL potentially surrounded by spaces. To obtain the absolute URL of the icon when the attribute's value is not the empty string, the attribute's value must be resolved relative to the element. When the attribute is absent, or its value is the empty string, or resolving its value fails, there is no icon.

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 and hidden is subtle. A command would be disabled if, in the same context, it could be enabled if only certain aspects of the situation were changed. A command would 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 attribute must be omitted unless the type attribute is in either the Checkbox state or the Radio state.

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. The attribute must be omitted unless the type attribute is in the Radio state.

If a command element slave has a command attribute, and slave is in a Document, and there is an element in that Document whose ID has a value equal to the value of slave's command attribute, and the first such element in tree order, hereafter master, itself defines a command and either is not a command element or does not itself have a command attribute, then the master command of slave is master.

An element with a command attribute must have a master command and must not have any type, label, icon, disabled, checked, or radiogroup attributes.

The type IDL attribute must reflect the content attribute of the same name, limited to only known values.

The label, icon, disabled, checked, and radiogroup IDL attributes must reflect the respective content attributes of the same name.

The command IDL attribute must return the master command, if any, or null otherwise.

If the element's Disabled State is false (enabled) then the element's activation behavior depends on the element's type and command attributes, as follows:

If the element has a master command set by its command attribute

The user agent must run synthetic click activation steps on the element's master command.

If the type attribute is in the Checkbox state

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.

If the type attribute is in the Radio state

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.

Then, the element's checked attribute attribute must be set to the literal value checked.

Otherwise

The element's activation behavior is to do nothing.

Firing a synthetic click event at the element does not cause any of the actions described above to happen.

If the element's Disabled State is true (disabled) then the element has no activation behavior.

command elements are not rendered unless they form part of a menu.

Here is an example of a toolbar with three buttons that let the user toggle between left, center, and right alignment. One could imagine such a toolbar as part of a text editor. The toolbar also has a separator followed by another button labeled "Publish", though that button is disabled.

<menu type="toolbar">
 <command type="radio" radiogroup="alignment" checked="checked"
          label="Left" icon="icons/alL.png" onclick="setAlign('left')">
 <command type="radio" radiogroup="alignment"
          label="Center" icon="icons/alC.png" onclick="setAlign('center')">
 <command type="radio" radiogroup="alignment"
          label="Right" icon="icons/alR.png" onclick="setAlign('right')">
 <hr>
 <command type="command" disabled
          label="Publish" icon="icons/pub.png" onclick="publish()">
</menu>