Interfaces Overview

The ITextDocument interface is the Text Object Model (TOM) top-level interface, which retrieves the active selection and range objects for any story in the document—whether active or not. It enables the application to:

Applications typically do not implement the ITextDocument interface. Microsoft text solutions, such as rich edit controls, implement ITextDocument as part of their TOM implementation.

Applications can retrieve an ITextDocument pointer from a rich edit control. To do this, send an EM_GETOLEINTERFACE message to retrieve an IRichEditOle object from a rich edit control. Then, call the object's IUnknown.QueryInterface method to retrieve an ITextDocument pointer.

Text Object Model (TOM) rich text-range attributes are accessed through a pair of dual interfaces, ITextFont and ITextPara.

The ITextFont and ITextPara interfaces encapsulate the functionality of the Microsoft Word Format Font and Paragraph dialog boxes, respectively. Both interfaces include a duplicate (Value) property that can return a duplicate of the attributes in a range object or transfer a set of attributes to a range. As such, they act like programmable format painters. For example, you could transfer all attributes from range r1 to range r2 except for making r2 bold and the font size 12 points by using the following subroutine.

ITextFont uses a special variable type, called tomBool, for rich-text attributes that have binary states. The tomBool type is different from the Boolean type because it can take four values: tomTrue, tomFalse, tomToggle, and tomUndefined. The tomTrue and tomFalse values indicate True and False. The tomToggle value is used to toggle a property. The tomUndefined value, more traditionally called NINCH, is a special no-input, no-change value that works with longs, floats, and COLOREFs. For strings, tomUndefined (or NINCH) is represented by the null string. For Set operations, using tomUndefined does not change the target property. For Put operations, tomUndefined means that the characters in the range have different values (it gives the grayed check box in property dialog boxes).

The rich edit control is able to accept and return all ITextFont properties intact, that is, without modification, both through TOM and through its Rich Text Format (RTF) converters. However, it cannot display the All Caps, Animation, Embossed, Imprint, Shadow, Small Caps, Hidden, Kerning, Outline, and Style font properties.

Applications typically do not implement the ITextFont interface. Microsoft text solutions, such as rich edit controls, implement ITextFont as part of their TOM implementation.

Applications can retrieve an ITextFont pointer for a text range by calling the ITextRange.Font property.

Text Object Model (TOM) rich text-range attributes are accessed through a pair of dual interfaces, ITextFont and ITextPara.

The ITextPara interface encapsulates the Word Paragraph dialog box. All measurements are given in floating-point points. The rich edit control is able to accept and return all ITextPara properties intact (that is, without modification), both through TOM and through its Rich Text Format (RTF) converters. However, the following properties have no effect on what the control displays:

Applications typically do not implement the ITextPara interface. Microsoft text solutions, such as rich edit controls implement ITextPara as part of their TOM implementation.

Applications can retrieve an ITextPara pointer for a text range by calling the ITextRange.GetPara method.

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.

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 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 ITextRange.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 would 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

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 ITextRange.Delete.

Some methods depend on a Unit argument, which can take on the predefined values listed in the following table.

Unit	Value	Meaning
tomCharacter	1	Character.
tomWord	2	Word.
tomSentence	3	Sentence.
tomParagraph	4	Paragraph.
tomLine	5	Line (on display).
tomStory	6	Story.
tomScreen	7	Screen (as for PAGE UP/PAGE DOWN).
tomSection	8	Section.
tomColumn	9	Table column.
tomRow	10	Table row.
tomWindow	11	Upper-left or lower-right of the window.
tomCell	12	Table cell.
tomCharFormat	13	Run of constant character formatting.
tomParaFormat	14	Run of constant paragraph formatting.
tomTable	15	Table.
tomObject	16	Embedded object.

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 &Hd and &H20), or the Unicode paragraph separator (&H2029). 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 &H2029). 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 ITextRange.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 ITextRange.Move, ITextRange.MoveEnd, and ITextRange.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 (towards the end of the story), and if Count is less than zero, the ends are moved backward (towards 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 ITextRange.MoveWhile, ITextRange.MoveEndWhile, and ITextRange.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 ITextRange.Move, ITextRange.MoveWhile, and ITextRange.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 ITextRange.MoveStart, ITextRange.MoveEnd, ITextRange.MoveStartWhile, ITextRange.MoveEndWhile, ITextRange.MoveStartUntil and ITextRange.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 ITextRange.MoveEnd method. To select a unit that corresponds to a noncontiguous range, such as tomObject, use the ITextRange.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 ITextDocument.Range method.

The selection is associated with some kind of view, and has some UI-oriented methods that allow one to emulate keyboard input. Thus, an application can use the ITextRange methods on a text selection, as well as the ITextSelection methods.

For keyboard input emulation, ranges used in selections use the concept of the active end, which is typically the end that was last moved. For example, if an ITextRange.Move* method operates on a range that is actually a text selection, the most recently moved end is the active one. The most familiar examples of the active end are those involving SHIFT+Arrow Key handling, where the active end is the one that moves. Accordingly, the ITextSelection methods include move methods for the active end, such as ITextSelection.MoveLeft or ITextSelection.MoveRight, and methods to get and set the active end status. These methods manipulate selections in ways similar to the standard cursor-keypad operations. This allows you to implement, for example, a macro recorder facility.

To see how the cursor-keypad methods work, see the following table. A given method corresponds to a cursor-keypad key with the CTRL and SHIFT keys. The Unit parameter is selected by pressing or not pressing the CTRL key, while the Extend parameter is selected by pressing or not pressing the SHIFT key. Note, ITextSelection.MoveUp and ITextSelection.MoveDown correspond to more than one keypad key. For more information, see the descriptions of the methods.

Method	Cursor-keypad key	Unit given by CTRL pressed (not pressed)	Extend given by SHIFT pressed (not pressed)
EndKey	END	tomStory (tomLine)	tomExtend (tomMove)
HomeKey	HOME	tomStory (tomLine)	tomExtend (tomMove)
MoveLeft	LEFT ARROW	tomWord (tomCharacter)	tomExtend (tomMove)
MoveRight	RIGHT ARROW	tomWord (tomCharacter)	tomExtend (tomMove)
MoveUp	UP ARROW	tomParagraph (tomLine)	tomExtend (tomMove)
MoveDown	DOWN ARROW	tomParagraph (tomLine)	tomExtend (tomMove)
MoveUp	PAGE UP	tomWindow (tomScreen)	tomExtend (tomMove)
MoveDown	PAGE DOWN	tomWindow (tomScreen)	tomExtend (tomMove)

Applications typically do not implement the ITextSelection interface. Instead, Microsoft text solutions such as rich edit controls implement ITextSelection as part of their Text Object Model (TOM) implementation.

Applications can retrieve an ITextSelection pointer by calling the ITextDocument.GetSelection method.

The purpose of the ITextStoryRanges interface is to enumerate the stories in an ITextDocument.

You get a pointer to an ITextStoryRanges collection by calling the ITextDocument.GetStoryRanges method. Each story obtained from this collection is represented by an ITextRange object that covers the whole story. Text Object Model (TOM) engines that only have a single story don't need to implement an ITextStoryRanges interface. Your code should only get a stories collection if ITextDocument.GetStoryCount returns a story count greater than one.