The ITextRange objects are powerful editing and data-binding tools that allow a program to select text in a story and then examine or change that text.
The ITextRange interface inherits from the IDispatch interface. ITextRange also has these types of members:
The ITextRange interface has these methods.
Determines whether the specified range can be edited.
Determines if a data object can be pasted, using a specified format, into the current range.
Changes the case of letters in this range according to the Type parameter.
Collapses the specified text range into a degenerate point at either the beginning or end of the range.
Copies the text to a data object.
Cuts the plain or rich text to a data object or to the Clipboard, depending on the pVar parameter.
Mimics the DELETE and BACKSPACE keys, with and without the CTRL key depressed.
Moves this range's ends to the end of the last overlapping Unit in the range.
Expands this range so that any partial units it contains are completely contained.
Searches up to Count characters for the text given by bstr. The starting position and direction are also specified by Count, and the matching criteria are given by Flags.
Searches up to Count characters for the string, bstr, starting from the range's End cp. The search is subject to the comparison parameter, Flags. If the string is found, the End cp is changed to be the end of the matched string, and pLength is set equal to the length of the string. If the string is not found, the range is unchanged and pLength is set equal to zero.
Searches up to Count characters for the string, bstr, starting at the range's Start cp (cpFirst). The search is subject to the comparison parameter, Flags. If the string is found, the Start cp is changed to the matched string, and pLength is set equal to the length of the string. If the string is not found, the range is unchanged, and pLength is set equal to zero.
Gets the character at the start position of the range.
Gets a duplicate of this range object.
Retrieves a pointer to the embedded object at the start of the specified range, that is, at cpFirst. The range must either be an insertion point or it must select only the embedded object.
Gets the end character position of the range.
Gets an ITextFont object with the character attributes of the specified range.
Gets an ITextRange object with the specified range's formatted text.
Retrieves the story index of the Unit parameter at the specified range Start character position. The first Unit in a story has an index value of 1. The index of a Unit is the same for all character positions from that immediately preceding the Unit up to the last character in the Unit.
Gets an ITextPara object with the paragraph attributes of the specified range.
Retrieves screen coordinates for the start or end character position in the text range, along with the intra-line position.
Gets the start character position of the range.
Gets the count of characters in the range's story.
Get the type of the range's story.
Gets the plain text in this range. The Text property is the default property of the ITextRange interface.
Determines whether this range is within or at the same text as a specified range.
Determines whether this range's story is the same as a specified range's story.
Determines whether this range has the same character positions and story as those of a specified range.
Moves the insertion point forward or backward a specified number of units. If the range is nondegenerate, the range is collapsed to an insertion point at either end, depending on Count, and then is moved.
Moves the end position of the range.
Moves the range's end to the character position of the first character found that is in the set of characters specified by Cset, provided that the character is found within Count characters of the range's end.
Moves the end of the range either Count characters or just past all contiguous characters that are found in the set of characters specified by Cset, whichever is less.
Moves the start postion of the range the specified number of units in the specified direction.
Moves the start position of the range the position of the first character found that is in the set of characters specified by Cset, provided that the character is found within Count characters of the start position.
Moves the start position of the range either Count characters, or just past all contiguous characters that are found in the set of characters specified by Cset, whichever is less.
Searches up to Count characters for the first character in the set of characters specified by Cset. If a character is found, the range is collapsed to that point. The start of the search and the direction are also specified by Count.
Starts at a specified end of a range and searches while the characters belong to the set specified by Cset and while the number of characters is less than or equal to Count. The range is collapsed to an insertion point when a non-matching character is found.
Pastes text from a specified data object.
Scrolls the specified range into view.
Sets the start and end positions, and story values of the active selection, to those of this range.
Sets the character at the starting position of the range.
Sets the end position of the range.
Sets this range's character attributes to those of the specified ITextFont object.
Sets the formatted text of this range text to the formatted text of the specified range.
Changes this range to the specified unit of the story.
Sets the paragraph attributes of this range to those of the specified ITextPara object.
Changes the range based on a specified point at or up through (depending on Extend) the point (x, y) aligned according to Type.
Adjusts the range endpoints to the specified values.
Sets the character position for the start of this range.
Sets the text in this range.
Moves the range ends to the start of the first overlapping Unit in the range.
Multiple text ranges can be active and work cooperatively on the same story and evolve with the story. For example, if one text range deletes specified text before another text range, the latter tracks the change. In this sense, text ranges are similar to Microsoft Word bookmarks, which also track editing changes. However, bookmarks cannot edit text, while text ranges can. In addition, ranges let you manipulate text without changing the selection or Clipboard, both of which are valuable to end users. The ITextSelection interface inherits from ITextRange and adds some UI-oriented methods and properties as described in the section on ITextSelection.
You can look at a text range using methods based on character positions. Specifically, a text range is characterized by:
- The first character position, cpFirst, which points at an insertion point immediately preceding the first character (relative to the beginning of the story) in the range.
- The limit position, cpLim, which points at an insertion point immediately following the last character in the range.
The first character in a story has cpFirst = zero. If a cp argument has a value greater than the number of characters in the story, the number of characters in the story is used instead. If a cp argument is negative, zero is used instead. For those familiar with Microsoft Visual Basic for Applications, call the cpFirst property Start and the cpLim property End (even though the starting position of a range is also an end).
In the following figure, character positions are represented by the lines separating the letters. The corresponding character position values are given beneath the lines. The range starting at cpFirst = 5 and ending at cpLim = 7 contains the two-letter word is. If this figure depicts the complete text in a story, the story length is 30.
The length of a range is given by cpLim - cpFirst or equivalently by End - Start. A range with zero length is called a degenerate or empty range and has equal cp* values, that is, cpFirst = cpLim. An example of a degenerate range is the current insertion point. A non-null selection is an example of a nondegenerate range.
Suppose that the range from 5 to 7 indicated by shaded cells in the preceding figure is told to delete its text (see Delete), thereby turning itself into an insertion point. The range from 25 to 29 would automatically track its contents, namely the word text. The following figure shows the result.
In this figure, the range for text now has been automatically adjusted to have cpFirst = 23 and cpLim = 27. The owner of the range does not have to worry about updating the range character position values in the face of editing.
The names of the move methods indicate which end to move, but note that if any method attempts to move one range end past the other, both ends get moved to the target position. As a result, the insertion point is at the target position. The concept is that cpFirst and cpLim always have to obey the fundamental condition
0 <= cpFirst <= cpLim <= # characters in story
or equivalently for a range r, 0 <= r.Start <= r.End <= r.StoryLength, which is what you would expect from the names of these quantities.
Another important feature is that all stories contain an undeletable final CR (0xD) character at the end. So even an empty story has a single character, namely the final CR. A range can select this character, but cannot become an insertion point beyond it. To see how this works, try selecting the final CR in a Word document and then press the RIGHT ARROW key to collapse it. The directory tree will collapse before the final CR, but the CR cannot be deleted. The Text Object Model (TOM) functions the same way. So, if r.Start <= r.End, then r.End <= (r.StoryLength – 1). For a discussion about deleting a CR, see Delete.
Some methods depend on a Unit argument, which can take on the predefined values listed in the following table.
|tomLine||5||Line (on display).|
|tomScreen||7||Screen (as for PAGE UP/PAGE DOWN).|
|tomWindow||11||Upper-left or lower-right of the window.|
|tomCharFormat||13||Run of constant character formatting.|
|tomParaFormat||14||Run of constant paragraph formatting.|
Most of the Unit values are self-explanatory. However the following descriptions are provided for additional clarity.
The tomWord constant is an end of paragraph or a span of alphanumerics or punctuation including any blanks that follow. To get an on-screen feel for tomWord, watch how the caret moves when you press CTRL+RIGHT ARROW (—>) or CTRL+LEFT ARROW (<—) in a Word document.
The tomSentence constant describes a string of text that ends with a period, question mark, or exclamation mark and is followed either by one or more ASCII white space characters (9 through 0xd and 0x20), or the Unicode paragraph separator (0x2029). The trailing white space is part of the sentence. The last sentence in a story does not need to have a period, question mark, or exclamation mark. The start of a story qualifies as the start of a tomSentence, even if the string there does not qualify as a sentence grammatically. Other sentences must follow a sentence end and cannot begin with a period, question mark, or exclamation mark.
The tomParagraph constant is a string of text terminated by an end-of-paragraph mark (CRLF, CR, VT (for SHIFT+ENTER), LF, FF, or 0x2029). TOM engines always have an undeletable end-of-paragraph mark at the end of a story. Thus, all TOM stories automatically have at least one tomWord, one tomSentence, and one tomParagraph.
The tomLine constant corresponds to one line of text on a display, provided that a display is associated with the range. If no display is associated with a range, tomLine is treated as tomParagraph. A selection automatically has a display and a range that is a duplicate (see GetDuplicate). Other ranges may not have a display, depending on the TOM engine and context.
Methods that move one or both ends in terms of Unit, such as Move, MoveEnd, and MoveStart, depend on the signed Count argument. Except for the ITextSelection geometrical movement commands, if Count is greater than zero, the ends to be moved are moved forward (toward the end of the story), and if Count is less than zero, the ends are moved backward (toward the beginning). The default value of Count for these Move methods is 1. These methods attempt to move Count Units, but movement is never beyond the ends of the story.
Methods that move one or both ends by matching character strings or string patterns, such as MoveWhile, MoveEndWhile, and MoveStartWhile, can move up to a maximum number of characters given by the signed Count argument. If Count is greater than zero, the ends to be moved are moved forward, and if Count is less than zero, the ends are moved backward. Two special Count values, tomForward and tomBackward, are defined. These values are guaranteed to reach the end and the start of the story, respectively. The default value of Count is tomForward.
In Move* methods that turn a nondegenerate range into a degenerate one, such as Move, MoveWhile, and MoveUntil, cpFirst is changed if Count is negative and cpLim is changed if Count is positive. After this movement, the other end of the range is also moved to the new location. See the individual methods for more specific Count information. For nondegenerate ranges, the methods MoveStart, MoveEnd, MoveStartWhile, MoveEndWhile, MoveStartUntil and MoveEndUntil move either the starting position (Start) or the ending position (End).
To select a unit that corresponds to a contiguous range, such as a tomWord, tomSentence, and tomParagraph, use the MoveEnd method. To select a unit that corresponds to a noncontiguous range, such as tomObject, use the EndOf method, since the next object may occur after substantial intermediate text, if at all. To select a tomCell unit, the range must be inside a table.
Examples and further explanation of the Count and Unit arguments follow. Note that TOM engines may not support all of the units in the table above. For example, rich edit controls do not offer the concepts of sections, but rather return E_NOTIMPL when given tomSection. However if a TOM engine does support a unit, it has the index value given in the table.
Applications typically do not implement the ITextRange interface. Microsoft text solutions, such as rich edit controls, implement ITextRange as part of their TOM implementation.
Applications can retrieve an ITextRange pointer by calling the Range method.
Minimum supported client
Windows Vista [desktop apps only]
Minimum supported server
Windows Server 2003 [desktop apps only]