Point Objects

As you might guess, a point object represents a position in a text document. The automation object model gives you three point objects to choose from: TextPoint, VirtualPoint, and EditPoint.

The TextPoint Object

The TextPoint object embodies the fundamental attributes of a text document location; VirtualPoint and EditPoint implement the TextPoint interface, so all point objects have these fundamental attributes in common. The following list gives you an idea of what these attributes might be:

• Line information The Line property returns the number of the line that contains the point.

• Offset information The AbsoluteCharOffset and LineCharOffset properties return the number of characters between the point and the beginning of the document, and between the point and the beginning of the current line, respectively.

• Extreme information The AtStartOfDocument, AtEndOfDocument, AtStartOfLine, and AtEndOfLine properties allow you to determine whether the point is at the beginning or end of a document or line.

• Relational information The LessThan, EqualTo, and GreaterThan methods let you discover the relation of one point with respect to another.

The TextPoint object doesn't have methods that allow you to edit text directly. Instead, you either pass these point objects to editing methods or use them to create an EditPoint object at a particular location, which you can then use to edit text. Table 10-3 shows you the different ways to find a TextPoint object.

Table 10-3: How to Retrieve a TextPoint Object

Returned By	Applies To
StartPoint property	TextDocument TextPane TextRange
EndPoint property	TextDocument TextRange

The VirtualPoint Object

A VirtualPoint object represents a point in virtual space, which is a text editor feature that allows the insertion point to move indefinitely past the end of a line. When you type a character at a point in virtual space, the editor automatically fills in the space between the current end of the line and the new character. You can enable virtual space for all languages by opening the Tools—Options dialog box, selecting Text Editor—All Languages—General, and selecting the Enable Virtual Space check box in the Settings area. (See Figure 10-2.)

Figure 10-2: Enabling virtual space

Table 10-4 shows the different ways you can find a VirtualPoint object. As you can see from the table, VirtualPoint objects spring from TextSelection objects, which gives you a clue to their function; selections can extend into virtual space, so the TextSelection object needs VirtualPoint objects to keep track of endpoints that fall outside the text buffer.

Table 10-4: How to Retrieve a VirtualPoint Object

Returned By	Applies To
ActivePoint property	TextSelection
AnchorPoint property
BottomPoint property
TopPoint property

As with the TextPoint object, one of the VirtualPoint object's main uses involves the creation of EditPoint objects. Be aware, however, that a VirtualPoint object can't create an EditPoint object in virtual space—if you try, the EditPoint object gets created at the end of the current line instead. You can avoid those situations by using the following function, which tells you when a VirtualPoint object has strayed into virtual space:

 Function IsVirtualSpace(ByVal vrtPoint As VirtualPoint) As Boolean     ' Description: Returns whether the VirtualPoint lies in virtual space     Return vrtPoint.LineCharOffset <> vrtPoint.VirtualCharOffset End Function 

The VirtualPoint object defines a property named VirtualCharOffset that returns the distance between the point and the beginning of the line. The VirtualCharOffset property always has the same value as the LineCharOffset property, except when the point is in virtual space.

Lab: Exploring Virtual Space

The best way to understand virtual space and its effects on point objects is to test it for yourself. Here's a quick experiment:

1. Turn off virtual space in the editor.

2. Open a new text file, and type I am a fish. without pressing Enter.

3. Select the entire sentence by dragging the mouse from left to right. Notice that the editor won't extend the selection beyond the period.

4. Open the Output window and run the DisplayTextSelectionEditPoints macro. Observe that the DisplayColumn entries for TopPoint and BottomPoint are 1 and 13, respectively.

5. Run the DisplayTextSelectionVirtualPoints macro. Notice that the DisplayColumn entries for TopPoint and BottomPoint match those from the previous step.

6. Run the DisplayTextSelectionText macro, and observe that the output is "I am a fish."

When you disable virtual space, you confine VirtualPoint objects to the limits of the text buffer. Enable virtual space, however, and those same VirtualPoint objects can wander off to parts unknown, as we can see in the following steps:

1. Enable virtual space in the text editor.

2. Reselect the entire sentence, but this time extend the selection beyond its end.

3. Rerun the DisplayTextSelectionEditPoints and DisplayTextSelectionVirtualPoints macros. Notice that the EditPoint values remain unchanged, but the VirtualPoint's VirtualCharOffset and VirtualDisplayColumn values exceed those of the corresponding LineCharOffset and DisplayColumn values.

4. Run the DisplayTextSelectionText macro, and observe that its output is the same as before.

That last step shows that virtual space exists outside the text buffer; it also shows that virtual space doesn't count as selected text. Instead, virtual space allows for what you might call WYSINWYG editing—what you see isn't necessarily what you get.

The EditPoint Object

The EditPoint is the workhorse of the point objects. In addition to the TextPoint methods and properties, EditPoint has methods that let you automate every possible modification of the text buffer. Table 10-5 shows the different ways you can retrieve an EditPoint object.

Table 10-5: How to Retrieve an EditPoint Object

Returned By	Applies To
CreateEditPoint method	EditPoint TextPoint VirtualPoint TextDocument

We'll examine the EditPoint object's methods shortly, in the section titled "A Comparison of the TextSelection and EditPoint objects."