Export (0) Print
Expand All

ITextRange interface

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.

Members

The ITextRange interface inherits from the IDispatch interface. ITextRange also has these types of members:

Methods

The ITextRange interface has these methods.

MethodDescription
CanEdit

Determines whether the specified range can be edited.

CanPaste

Determines if a data object can be pasted, using a specified format, into the current range.

ChangeCase

Changes the case of letters in this range according to the Type parameter.

Collapse

Collapses the specified text range into a degenerate point at either the beginning or end of the range.

Copy

Copies the text to a data object.

Cut

Cuts the plain or rich text to a data object or to the Clipboard, depending on the pVar parameter.

Delete

Mimics the DELETE and BACKSPACE keys, with and without the CTRL key depressed.

EndOf

Moves this range's ends to the end of the last overlapping Unit in the range.

Expand

Expands this range so that any partial units it contains are completely contained.

FindText

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.

FindTextEnd

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.

FindTextStart

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.

GetChar

Gets the character at the start position of the range.

GetDuplicate

Gets a duplicate of this range object.

GetEmbeddedObject

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.

GetEnd

Gets the end character position of the range.

GetFont

Gets an ITextFont object with the character attributes of the specified range.

GetFormattedText

Gets an ITextRange object with the specified range's formatted text.

GetIndex

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.

GetPara

Gets an ITextPara object with the paragraph attributes of the specified range.

GetPoint

Retrieves screen coordinates for the start or end character position in the text range, along with the intra-line position.

GetStart

Gets the start character position of the range.

GetStoryLength

Gets the count of characters in the range's story.

GetStoryType

Get the type of the range's story.

GetText

Gets the plain text in this range. The Text property is the default property of the ITextRange interface.

InRange

Determines whether this range is within or at the same text as a specified range.

InStory

Determines whether this range's story is the same as a specified range's story.

IsEqual

Determines whether this range has the same character positions and story as those of a specified range.

Move

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.

MoveEnd

Moves the end position of the range.

MoveEndUntil

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.

MoveEndWhile

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.

MoveStart

Moves the start postion of the range the specified number of units in the specified direction.

MoveStartUntil

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.

MoveStartWhile

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.

MoveUntil

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.

MoveWhile

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.

Paste

Pastes text from a specified data object.

ScrollIntoView

Scrolls the specified range into view.

Select

Sets the start and end positions, and story values of the active selection, to those of this range.

SetChar

Sets the character at the starting position of the range.

SetEnd

Sets the end position of the range.

SetFont

Sets this range's character attributes to those of the specified ITextFont object.

SetFormattedText

Sets the formatted text of this range text to the formatted text of the specified range.

SetIndex

Changes this range to the specified unit of the story.

SetPara

Sets the paragraph attributes of this range to those of the specified ITextPara object.

SetPoint

Changes the range based on a specified point at or up through (depending on Extend) the point (x, y) aligned according to Type.

SetRange

Adjusts the range endpoints to the specified values.

SetStart

Sets the character position for the start of this range.

SetText

Sets the text in this range.

StartOf

Moves the range ends to the start of the first overlapping Unit in the range.

 

Remarks

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.

Diagram of a 30-character text string, with two of the five words shaded

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.

Diagram of a 28-character text string, with one of the four words shaded

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.

UnitValueMeaning
tomCharacter1Character.
tomWord2Word.
tomSentence3Sentence.
tomParagraph4Paragraph.
tomLine5Line (on display).
tomStory6Story.
tomScreen7Screen (as for PAGE UP/PAGE DOWN).
tomSection8Section.
tomColumn9Table column.
tomRow10Table row.
tomWindow11Upper-left or lower-right of the window.
tomCell12Table cell.
tomCharFormat13Run of constant character formatting.
tomParaFormat14Run of constant paragraph formatting.
tomTable15Table.
tomObject16Embedded object.

 

Most of the Unit values are self-explanatory. However the following descriptions are provided for additional clarity.

tomWord

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.

tomSentence

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.

tomParagraph

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.

tomLine

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.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Tom.h

DLL

Msftedit.dll

See also

Conceptual
Text Object Model
Using The Text Object Model

 

 

Community Additions

ADD
Show:
© 2014 Microsoft