TextRange
--------------------------------------------------------------------------------
Description
Represents text in an HTML element.
Remarks
You can use this object to retrieve and modify text in an element, to locate specific strings in the text, and to carry out commands that affect the appearance of the text.
You can retrieve a text range object by applying the createTextRange method to a BODY, BUTTON, or TEXTAREA element or an INPUT element having text type. You can modify the extent of the text range by moving its start and end positions with methods such as move, moveToElementText, and findText. Within the text range, you can retrieve and modify plain text or HTML text. These forms of text are identical except that HTML text includes HTML tags; plain text does not.
This feature might not be available on non-Win32® platforms. See article Q172976 in the Microsoft® Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Example
The following JScript example changes the text of a BUTTON element to "Clicked".
var b = document.all.tags("BUTTON");
if (b!=null) {
var r = b[0].createTextRange();
if (r != null) {
r.text = "Clicked";
}
}
Properties
htmlText, text, boundingHeight, boundingLeft, boundingTop, boundingWidth, offsetLeft, offsetTop
Methods
collapse, compareEndPoints, duplicate, execCommand, expand, findText, getBookmark, inRange, isEqual, move, moveEnd, moveStart, moveToBookmark, moveToElementText, moveToPoint, parentElement, pasteHTML, queryCommandEnabled, queryCommandIndeterm, queryCommandState, queryCommandSupported, queryCommandValue, scrollIntoView, select, setEndPoint
See Also
createTextRange
--------------------------------------------------
createTextRange
--------------------------------------------------------------------------------
Description
Creates a text range object for the given object. You use a text range to examine and modify the text within an object.
Syntax
TextRange = object.createTextRange( )
Return Value
Returns a text range object if successful, or NULL otherwise.
Examples
The following JScript example creates a text range for the document, then uses the range to display all text and HTML tags in the document.
var rng = document.body.createTextRange( );
if (rng!=null) {
alert(rng.htmlText);
}
The following JScript example creates a text range for the first BUTTON element in the document, then uses the text range to change the text in the button.
var coll = document.all.tags("BUTTON");
if (coll!=null && coll.length>0) {
var rng = coll[0].createTextRange();
rng.text = "Clicked";
}
Applies To
BODY, BUTTON, INPUT (text type only), TEXTAREA
See Also
TextRange
----------------------------------------------------
outerHTML
--------------------------------------------------------------------------------
Description
Sets or retrieves the current element and its content in HTML.
Syntax
object.outerHTML[ = outerHTML]
Settings
This read-write property can be any valid string containing a combination of text and HTML tags, except for ,
, and tags.
When setting this property, the given string completely replaces the element, including its start and end tags. If the string contains HTML tags, the string is parsed and formatted as it is placed into the document.
Note You cannot set this property while the document is loading. Wait for the onload event before attempting to set it. If a tag is dynamically created using TextRange, innerHTML, or outerHTML, you can only use JScript to create new events to handle the newly formed tags. VBScript is not supported.
Applies To
A, ACRONYM, ADDRESS, APPLET, AREA, B, BGSOUND, BIG, BLOCKQUOTE, BR, BUTTON, CENTER, CITE, CODE, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TEXTAREA, TT, U, UL, VAR, XMP
See Also
insertAdjacentHTML method
---------------------------------------------
innerHTML
--------------------------------------------------------------------------------
Description
Sets or retrieves the HTML between the start and end tags of the current element.
Syntax
object.innerHTML[ = innerHTML]
Settings
This read-write property takes a string containing a valid combination of text and HTML tags, except for , , and tags.
When setting this property, the given string completely replaces the existing content of the element. If the string contains HTML tags, the string is parsed and formatted as it is placed into the document.
Note You cannot set this property while the document is loading. Wait for the onload event before attempting to set it. If a tag is dynamically created using TextRange, innerHTML, or outerHTML, you can only use JScript to create new events to handle the newly formed tags. VBScript is not supported.
Applies To
A, ACRONYM, ADDRESS, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DEL, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, I, IFRAME, IMG, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OL, P, PRE, Q, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TH, TT, U, UL, VAR
See Also
insertAdjacentHTML method
--------------------------------------------------
htmlText
--------------------------------------------------------------------------------
Description
Returns the HTML source as a valid HTML fragment.
Syntax
object.htmlText
Remarks
This property corresponds to the fragment portion of the CF_HTML clipboard format.
This property has read-only permission, meaning you can retrieve its current value, but not change it.
This feature may not be available on non-Win32® platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Applies To
TextRange
------------------------------------------------------
pasteHTML
--------------------------------------------------------------------------------
Description
Pastes HTML text into the given text range. The text completely replaces any previous text and HTML elements in the range.
Syntax
object.pasteHTML(htmlText)
Parameter Description
htmlText String specifying the HTML text to paste. The string can contain text and any combination of the HTML tags described in HTML Elements.
Return Value
No return value.
Remarks
Although this method never fails, it might alter the HTML text to make it fit the given text range. For example, attempting to paste a table cell into a text range that does not contain a table might cause the method to insert a TABLE element. For predictable results, you should paste only well-formed HTML text that is appropriate for the given text range.
Note You cannot use this method while the document is loading. Wait until the document is completely downloaded.
Remarks
This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Example
The following JScript example replaces the current selection with a new paragraph.
var sel = document.selection;
if (sel!=null) {
var rng = sel.createRange();
if (rng!=null)
rng.pasteHTML("Selection has been replaced.");
}
Applies To
TextRange
--------------------------------------------------
expand
--------------------------------------------------------------------------------
Description
Expands the range so that partial units are completely contained.
Syntax
Boolean = object.expand(unit)
Parameter Description
unit Units to move in the range. Can be one of the following: character Expands a character.
word Expands a word. A word is a collection of characters terminated by a space or other white-space character.
sentence Expands a sentence. A sentence is a collection of words terminated by a punctuation character, such as a period.
textedit Expands to enclose the entire range.
Return Value
Returns TRUE if it successfully expands the range, or FALSE otherwise.
Remarks
This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Example
The following example creates a range from the current selection, then uses expand to ensure that any word partially enclosed by the range becomes entirely enclosed in the range.
var rng = document.selection.createRange();
rng.expand("word");
Applies To
TextRange
See Also
collapse
--------------------------------------------------------------------------------
findText
--------------------------------------------------------------------------------
Description
Searches for text in the document. Positions the start and end points of the range to encompass the search string.
Syntax
bFound = object.findText(sText [, iSearchScope] [, iFlags])
Parameter Description
sText String specifying the text to find.
iSearchScope Optional. An integer indicating the direction to search from the starting point of the range. A positive integer indicates a forward search; a negative integer indicates a backward search.
iFlags Optional. A combination of one or more of the following flags indicating the type of search: 2 match whole words only.
4 match case.
Return Value
Returns true if the search text is found, or false otherwise.
Remarks
A range has two distinct states: degenerate and non-degenerate. Analogous to a text editor, a degenerate range is like a text editor caret (insertion point); it does not actually select any characters. Instead it specifies a point between two characters. A degenerate range’s endpoints are effectively next to each other. On the other hand, a non-degenerate range is like a text editor selection. A certain amount of text is selected, and the end points of the range are not next to each other.
The degenerate state of the range has a significant impact on the behavior of the findText method. The value passed for the iSearchScope parameter controls the part of the document, relative to the range, that is searched. If the range is degenerate, either a large positive or a large negative number can be passed to indicate the direction of the search. If the range is non-degenerate, passing 0 will cause only the text selected by the range to be searched. Passing a large positive number will cause the text to the right of the start of the range to be searched. Passing a large negative number will cause the text to the left of the end of the range to be searched. For all intensive purposes, a large positive and a large negative number are 9999999 and -9999999, respectively. Passing anything else for iSearchScope may not be compatible with future versions of Internet Explorer.
This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Example
The following example creates a Text Range over the body of the document and searches for text with various flag combinations. The results are indicated in the code comments.
Leonardo da Vinci was one of the great masters of the High Renaissance,
especially in painting, sculpture, architecture, engineering, and science.
Applies To
TextRange
-----------------------------------------------
duplicate
--------------------------------------------------------------------------------
Description
Returns a duplicate of the range.
Syntax
TextRange = object.duplicate( )
Return Value
Returns TextRange.
Remarks
This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Applies To
TextRange
-----------------------------------------------
select
--------------------------------------------------------------------------------
Description
Highlights the input area of a form element.
Syntax
object.select( )
Return Value
No return value.
Remarks
You can use the select method with the focus method to highlight a field and position the cursor for a user response.
Applies To
INPUT, TEXTAREA
See Also
onselect
-----------------------------------------------
select
--------------------------------------------------------------------------------
Description
Makes the active selection equal to the current object.
Syntax
object.select( )
Return Value
No return value.
Remarks
This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Applies To
TextRange
--------------------------------------------------------------------------------
execScript
--------------------------------------------------------------------------------
Description
Executes the script defined for the expression parameter in the language parameter. The language defaults to JScript.
Syntax
object.execScript(expression , language)
Parameter Description
expression String specifying the code to be executed.
language String specifying the language in which the code is executed.
Return Value
No return value.
Applies To
window
----------------------------------
move (PER SCROLL TESTO HTML)
--------------------------------------------------------------------------------
Description
Collapses the given text range and moves the empty range by the given number of units.
Syntax
long = object.move(unit [, count])
Parameter Description
unit String specifying the units to move. Can be one of the following: character Moves one or more characters.
word Moves one or more words. A word is a collection of characters terminated by a space or other white-space character.
sentence Moves one or more sentences. A sentence is a collection of words terminated by a punctuation character, such as a period.
textedit Moves to the start or end of the original range.
count Optional. Integer specifying the number of units to move. This can be positive or negative. When omitted, defaults to 1.
Return Value
Returns the actual number of units moved.
Remarks
This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Applies To
TextRange
See Also
moveEnd, moveStart
------------------------------------------
moveToPoint
--------------------------------------------------------------------------------
Description
Moves the start and end positions of the text range to the given point. The coordinates of the point must be in pixels and be relative to the upper-left corner of the window. The resulting text range is empty, but can be expanded and moved using methods such as expand and moveEnd.
Syntax
object.moveToPoint(x, y)
Parameter Description
x Integer specifying the x-coordinate, in pixels.
y Integer specifying the y-coordinate, in pixels.
Return Value
No return value.
Remarks
This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Example
The following JScript example moves the text range to the same point as the user clicked the mouse, then expands the range and selects the text within the new range.
Applies To
TextRange
------------------------------------------
moveToBookmark
--------------------------------------------------------------------------------
Description
Moves to a bookmark. Bookmarks are opaque strings that are created with the getBookmark method.
Syntax
Boolean = object.moveToBookmark( )
Return Value
Returns TRUE if successful, or FALSE otherwise.
Remarks
This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Applies To
TextRange
--------------------------------------------------------------------------------
getBookmark
--------------------------------------------------------------------------------
Description
Retrieves a bookmark (opaque string) that can be used with moveToBookmark to return to the same range.
Syntax
string = object.getBookmark( )
Return Value
Returns a string if successful, or null otherwise.
Remarks
This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Applies To
TextRange
-----------------------------------
moveToElementText
--------------------------------------------------------------------------------
Description
Moves the text range so that the start and end positions of the range encompass the text in the given element.
Syntax
object.moveToElementText(element)
Parameter Description
element Element object.
Return Value
No return value.
Remarks
This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Applies To
TextRange
--------------------------------------------------------------------------------
getAttribute
--------------------------------------------------------------------------------
Description
Retrieves the value of the given attribute.
Syntax
variant = object.getAttribute(attrName [, iFlags])
Parameter Description
attrName String specifying the name of the attribute.
iFlags Optional. A combination of the following flags: 1 indicates that a case-sensitive search should be used to locate the attribute. 2 indicates that the value should be returned as it was specified in the source. 0 (default) indicates that the search should be case-insensitive, and that the returned value may be interpolated.
Return Value
Returns a string, number, or Boolean value as defined by the attribute. If the attribute is not present, this method returns null.
Remarks
If two or more attributes have the same name (differing only in uppercase and lowercase letters) and caseSensitive is FALSE, this method retrieves values only for the last attribute (the last to be created with this name). All other attributes of the same name are ignored.
If iFlags is set to 1, the uppercase and lowercase letters in attrName must match exactly those in the attribute name. If the caseSensitive parameter for the setAttribute method is set to true and this option is set to false (default), a conflict will arise.
Applies To
A, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, WBR, XMP, style
------------------------------------
setAttribute
--------------------------------------------------------------------------------
Description
Sets the value of the given attribute. If the attribute is not already present, the method adds the attribute to the element and sets the value.
Syntax
object.setAttribute(attrName , value [, caseSensitive])
Parameter Description
attrName String specifying the name of the attribute.
value String, number, or Boolean value to assign to the attribute.
caseSensitive Optional. Boolean value specifying whether to use a case-sensitive search to locate the attribute. If TRUE, the uppercase and lowercase letters in attrName must match exactly those in the attribute name. By default, this parameter is TRUE.
Return Value
No return value.
Remarks
Be careful when spelling attribute names. If caseSensitive is TRUE and attrName does not have the same uppercase and lowercase letters as the attribute, this method creates a new attribute.
If two or more attributes have the same name (differing only in uppercase and lowercase letters) and caseSensitive is FALSE, this method assigns a value only to the first attribute (the first to be created with this name). All other attributes of the same name are ignored.
Applies To
A, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, WBR, XMP, style
---------------------------------------
focus
--------------------------------------------------------------------------------
Description
Causes a control to receive the focus and executes the code specified by onfocus.
Syntax
object.focus( )
Return Value
No return value.
Applies To
A, APPLET, AREA, BODY, BUTTON, CAPTION, DIV, EMBED, FIELDSET, FRAME, FRAMESET, HR, IFRAME, IMG, INPUT, MARQUEE, OBJECT, SELECT, SPAN, TABLE, TD, TEXTAREA, TR, window
----------------------------------------------
click
--------------------------------------------------------------------------------
Description
Simulates a click by causing the onclick event to fire.
Syntax
object.click( )
Return Value
No return value.
Applies To
A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
--------------------------------------------------------------------------------
parentElement
--------------------------------------------------------------------------------
Description
Retrieves the parent element for the given text range. The parent element is the element that completely encloses the text in the range.
Syntax
element = object.parentElement( )
Return Value
Returns an element object if successful, or null otherwise.
Remarks
If the text range spans text in more than one element, this method returns the smallest element that encloses all the elements. When you insert text into a range that spans multiple elements, the text is placed within the parent element rather than in any of the contained elements.
Remarks
This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.
Example
The following JScript example retrieves the parent element for the text range created from the current selection and displays the tag name of the element.
var sel = document.selection;
var rng = sel.createRange();
var el = rng.parentElement();
alert(el.tagName);
Applies To
TextRange
--------------------------------------------------------------------------------