A command element can be used to invoke an operation that can come from multiple sources. For example, a clipboard paste operation can be invoked from the Edit menu, a context menu and by pressing a keyboard shortcut. You attach the code to the command using the oncommand attribute. It will be called no matter how it is invoked by the user. In addition, disabling the command will automatically disable the menu items and keyboard shortcuts.

Commands are identified by their id. If you include the script chrome://global/content/globalOverlay.js in your window, you can use the function goDoCommand function to invoke the command. Using this function has the advantage that the command will be sent to the part of the UI which will respond to it. Typically, this will be the currently focused element.

Like a broadcaster, commands forward attributes to other elements.

More information is available in the XUL tutorial. See also: command attribute, commandset element

Attributes
disabled, label, oncommand,reserved

Examples

The following code will send a paste command (cmd_paste) to the currently focused element:

// First include chrome://global/content/globalOverlay.js
goDoCommand("cmd_paste");

Example with two buttons

<commandset><command id="cmd_openhelp" oncommand="alert('Help');"/></commandset>
<button label="Help" command="cmd_openhelp"/>
<button label="More Help" command="cmd_openhelp"/>

Attributes

disabled
Type: boolean
Indicates whether the element is disabled or not. If this attribute is set to true the element is disabled. Disabled elements are usually drawn with grayed-out text. If the element is disabled, it does not respond to user actions, it cannot be focused, and the command event will not fire.
Visible controls have a disabled property which, except for menus and menuitems, is normally preferred to use of the attribute, as it may need to update additional state.
label
Type: string
The label that will appear on the element. If this is left out, no text appears. For an editable menuitem element the value of this attribute is copied to the menulist.value property upon user selection of the menuitem.

 

oncommand
Type: script code
This event handler is called when the command is activated. This occurs when a user selects a menu item or presses a keyboard shortcut attached to the command.
reserved
Type: string
This attribute applies to a command element.
If set to "true", it indicates that the command is reserved for chrome code, and is not available to content. This means that key events to execute these commands won't be passed to content, and event listeners registered for them in content will not be executed.
Currently, content will still receive these key events, it just can't override them. But in future releases it won't even receive them. See bug 1173061 for details.

 

Properties

Inherited Properties
align, attributes, allowEvents, baseURI, boxObject, builder, childElementCount, childNodes, children, className, clientHeight, clientLeft, clientTop, clientWidth, collapsed, contextMenu, controllers, database, datasources, dir, firstChild, firstElementChild, flex, height, hidden, id, lastChild, lastElementChild, left, localName, maxHeight, maxWidth, menu, minHeight, minWidth, namespaceURI, nextElementSibling, nextSibling, nodeName, nodeType, nodeValue, observes, ordinal, orient, ownerDocument, pack, parentNode, persist, prefix, previousElementSibling, previousSibling, ref, resource, scrollHeight, scrollLeft, scrollTop, scrollWidth, statusText, style, tagName,textContent, tooltip, tooltipText, top, width

Methods

Inherited Methods
addEventListener(), appendChild(), blur, click, cloneNode(), compareDocumentPosition, dispatchEvent(), doCommand, focus, getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getBoundingClientRect(), getClientRects(), getElementsByAttribute, getElementsByAttributeNS, getElementsByClassName(), getElementsByTagName(), getElementsByTagNameNS(), getFeature, getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isDefaultNamespace(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), querySelector(), querySelectorAll(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData

Document Tags and Contributors

Contributors to this page: wbamberg, Sheppy, pippijn, Cptskippy, Mgjbot, Brettz9, Drmaddon, Ptak82, Taken, Dria, Pmash
Last updated by: wbamberg,