Inside Microsoft® Visual Studio® .NET 2003 [Electronic resources] نسخه متنی

The TextSelection Object

The TextSelection object pulls double duty as a representation of the caret in the editor window as well as a representation of the currently selected text. (You can think of the caret as a zero-length selection.) Because there can be only one selection in an editor window, there can be only one TextSelection object per document. Figure 11-3 breaks down a TextSelection into its constituent parts.

As you can see in Figure 11-3, four properties delineate a TextSelection: TopPoint, BottomPoint, AnchorPoint, and ActivePoint. Each of these properties returns a VirtualPoint object from one of the ends of the selected range. The TopPoint and BottomPoint properties always refer to the upper-left and bottom-right of the selection, respectively. The AnchorPoint and ActivePoint properties refer to the equivalent of the start and end points of a mouse-drag selection; for example, the top selection in Figure 11-3 would result from dragging the mouse from the beginning of using Extensibility; to the end of using EnvDTE;. You can determine the orientation of a TextSelection by checking its IsActiveEndGreater property, which returns True when ActivePoint equals BottomPoint. If the orientation isn't to your liking, you can flip it by calling the TextSelection.SwapAnchor method, which exchanges the positions of AnchorPoint and ActivePoint.

The TextSelection.IsEmpty property lets you know whether there's a selection, and you can retrieve the selected text from the Text property. If there's no selection, Text always returns an empty string. The converse doesn't hold, however, because Text returns an empty string for a virtual space selection. When a selection spans multiple lines, the TextRanges property holds a collection of TextRange objects, one for each line of the selection.

Table 11-6 lists the different ways you can get a TextSelection object.

A Comparison of TextSelection and EditPoint

The TextSelection and EditPoint objects offer a bewildering array of editing methods, which are listed in Table 11-7. Looking at the table, you'll see that TextSelection and EditPoint share the majority of their methods and have only a few seemingly minor differences, which makes choosing one over the other akin to choosing between the 52-feature Swiss army knife that comes with scissors and the 52-feature Swiss army knife that comes with a saw. In most circumstances, either knife will do just fineit's only in those particular moments when you need to gather firewood or do a little personal grooming that you suddenly realize that you can't cut down branches with scissors and you can't trim nose hairs with a saw. Using the editing objects is much the same in that you won't know whether you've chosen the right one for the job until it fails you.

The fundamental difference between the two objects is that the TextSelection object is view-based and the EditPoint object is buffer-based. The TextSelection object exists primarily to model user actions within the text editorif you can do it by hand in the editor, you can do it with the TextSelection object. (You can see this demonstrated every time you record a macro: the Macro Recorder translates changes that you make to text documents into sequences of TextSelection statements.) This emphasis on WYSIWYG functionality, however, means that the global view state can affect the behavior of a TextSelection method. For example, when line wrapping is enabled, you can't count on TextSelection.LineDown moving the insertion point to the next line of text in the bufferif the line wraps underneath the insertion point, then moving the insertion point to the next line in the view serves only to move the insertion point further down the same line in the buffer.

The EditPoint object, on the other hand, knows nothing about the view, so its operations are immune from the view's effects. Therefore, a call to EditPoint.LineDown always moves the EditPoint to the next line in the buffer, regardless of the line wrapping state. The only drawback of this insulation from the view is that you can't use EditPoint objects to affect virtual space.

So there you have itif you want your add-ins and macros to make use of the view state automatically, use TextSelection; if you want complete control over the text buffer, use EditPoint.