Executing Commands
The Dynamic HTML object model exposes a set of methods that allow
user operations to be executed directly on a range or on the document.
These operations correspond to different actions the user can perform on the
text. For example, there are commands for making text boldface or not
boldface, similar to a Bold toggle button in a text editor. These commands modify
the underlying HTML to achieve the desired result. Currently all style
manipulations occur by inserting the presentational HTML markup into the
document. There are no guarantees that the commands will perform style
manipulations this way in future releases of the browser. The only guarantee is that the
commands will still create the same visible end results.
These commands enable a page to manipulate the document style
and contents without worrying about the HTML structural rules. For
example, when the Bold command is invoked, appropriate HTML is automatically
generated. Commands are also available for performing other basic user
operations, such as cutting and copying text, adding controls to a fixed region, and
undoing the last operation.
TextRange objects and the
document object expose a number of methods for executing and querying the status of commands. These methods fall
into two categories: those that return the status of a command and those that
execute a command. The six available methods for determining a
command's status are shown here:
- queryCommandSupported(cmdID)
- queryCommandEnabled(cmdID)
- queryCommandState(cmdID)
- queryCommandIndeterm(cmdID)
- queryCommandText(cmdID, text)
- queryCommandValue(cmdID)
These methods are best understood in the context of a text editor's
user interface. The queryCommandSupported
and queryCommandEnabled methods return Boolean values reporting whether the specified command is
supported by the object and whether it is currently available. If a command is
disabled, executing the command has no effect on the document. The
queryCommandState method indicates whether the specified command has been carried
out on the object; for example, calling this method with the parameter
Bold returns true if the object spans boldface text,
false if not, and null if the method
cannot determine the state. The
queryCommandIndeterm method indicates
whether the state of the command is available. For example, if a
TextRange object spans both boldface text and plain text, this method returns
true because the actual bold state is unavailable.
The queryCommandText and
queryCommandValue methods provide further information about a command. The
queryCommandText method returns a short menu string or a longer status bar string that describes the function.
Because the texts of these strings may vary among browsers, you should not write
code that relies on a particular string being returned. The
queryCommandValue method returns the actual value of the command. For example, calling
this method with the parameter FontName returns the name of the font.
None of the preceding methods have any effect on the document;
they simply return information about the current state. To interact with the
document, the following two methods are exposed:
- execCommand(cmdID [, displayUI] [, value])
- execCommandShowHelp(cmdID)
The execCommand method executes a command. The
cmdID argument represents the command to invoke and is required. The optional
displayUI parameter specifies whether to display or hide any corresponding user interface. By
default, any associated user interface is not displayed. In some cases,
bypassing the user interface would create a security concern, so the
displayUI argument is ignored and the user interface is always displayed. For example, invoking
the Print command will not print the document without first alerting the user.
The value attribute supplies a value to the command. The
execCommandShowHelp method displays the help file if one is supported for the specified command.
The following code, which analyzes a document in order to
determine how many fonts are displayed, illustrates how the
queryCommandValue method can be used:
<SCRIPT LANGUAGE="JavaScript">
function walkDocument() {
var fonts = new Array();
var tr = document.body.createTextRange();
tr.collapse();
while (tr.moveEnd("character", 1)) {
var val = tr.queryCommandValue("FontName");
if (null == fonts[val]) {
fonts[val] = true;
fonts.length++
}
tr.collapse(false);
}
var settings = "Total Fonts: " + fonts.length + "\n";
for (var font in fonts) {
settings += " " + font + "\n";
}
alert(settings);
}
</SCRIPT>
The companion CD contains a list of all the available commands and
the types of values they accept and return. [Содержание]
|
