Text Windows and Window Panes
Text windows have their own specific object abstraction in addition to the generic Window object: the TextWindow object is used to represent text editor windows. To obtain a reference to a window’s TextWindow object, you retrieve the Window object’s value and assign it into a TextWindow type.
TextWindow textWindow = DTE.ActiveWindow.Object;
The TextWindow object doesn’t provide much functionality over and above the functionality found in the Window type; its real value is the access it provides to window panes.
Text editor windows in Visual Studio can be split into two panes; with a text editor open, simply select Split from the Window menu to create a new pane within the window. The TextWindow.ActivePane property returns a TextPane object representing the currently active pane in the window, and the TextWindow.Panes property provides access to all the panes within a text window.
//Get pane instance from collection
TextPane2 newPane = textWindow.Panes.Item(1);
//Get currently active pane
TextPane2 currPane = textWindow.ActivePane;
One of the more useful things you can do with the TextPane object is to scroll the client area of the pane (for example, the visible portion of the document within the pane) so that a specific range of text is visible. This is done via the TextPane.TryToShow method.
Here is the definition for the method.
bool TryToShow( [InAttribute] TextPoint Point,
[OptionalAttribute] [InAttribute] vsPaneShowHow How,
[OptionalAttribute] [InAttribute] Object PointOrCount)
The TextPoint parameter represents the specific location within the text document that you want visible in the text pane. (We discuss TextPoint objects in depth later in this chapter, in the section “Editing Text Documents.”) The vsPaneShowHow value specifies how the pane should behave when scrolling to the indicated location:
vsPaneShowHow.vsPaneShowCentered causes the pane to center the text/text selection in the middle of the pane (horizontally and vertically).
vsPaneShowHow.vsPaneShowTop places the text point at the top of the viewable region in the pane.
vsPaneShowHow.vsPaneShowAsIs shows the text point as is with no changes in horizontal or vertical orientation within the viewable region in the pane.
The last parameter, the PointOrCount object, is used to specify the end of the text area that you want displayed. If you provide an integer here, this represents a count of characters past the original text point; if you provide another text point, the selection is considered to be that text that resides between the two text points.
The TextPane object is also used to access the Incremental Search feature for a specific window pane. Listing 14.3 provides code that demonstrates one approach to searching a text window using the TextPane and IncrementalSearch classes.
LISTING 14.3 Controlling Incremental Search
using System;
using Extensibility;
using EnvDTE;
using EnvDTE80;
public class Connect : IDTExtensibility2
{
private DTE2 _applicationObject;
private AddIn _addInInstance;
public void IncrementalSearchDemo()
{
//Grab references to the active window;
//we assume, for this example, that the window
//is a text window.
Window window = _applicationObject.ActiveWindow;
//Grab a TextWindow instance that maps to our
//active window
TextWindow txtWindow = (TextWindow)window.Object;
//Get the active pane from the text window
TextPane2 pane = (TextPane2)txtWindow.ActivePane;
//Using the active pane, get an IncrementalSearch object
//for the pane
IncrementalSearch search = pane.IncrementalSearch;
//Try to find our IMessageMapper interface by looking
//for the string "IM"
//Configure the search:
// search forward in the document
// append the chars that we are searching for
// quit the search
search.StartForward();
search.AppendCharAndSearch((short)Strings.Asc('I'));
search.AppendCharAndSearch((short)Strings.Asc('M'));
//To remove us from incremental search mode,
//we can call IncrementalSearch.Exit()...
search.Exit();
}
}