Note : The TextRange object is Internet Explorer 4.0 specific.
The TextRange object can be used to manipulate any of the document content. It represents one of the major additions to Dynamic HTML, especially considered against the W3C's 'Document Object Model' (http://www.w3.org/pub/WWW/MarkUp/DOM/). One of the more distinctive points of that specification is the ability to be able to manipulate document content through scripting, which the TextRange object more than adequately covers.
A TextRange object can be created by calling the createTextRange() method from the <BODY>, <BUTTON>, <TEXTAREA> or <INPUT TYPE="text"...> elements, or by using the createRange() method on the users current selection through the Selection Object. The text in the resulting TextRange object can then be manipulate in various ways.
Properties
htmlText
The htmlText property returns the contents of the referenced TextRange object, with its HTML intact.
text
The text property returns the contents of the referenced TextRange object as plain text, regardless of any HTML formatting of the content.
For example, consider the following HTML fragment:
this is the <STRONG>contents</STRONG> of a TextRange object
The htmlText property of the TextRange would be:
this is the <STRONG>contents</STRONG> of a TextRange object
whereas the text property would be:
this is the contents of a TextRange object
Methods
collapse
The collapse method sets an insertion point at either the beginning (collapse(true)), or end (collapse(false)) of the referenced TextRange object. Insertion points are useful, as then various execCommand commands (see below) can be executed on the text range to insert new element into the HTML. For example, select some of the text below (the white paragraph) and then press the right mouse button. When this happens the following script function is executed:
. . .
set selectedRange = document.selection.createRange()
selectedRange.collapse(false)
selectedRange.execCommand "InsertHorizontalRule","HR1"
This creates a TextRange object from the current Selection Object, then forces the insertion point to the end of the resulting TextRange object and inserts a <HR> element with an ID attribute/property setting of HR1
Select some of the text, then press the right mouse button to insert a |
compareEndPoints
The compareEndPoints method can be used to compare the ends (either starting, or finishing ends) of two TextRange objects and returns a value of "-1", "0" or "1" depending on whether the compared TextRange object's end point is greater than, equal to, or less than the referenced
duplicate
The duplicate method can be used to create a temporary copy of a referenced TextRange object. For example:
set TR2 = TR1.duplicate()
would create a TextRange object TR2 that is a copy of the TextRange object TR1
ExecCommand
The Internet Explorer 4.0 specific execCommand method can be used to execute a number of commands over a TextRange object. The syntax is:
Boolean = object.execCommand(command [, bool [, value]])
where:
The possible Command Identifiers are:
| Command | Description | Value |
| BackColor | sets the background colour of the referenced text | #rrggbb|Colour name |
| Bold | Wraps a <B> element around the referenced object |
- |
| Copy | Copies the referenced object to the clipboard | - |
| CreateBookmark | Wraps a <A NAME="..."> element around the referenced object |
String - bookmark to use |
| Create Link | Wraps a <A HREF="..."> element around the referenced object |
String - URL for link |
| Cut | Copies the referenced object to the clipboard, then removes it from the document | - |
| Delete | Deletes the referenced object | - |
| FontName | Sets the typeface for the referenced object | String - Font Name |
| FontSize | Sets the font size for the referenced object | String - size |
| ForeColor | Sets the foreground (i.e. text) colour for the referenced object | #rrggbb | Colour Name |
| FormatBlock | Wraps a specified block-level element around the referenced object | String - block level element to use |
| Indent | Indents the referenced object | - |
| InsertButton | Inserts a <BUTTON> element at the current insertion point |
String - ID value |
| InsertFieldSet | Inserts a <FIELDSET> element at the current insertion point |
String - ID value |
| InsertHorizontalRule | Inserts a <HR> element at the current insertion point |
String - ID value |
| InsertIFrame | Inserts a <IFRAME> element at the current insertion point |
String - SRC value |
| InsertInputButton | Inserts a <INPUT TYPE="button"> element at the current insertion point |
String - ID value |
| InsertInputCheckbox | Inserts a <INPUT TYPE="checkbox"> element at the current insertion point |
String - ID value |
| InsertInputFileUpload | Inserts a <INPUT TYPE="FileUpload"> element at the current insertion point |
String - ID value |
| InsertInputHidden | Inserts a <INPUT TYPE="hidden"> element at the current insertion point |
String - ID value |
| InsertInputPassword | Inserts a <INPUT TYPE="password"> element at the current insertion point |
String - ID value |
| InsertInputRadio | Inserts a <INPUT TYPE="radio"> element at the current insertion point |
String - ID value |
| InsertInputReset | Inserts a <INPUT TYPE="reset"> element at the current insertion point |
String - ID value |
| InsertInputSubmit | Inserts a <INPUT TYPE="submit"> element at the current insertion point |
String - ID value |
| InsertInputText | Inserts a <INPUT TYPE="text"> element at the current insertion point |
String - ID value |
| InsertMarquee | Inserts a <MARQUEE> element at the current insertion point |
String - ID value |
| InsertOrderedList | Inserts a <OL> element at the current insertion point |
String - ID value |
| InsertParagraph | Inserts a <P> element at the current insertion point |
String - ID value |
| InsertSelectDropdown | Inserts a <SELECT TYPE="dropdown"> element at the current insertion point |
String - ID value |
| InsertSelectListbox | Inserts a <SELECT TYPE="Listbox"> element at the current insertion point |
String - ID value |
| InsertTextArea | Inserts a <TEXTAREA> element at the current insertion point |
String - ID value |
| InsertUnorderedList | Inserts a <IL> element at the current insertion point |
String - ID value |
| Italic | Wraps a <I> element around the referenced object |
- |
| JustifyCenter | Centers the referenced object | - |
| JustifyFull | Full justifies the referenced object | - |
| JustifyLeft | Left justifies the referenced object | - |
| JustifyRight | Right justifies the referenced object | - |
| Outdent | Outdents the referenced object | - |
| OverWrite | Sets the typing mode - insert or over-write | Boolean - true=over-write, false=insert |
| Paste | Places clipboard contents at the current insertion point (can only paste text copied by the copy command in script | - |
| PlayImage | Starts playing any dynamic (i.e. video, animated GIF's etc) images with the referenced object | - |
| Refresh | Reloads the source of the current document | - |
| RemoveFormat | Removes formatting for the referenced object | - |
| RemoveParaFormat | Removes any paragraph formatting for the referenced object | - |
| SelectAll | Selects the whole document text | - |
| StopImage | Stops playing of all dynamic images | - |
| Underline | Wraps a <U> around the referenced object |
- |
| Unlink | Removes a link | - |
| Unselect | Empties any selections from the document | - |
Note : Different Command Identifiers are supported 4.0 for the TextRange object (or the Document Object object).
expand
The expand method expands a TextRange object to totally cover any partial units. By using differing arguments, it can expand to cover characters, words, sentences, or an entire editable text range. For example, suppose the following is a users current text selection:
I'm only partly selected
Using:
bIsExpanded=TextRangereference.expand("word")
would return true (i.e. bIsExpanded=true) if the TextRange object was successfully expanded to cover the whole of the word 'partly'. Note that the expand method expands the TextRange at both ends to cover the amount specified in the method argument (this can be character, word, sentence or textedit)
findText
The findText method searches for text in the given TextRange object and if it finds the text, positions the TextRange object around the text. For example:
set TRange=document.body.createTextRange()
TRange.findText("HTMLib")
. . .
would search the whole document for the text "HTMLib".
getBookmark
The getBookmark method can be used to create a 'bookmark' for the referenced TextRange object, which can then be moved to later, using the moveToBookmark method (see below). This is useful when managing an entire document as a TextRange object, because it allows script functions to navigate back to certain points of the TextRange object.
inRange
The inRange method allows a script function to determine where a referenced TextRange object is contained within another TextRange object. For example:
bIsIn=TR1.inRange(TR2)
would return true (bIsIn=true) is the TextRange TR1 was contained in the TextRange TR2.
isEqual
Two separate TextRange objects are deemed to be equal if they're start and end points are the same position within the document content. The isEqual method can be used to determine whether or not two TextRange objects are considered equal.
bIsEqual=TR1.isEqual(TR2)
would return true is the TextRange object TR1 is equal to the TextRange object TR2.
move
The move method can be used to move a TextRange object by a set number of units. Possible units are character, word, sentence or textedit. The optional argument count can be used to move the TextRange a set number of units. For example, click the button below. It'll create a TextRange (with the button text), then move the text range 3 words, expand it by a word and highlight the resulting TextRange object.
The script code is:
set Range=document.all("btn1").createTextRange()
Range.move "word",3
Range.expand "word"
Range.select()
Note : Moving the collapsed TextRange by three words positions its start point between the third and fourth words, so it's the fourth word that is selected and highlighted.
moveEnd
The moveEnd method alters the size (and content) of the referenced TextRange object by moving its end point by a set number of units (again, these are character, word, sentence and textedit). For example, if we added:
Range.moveEnd "word",1
to the above example, it would highlight "very long" as the TextRange, instead of just "long".
moveStart
Like the moveEnd method, the moveStart method changes the start point of the referenced TextRange object (again in character, word, sentence, or textedit units.
moveToBookmark
The moveToBookmark moves the referenced TextRange object to a bookmark, previously defined using the getBookmark method (described above).
moveToElementText
The moveToElementText method moves the referenced TextRange's start and end points to encompass the text of any element contained in the original TextRange object. For example, the button below contained some <STRING> text that contains some <EM> emphasised text. Clicking it once will move the TextRange (created from the whole button) to the contents of the <STRong> element, clicking it twice will move the TextRange object to the text in the <EM> element.
It's clear how useful the moveToElementText method could be given TextRange objects that encompass an entire document. Any element in the document could be made into a TextRange object, event though most elements don't support direct TextRange object creation.
moveToPoint
The moveToPoint method can be used to create an initially empty TextRange object whose start and end points are specified in the x and y arguments of the method. The resulting TextRange object can then be expanded (using the expand method (described above) or the moveEnd and moveStart methods to encompass a certain amount of text.
parentElement
Every TextRange object has a parentElement property that contains a reference to the element that totally encloses the contents of the TextRange element. The element object reference returned represents the lowest element object (in the document hierarchy) that totally encloses the referenced TextRange. For example, the parentElement reference for any selected TextRange objects in the collapse method, is the <P> element.
pasteHTML
The pasteHTML method pastes the given HTML string into the contents of the referenced TextRange, over-writing the existing TextRange contents. The pasteHTML method will never fail, although to ensure the best results, you should take care to only use correct HTML in the pasteHTML method. For example <BUTTON> elements cannot be nested, so TextRange objects created from <BUTTON> elements should not have any <BUTTON> HTML inserted into them with the pasteHTML method.
queryCommandEnabled
The Internet Explorer 4.0 specific queryCommandEnabled method allows you to determine whether a specific command (as defined by its command identifier is available for the referenced object. As mentioned before, certain commands aren't available for the respective Document Object or Text Range objects, so the queryCommandEnabled method should be used to determine whether the command is enabled for the referenced object before attempting to use the command. The queryCommandEnabled method takes one argument, which should be a string containing one of the Command Identifiers.
queryComandIndeterm
The Internet Explorer 4.0 specific queryCommandIndeterm method can be used to determine whether a specific command is in the indeterminate state or not. It accepts one argument - a string value containing the Command Identifier in question.
queryCommandState
The queryCommandState method is used to determine the state of any command issued with the execCommand method (see above). It returns true if the command was successfully carried out on the referenced object, false if the command failed.
queryCommandSupported
queryCommandSupported method can be used to determine whether the command is currently on or off. It accepts a single argument of a string value defining the Command Identifier to be queried and returns a boolean value of true is the command is on for the referenced object, or false if it isn't.
queryCommandText
The Internet Explorer 4.0 specific queryCommandText method can be used to determine the the string associated with a command. It accepts the standard string argument of the Command Identifier together with a string value which can be either Name or StatusText which specified whether to return the short name of the command in question, or the status bar text which may appear with the specific command.
queryCommandValue
The Internet Explorer 4.0 specific queryCommandValue method can be used to determine the value argument used in the execCommand method. See the Command Identifiers for details of the values used with certain commands.
scrollIntoView
The scrollIntoView method is one of the standard Dynamic HTML methods and can be used to force the current viewing window to scroll to a referenced TextRange object. It accepts a boolean argument (true or false) which determines whether the window should be scrolled so that the referenced TextRange object is at the top (true) or bottom (false) of the window. For example, the button below will select the contents of the <BUTTON> element in the move method and scroll it into view, so that it's at the top of the viewing window.
select
The select method highlights the referenced TextRange object in whatever highlighting styles are set by the users system for highlighted text (for example, text selected in a document).
setEndPoint
The setEndPoint method sets the end point of one TextRange object, based on the contents of another TextRange object. It accepts two arguments - one specifying which end points should be matched (this can be either StartToEnd, StartToStart, EndToStart or EndToEnd) and a reference to the TextRange object whose end point is being matched.
© 1995-1998, Stephen Le Hunte