MSHTML Methods: queryCommandValue

Scripting Syntax

vCmdValue = object.queryCommandValue (sCommand);

Object

The queryCommandValue 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 the command status (treating indeterminate as on) or in some cases an evaluation of the command.

Behaviour

The queryCommandValue provides scriptable access to the object’s IOleCommandTarget functionality, specifically to call the QueryStatus method (ordinarily) or the Exec method, depending on the given command.

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 queryCommandValue method fails, in the sense of causing a runtime script error, if the given command name is not supported for scripting. For supported commands, behaviour varies depending on whether the command is expected to evaluate as a boolean.

Boolean Evaluations

For all but a few commands, queryCommandValue is effectively a call to QueryStatus to test for a particular combination of flags. It 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 or OLECMDF_NINCHED set, but not both
all other bits clear

The second part of this combination represents the indeterminate and on states. For these commands, queryCommandValue is for all practical purposes the same as queryCommandState but with indeterminate treated as on.

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

Other Evaluations

A handful of commands evaluate differently:

BackColor, FontSize and ForeColor as integers
FontName and FormatBlock as strings
GetBlockFormats as an array

For these, queryCommandValue is effectively Exec but with no input and no prompting of the user. It fails, again with a runtime script error, if the call to Exec fails.

What happens in the call to Exec varies with the command and is anyway left for the different topic of MSHTML’s IOleCommandTarget functionality.

There is a demonstration here. To see it, please enable scripting and then refresh this page.

function Test_TextRange_queryCommandValue ()
{
    var cmd = prompt ("Enter the name of an MSHTML command to evaluate:", "");
    if (cmd == null) return;

    /*  Create a TextRange for the first button in the document.  */

    var range = document.getElementsByTagName ("BUTTON") [0].createTextRange ();
    if (range == null) return;

    var value = range.queryCommandValue (cmd);
    alert ('queryCommandValue ("' + cmd + '") for the TextRange returned a ' + typeof (value) + ": " + value);
}