IHTMLTxtRange

IHTMLTxtRange


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
get_htmlText   put_text   get_text  
parentElement   duplicate   inRange  
isEqual   scrollIntoView   collapse  
expand   move   moveStart  
moveEnd   select   pasteHTML  
moveToElementText   setEndPoint   compareEndPoints  
findText   moveToPoint   getBookmark  
moveToBookmark   queryCommandSupported   queryCommandEnabled  
queryCommandState   queryCommandIndeterm   queryCommandText  
queryCommandValue   execCommand   execCommandShowHelp

IHTMLTxtRange::collapse

HRESULT collapse(
    VARIANT_BOOL Start 
);

Creates an empty range either at the beginning or end of the current range.

Start
Boolean value specifying where to create the empty range. TRUE creates an empty range at the beginning of the current range; FALSE creates it at the end.

See also expand

IHTMLTxtRange::compareEndPoints

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.

how
String describing the end points to compare. Can be one of these values:
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.
SourceRange
Interface pointer of the range object against which the current range is to be compared.
ret
Address of a variable that receives the result of the comparison. Can be one of these values:
-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

IHTMLTxtRange::duplicate

HRESULT duplicate(
    IHTMLTxtRange **Duplicate 
);

Creates a duplicate of the range.

Duplicate
Address of a variable that receives an interface pointer for the duplicate range.

See also IHTMLTxtRange

IHTMLTxtRange::execCommand

HRESULT execCommand(
    BSTR cmdID,
    VARIANT_BOOL showUI,
    VARIANT value,
    VARIANT_BOOL *pfRet
);

Executes the given command over the current selection or text range.

cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
showUI
Flag specifying whether to display a user interface if the command supports one. If TRUE, the command displays a user interface, if applicable; otherwise, it doesn't.
value
Value to pass to the command. Possible values depend on the value of cmdID.
pfRet
Address of a variable that receives TRUE if the function is successful, or FALSE otherwise.

See also execCommandShowHelp

IHTMLTxtRange::execCommandShowHelp

HRESULT execCommandShowHelp( 
    BSTR cmdID,
    VARIANT_BOOL *pfRet 
);

Displays help information for the given command identifier.

cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a variable that receives TRUE if successful, or FALSE otherwise.

See also execCommand

IHTMLTxtRange::expand

HRESULT expand(
    BSTR Unit,
    VARIANT_BOOL *Success 
);

Expands the range so that partial units are completed contained.

Unit
String specifying the unit by which to expand the range. Can be one of these values:
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.
Success
Address of a variable that receives TRUE if the the range was successfully expanded, or FALSE if not.

See also collapse

IHTMLTxtRange::findText

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.

String
String specifying the text to find.
count
Long integer that receives the count.
Flags
Long integer that receives the search flags.
Success
Address of a variable that receives TRUE if the text is found, or FALSE if not.

IHTMLTxtRange::get_htmlText

HRESULT get_htmlText( 
    BSTR *p 
);

Retrieves the HTML source as a valid HTML fragment.

p
Address of a variable that receives the HTML source.

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

IHTMLTxtRange::get_text

HRESULT get_text(
    BSTR *p 
);

Retrieves the text contained within the range.

p
Address of a variable that receives the text.

The text is formatted within the current context of the document.

IHTMLTxtRange::getBookmark

HRESULT getBookmark(
    BSTR *Bookmark 
);

Retrieves a bookmark (opaque string) that can be used with moveToBookmark to return to the same range.

Bookmark
Address of a variable that receives the bookmark if successful, or NULL otherwise.

See also moveToBookmark

IHTMLTxtRange::inRange

HRESULT inRange(
    IHTMLTxtRange *Range,
    VARIANT_BOOL *InRange 
);

Determines whether the specified range is within or equal to the current range.

Range
Interface pointer of the range to test.
InRange
Address of a variable that receives TRUE if Range is within the current range, or FALSE if not.

See also IHTMLTxtRange

IHTMLTxtRange::isEqual

HRESULT isEqual(
    IHTMLTxtRange *Range,
    VARIANT_BOOL *IsEqual 
);

Determines whether the specified range is equal to the current range.

Range
Interface pointer of the range to test.
IsEqual
Address of a variable that receives TRUE if Range is equal to the current range, or FALSE if not.

See also inRange

IHTMLTxtRange::move

HRESULT move(
    BSTR Unit,
    long Count,
    long *ActualCount 
);

Collapses the given text range and moves the empty range by the given number of units.

Unit
String specifying the units to move. Can be one of these values:
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
Integer specifying the number of units to move. This can be positive or negative.
ActualCount
Address of a variable that receives the actual number of units moved.

See also moveStart

IHTMLTxtRange::moveEnd

HRESULT moveEnd(
    BSTR Unit,
    long Count,
    long *ActualCount 
);

Changes the scope of the range by moving the end position of the range.

Unit
String specifying the units to move. Can be one of these values:
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
Integer specifying the number of units to move. This can be positive or negative.
ActualCount
Address of a variable that receives the actual number of units moved.

See also move, moveStart

IHTMLTxtRange::moveStart

HRESULT moveStart(
    BSTR Unit,
    long Count,
    long *ActualCount 
);

Changes the scope of the range by moving the start position of the range.

Unit
String specifying the units to move. Can be one of these values:
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
Integer specifying the number of units to move. This can be positive or negative.
ActualCount
Address of a variable that receives the actual number of units moved.

See also move, moveEnd

IHTMLTxtRange::moveToBookmark

HRESULT moveToBookmark( 
    BSTR Bookmark,
    VARIANT_BOOL *Success 
);

Moves to a bookmark. Bookmarks are opaque strings that are created with the getBookmark method.

Bookmark
String specifying the bookmark.
Success
Address of a variable that receives TRUE if successful, or FALSE otherwise.

See also getBookmark

IHTMLTxtRange::moveToElementText

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.

element
Interface pointer of an element.

See also IHTMLElement

IHTMLTxtRange::moveToPoint

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.

x
Integer specifying the x-coordinate, in pixels.
y
Integer specifying the y-coordinate, in pixels.

IHTMLTxtRange::parentElement

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.

Parent
Address of a variable that receives an interface pointer for the parent element.

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

IHTMLTxtRange::pasteHTML

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.

html
String specifying the HTML text to paste.

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.

IHTMLTxtRange::put_text

HRESULT put_text(
    BSTR v 
);

Sets the text contained within the range.

v
String specifying the text.

The text is formatted within the current context of the document.

See also get_text

IHTMLTxtRange::queryCommandEnabled

HRESULT queryCommandEnabled(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Determines whether the given command is currently available.

cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a variable that receives TRUE if the command is available, or FALSE otherwise.

See also queryCommandSupported

IHTMLTxtRange::queryCommandIndeterm

HRESULT queryCommandIndeterm(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Determines whether the given command is in the indeterminate state.

cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a variable that receives TRUE if the given command is in the indeterminate state, or FALSE otherwise.

IHTMLTxtRange::queryCommandState

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.

cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a variable that receives TRUE if the given command has been carried out, FALSE if it has not, or NULL if the function cannot determine the status of the command.

IHTMLTxtRange::queryCommandSupported

HRESULT queryCommandSupported(
    BSTR cmdID,
    VARIANT_BOOL *pfRet 
);

Determines whether the given command is supported.

cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a variable that receives TRUE if the command is supported, or FALSE otherwise.

See also queryCommandEnabled

IHTMLTxtRange::queryCommandText

HRESULT queryCommandText(
    BSTR cmdID,
    BSTR *pcmdText
);

Returns the string associated with a command.

cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pcmdText
Address of a string variable that receives the command text.

See also queryCommandValue

IHTMLTxtRange::queryCommandValue

HRESULT queryCommandValue(
    BSTR cmdID,
    VARIANT *pcmdValue
);

Retrieves the current value of the given command.

cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pcmdValue
Address of a variable that receives a string representing the command value. If the command is not supported, this variable receives NULL.

See also queryCommandText

IHTMLTxtRange::scrollIntoView

HRESULT scrollIntoView(
    VARIANT_BOOL fStart 
);

Scrolls the range into view, aligning it at either the top or bottom of the window.

fStart
Boolean value specifying the alignment of the range. TRUE aligns the range at the top of the window; FALSE aligns it at the bottom.

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.

IHTMLTxtRange::select

HRESULT select(
    void 
);

Makes the active selection equal to the current object.

IHTMLTxtRange::setEndPoint

HRESULT setEndPoint(
    BSTR how,
    IHTMLTxtRange *SourceRange
);

Sets the end point of one range based on the end point of another.

how
String describing the end points. Can be one of these values:
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.
SourceRange
Interface pointer of the range object to be used for setting the end point of the current range.

See also compareEndPoints

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.