4.11.5 Commands

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 facets such as the Disabled State.

Commands are defined to have the following facets:

Type

The kind of command: "command", meaning it is a normal command; "radio", meaning that triggering the command will, amongst other things, set the Checked State to true (and probably uncheck some other commands); or "checkbox", meaning that triggering the command will, amongst other things, toggle the value of the Checked State.

ID

The name of the command, for referring to the command from the markup or from script. If a command has no ID, it is an anonymous command.

Label

The name of the command as seen by the user.

Hint

A helpful or descriptive string that can be shown to the user.

Icon

An absolute URL identifying a graphical image that represents the action. A command might not have an Icon.

Access Key

A key combination selected by the user agent that triggers the command. A command might not have an Access Key.

Hidden State

Whether the command is hidden or not (basically, whether it should be shown in menus).

Disabled State

Whether the command is relevant and can be triggered or not.

Checked State

Whether the command is checked or not.

Action

The actual effect that triggering the command will have. This could be a scripted event handler, a URL to which to navigate, or a form submission.

These facets are exposed on elements using the command API:

element . commandType

Exposes the Type facet of the command.

element . id

Exposes the ID facet of the command.

element . commandLabel

Exposes the Label facet of the command.

element . title

Exposes the Hint facet of the command.

element . commandIcon

Exposes the Icon facet of the command.

element . accessKeyLabel

Exposes the Access Key facet of the command.

element . commandHidden

Exposes the Hidden State facet of the command.

element . commandDisabled

Exposes the Disabled State facet of the command.

element . commandChecked

Exposes the Checked State facet of the command.

element . click()

Triggers the Action of the command.

document . commands

Returns an HTMLCollection of the elements in the Document that define commands and have IDs.

User agents may expose the commands whose Hidden State facet is false (visible) and whose elements are in a Document. For example, such commands could be listed in the user agent's menu bar. User agents are encouraged to do this especially for commands that have Access Keys, as a way to advertise those keys to the user.

4.11.6 The dialog element

Categories:

Flow content.

Sectioning root.

Contexts in which this element can be used:

Where flow content is expected.

As a child of a dt element.

As a child of a th element.

Content model:

Flow content.

Content attributes:

Global attributes

open

DOM interface:

interface HTMLDialogElement : HTMLElement {
           attribute boolean open;
           attribute DOMString returnValue;
  void show(optional (MouseEvent or Element) anchor);
  void showModal(optional (MouseEvent or Element) anchor);
  void close(optional DOMString returnValue);
};

The dialog element represents a part of an application that a user interacts with to perform a task, for example a dialog box, inspector, or window.

The open attribute is a boolean attribute. When specified, it indicates that the dialog element is active and that the user can interact with it.

dialog . show( [ anchor ] )

Displays the dialog element.

The argument, if provided, provides an anchor point to which the element will be fixed.

dialog . showModal( [ anchor ] )

Displays the dialog element and makes it the top-most modal dialog.

The argument, if provided, provides an anchor point to which the element will be fixed.

This method honors the autofocus attribute.

dialog . close( [ result ] )

Closes the dialog element.

The argument, if provided, provides a return value.

dialog . returnValue [ = result ]

Returns the dialog's return value.

Can be set, to update the return value.

4.11.6.1 Anchor points

This section will eventually be moved to a CSS specification; it is specified here only on an interim basis until an editor can be found to own this.

The 'anchor-point' property specifies a point to which dialog boxes are to be aligned.

If the value is the keyword 'none', then no explicit alignment point is defined. The user agent will pick an alignment point automatically if necessary (as described in the definition of the open() method above).