In general, the TOM methods return the following standard values.īe aware that if the editing instance associated with a TOM object such as ITextRange is deleted, the TOM object becomes useless, and all its methods return CO_E_RELEASED. TOM Interface ConventionsĪll TOM methods return HRESULT values. The ITextRow interface together with the ITextRange::Move and ITextRange::Expand methods give the capability to insert, query, and change tables. In particular, the ITextDocument2 object can create an ITextStoryRanges2 object to enumerate the stories in the document in terms of ranges with start and end character position values that describe complete stories (such as, 0 and tomForward). With an ITextStoryRanges2 object, an explicit story object is not needed, since the each story is described by an ITextRange2 object. In particular, the ITextDocument object can create an ITextStoryRanges object to enumerate the stories in the document in terms of ranges with start and end character position values that describe complete stories (such as, 0 and tomForward). A text range object can modify itself in various ways, can return a duplicate of itself, and it can be commanded to copy its start and end character positions and its story pointer to the current selection.Īn explicit story object is not needed, since an ITextRange object can always be created to represent any given story. A text range object is different from spreadsheet and other range objects, which are defined by other kinds of offsets for example, row/column or graphics position (x, y). It does not exist independently of its parent story object, although its text can be copied to the clipboard or to other targets.
A scratch pad story is also used when saving the contents of a range that is the current copy source when the contents are about to be changed.Īn ITextRange2 object is defined by its start and end character-position offsets and a story object. A scratch pad story is used when translating between linearly formatted math expressions and a built-up form. Stories represent various parts of a document, such as the main text of the document, headers and footers, footnotes, annotations, and rich-text scratch pads. ITextStoryRanges2 Enumerator for stories in documentĪn ITextDocument2 object describes one or more contiguous ranges of text called stories. ITextStrings Rich-text strings collection ITextDisplays Displays collection (not yet defined) ITextRange2 Selection inherits all range methods ITextSelection2 Screen highlighted text range ITextRange2 Primary text interface: a range of text The TOM 2 objects have the following hierarchy. For example, ITextDocument2 inherits from ITextDocument. These capabilities help make text accessible to people with impaired vision, for example.Įach interface that has the 2 suffix inherits from the corresponding interface without the 2 suffix. The range and selection objects include screen-oriented methods that enable programs to examine text on screen or text that could be scrolled onto the screen. In addition to these three lower-level objects, TOM 2 has a selection object ( ITextSelection2), which is an ITextRange2 object with selection highlighting and some UI-oriented methods. ITextFont2 provides the programming equivalent of the Microsoft Word format-font dialog, and ITextPara2 provides the equivalent of the Word format-paragraph dialog.
If you need to add rich-text formatting, you can obtain ITextFont2 and ITextPara2 objects from an ITextRange2 object. For simple plain-text processing, you can obtain an ITextRange2 object from an ITextDocument2 object and do most everything with that. The top-level TOM 2 object is defined by the ITextDocument2 interface, which has methods for creating and retrieving objects lower in the object hierarchy. The updated TOM API includes support for new character and paragraph format properties, a table model, multiple selection, and inline object support for math and ruby. TOM version 2 (TOM 2) extends the original text object model the new interfaces are derived from the old ones. This topic provides a high-level overview of the TOM.
The Text Object Model (TOM) defines a set of text manipulation interfaces that are supported in varying degrees by several Microsoft text solutions, including the rich edit control.