The TextSelection Object

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 10-3 breaks down a TextSelection into its constituent parts.

As you can see in Figure 10-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 starting point and the endpoint of a mouse-drag selection; for example, the top selection in Figure 10-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 the AnchorPoint and ActivePoint objects.

Figure 10-3: Anatomy of a TextSelection object

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 10-6 lists the different ways you can retrieve a TextSelection object.

Table 10-6: Properties That Return a TextSelection Object

Property	Applies To
Selection	Document TextDocument TextPane and TextPane2 TextWindow Window and Window2

A Comparison of the TextSelection and EditPoint Objects

The TextSelection and EditPoint objects offer a bewildering array of editing methods, which are listed in Table 10-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 fine—it'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.

Table 10-7: TextSelection and EditPoint Methods
Open table as spreadsheet

Task	Methods in Common	TextSelection Only	EditPoint Only
Moving the insertion point	CharLeft, CharRight, EndOfDocument, EndOfLine, LineDown, LineUp, MoveToAbsoluteOffset, MoveToLineAndOffset, MoveToPoint, StartOfDocument, StartOfLine, WordLeft, WordRight	Collapse, GoToLine, MoveToDisplayColumn, PageDown, PageUp
Finding and retrieving text	FindPattern	FindText	GetLines, GetText
Selecting text		SelectAll, SelectLine
Modifying text	ChangeCase, Copy, Cut, Delete, DeleteWhitespace, Indent, Insert, InsertFromFile, PadToColumn, Paste, ReplacePattern, SmartFormat, Unindent	DeleteLeft, DestructiveInsert, NewLine, Tabify, Untabify	InsertNewLine[1], ReplaceText
Managing bookmarks	ClearBookmark, NextBookmark, PreviousBookmark, SetBookmark
Miscellaneous	OutlineSection	SwapAnchor	ReadOnly
[1]Defined by EditPoint2

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 editor—if 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 to move the insertion point to the next line of text in the buffer—if the line wraps underneath the insertion point, moving the insertion point to the next line in the view serves only to move the insertion point farther down the same line in the buffer.

The EditPoint object, on the other hand, bypasses the view and operates on the buffer directly. 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 it—if 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.