
This interface provides the ability to access the text range object in an HTML element. You use this interface 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 retrieve a text range object by using the createTextRange method of the IHTMLBodyElement, IHTMLInputHiddenElement, IHTMLInputTextElement, IHTMLTextAreaElement, or IHTMLButtonElement interface. 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.
IHTMLTxtRange Methods
HRESULT collapse(
VARIANT_BOOL Start
);
Creates an empty range either at the beginning or end of the current range.
See also expand
HRESULT compareEndPoints(
BSTR how,
IHTMLTxtRange *SourceRange,
long *ret
);
Compares two end points and returns -1, 0, or 1 for less than, equal, or greater than, respectively.
| StartToEnd | Compares the start point of the current range to the end point of the given range. |
| StartToStart | Compares the start point of the current range to the start point of the given range. |
| EndToStart | Compares the end point of the current range to the start point of the given range. |
| EndToEnd | Compares the end point of the current range to the end point of the given range. |
| -1 | The end point of SourceRange is less than that of the current range. |
| 0 | The end point of SourceRange is equal to that of the current range. |
| 1 | The end point of SourceRange is greater than that of the current range. |
See also setEndPoint
HRESULT duplicate(
IHTMLTxtRange **Duplicate
);
Creates a duplicate of the range.
See also IHTMLTxtRange
HRESULT execCommand(
BSTR cmdID,
VARIANT_BOOL showUI,
VARIANT value,
VARIANT_BOOL *pfRet
);
Executes the given command over the current selection or text range.
See also execCommandShowHelp
HRESULT execCommandShowHelp(
BSTR cmdID,
VARIANT_BOOL *pfRet
);
Displays help information for the given command identifier.
See also execCommand
HRESULT expand(
BSTR Unit,
VARIANT_BOOL *Success
);
Expands the range so that partial units are completed contained.
| Character | Expands a character. |
| Word | Expands a word. A word is a collection of characters terminated by a space or other white space character, such as a tab or return 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. |
See also collapse
HRESULT findText(
BSTR String,
long count,
long Flags,
VARIANT_BOOL *Success
);
Searches for text in the given range. Positions the start and end points of the range to encompass the search string.
HRESULT get_htmlText(
BSTR *p
);
Retrieves the HTML source as a valid HTML fragment.
This property corresponds to the fragment portion of the CF_HTML clipboard format. For more information about CF_HTML, see HTML Clipboard Format.
See also put_text
HRESULT get_text(
BSTR *p
);
Retrieves the text contained within the range.
The text is formatted within the current context of the document.
HRESULT getBookmark(
BSTR *Bookmark
);
Retrieves a bookmark (opaque string) that can be used with moveToBookmark to return to the same range.
See also moveToBookmark
HRESULT inRange(
IHTMLTxtRange *Range,
VARIANT_BOOL *InRange
);
Determines whether the specified range is within or equal to the current range.
See also IHTMLTxtRange
HRESULT isEqual(
IHTMLTxtRange *Range,
VARIANT_BOOL *IsEqual
);
Determines whether the specified range is equal to the current range.
See also inRange
HRESULT move(
BSTR Unit,
long Count,
long *ActualCount
);
Collapses the given text range and moves the empty range by the given number of units.
| 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. |
See also moveStart
HRESULT moveEnd(
BSTR Unit,
long Count,
long *ActualCount
);
Changes the scope of the range by moving the end position of the range.
| 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. |
HRESULT moveStart(
BSTR Unit,
long Count,
long *ActualCount
);
Changes the scope of the range by moving the start position of the range.
| 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. |
HRESULT moveToBookmark(
BSTR Bookmark,
VARIANT_BOOL *Success
);
Moves to a bookmark. Bookmarks are opaque strings that are created with the getBookmark method.
See also getBookmark
HRESULT moveToElementText(
IHTMLElement *element
);
Moves the text range so that the start and end positions of the range encompass the text in the given element.
See also IHTMLElement
HRESULT moveToPoint(
long x,
long y
);
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.
HRESULT parentElement(
IHTMLElement **Parent
);
Retrieves the parent element for the given text range. The parent element is the element that completely encloses the text in the range.
If the text range spans text in more than one element, the 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.
See also IHTMLElement
HRESULT pasteHTML(
BSTR html
);
Pastes HTML text into the given text range. The text completely replaces any previous text and HTML elements in the range.
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.
You cannot use this method while the document is loading. Wait for the onload event before attempting to use it.
HRESULT put_text(
BSTR v
);
Sets the text contained within the range.
The text is formatted within the current context of the document.
See also get_text
HRESULT queryCommandEnabled(
BSTR cmdID,
VARIANT_BOOL *pfRet
);
Determines whether the given command is currently available.
See also queryCommandSupported
HRESULT queryCommandIndeterm(
BSTR cmdID,
VARIANT_BOOL *pfRet
);
Determines whether the given command is in the indeterminate state.
HRESULT queryCommandState(
BSTR cmdID,
VARIANT_BOOL *pfRet
);
Retrieves the current status of the given command. The status indicates whether the command has been carried out on the object.
HRESULT queryCommandSupported(
BSTR cmdID,
VARIANT_BOOL *pfRet
);
Determines whether the given command is supported.
See also queryCommandEnabled
HRESULT queryCommandText(
BSTR cmdID,
BSTR *pcmdText
);
Returns the string associated with a command.
See also queryCommandValue
HRESULT queryCommandValue(
BSTR cmdID,
VARIANT *pcmdValue
);
Retrieves the current value of the given command.
See also queryCommandText
HRESULT scrollIntoView(
VARIANT_BOOL fStart
);
Scrolls the range into view, aligning it at either the top or bottom of the window.
Depending on the size of the given object and the current window, this method might not be able to put the item at the very top or very bottom, but will always position the object as close to the requested position as possible.
HRESULT select(
void
);
Makes the active selection equal to the current object.
HRESULT setEndPoint(
BSTR how,
IHTMLTxtRange *SourceRange
);
Sets the end point of one range based on the end point of another.
| StartToEnd | Sets the start point of the current range to the end point of the given range. |
| StartToStart | Sets the start point of the current range to the start point of the given range. |
| EndToStart | Sets the end point of the current range to the start point of the given range. |
| EndToEnd | Sets the end point of the current range to the end point of the given range. |
See also compareEndPoints
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.