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:
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:
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.