MSHTML Methods: queryCommandEnabled

Scripting Syntax

bEnabled = object.queryCommandEnabled (sCommand);

Object

The queryCommandEnabled method applies to the document and TextRange objects and the controlRange collection.

Arguments

The required sCommand argument names a command to execute. There are many supported commands.

Return Value

The method returns true if the named command is supported and enabled and its state is not invalid. Otherwise, it returns false.

Behaviour

The queryCommandEnabled method provides scriptable access to the object’s IOleCommandTarget functionality, specifically to call the QueryStatus method and test for a particular combination of flags.

The case-insensitive command name given as sCommand translates to a numeric command ID in the MSHTML command group represented programmatically by CGID_MSHTML. Even within this command group, only a small subset of the commands that are supported through the IOleCommandTarget interface are supported for scripting.

The queryCommandEnabled method fails, in the sense of causing a runtime script error, if the given command name is not supported for scripting. It also fails, again with a runtime script error, if the call to QueryStatus fails.

Given a successful call to QueryStatus, the queryCommandEnabled method returns true or false according to whether QueryStatus produces the following combination:

• OLECMDF_SUPPORTED and OLECMDF_ENABLED both set
• OLECMDF_LATCHED and OLECMDF_NINCHED not both set
• all other bits clear

The second part to the combination allows that the status can be off, on or indeterminate (but cannot be both on and indeterminate).

Behavior within the call to QueryStatus varies with the command and is anyway left for the different topic of MSHTML’s IOleCommandTarget functionality.

function Test_document_queryCommandEnabled ()
{
    var cmd = prompt ("Enter the name of an MSHTML command to query for being enabled:", "");
    if (cmd == null) return;

    var result = document.queryCommandEnabled (cmd);
    alert ('queryCommandEnabled ("' + cmd + '") for the document returned ' + result);
}