MSHTML Methods: queryCommandState

Scripting Syntax

bOn = object.queryCommandState (sCommand);

Object

The queryCommandState 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 is in the on state. Otherwise, it returns false.

Behaviour

The queryCommandState 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 queryCommandState 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 queryCommandState method returns true or false according to whether QueryStatus produces the following combination:

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

The second part of this combination represents the on state. To this method, the indeterminate state (if supported) is effectively the same as off.

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_queryCommandState ()
{
    var cmd = prompt ('Enter the name of an MSHTML command to query for the "on" state:', "");
    if (cmd == null) return;

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