Practical Uses for Editor Automation Objects

 < Free Open Study > 

The Document Object

The Document object refers to an open document or designer in the IDE. This basically means the code windows, form designers, and other windows that are not tool windows. Additionally, these windows have an area in which text can be edited. The Document object has properties, methods, and events, all of which can be called members, with which you can manipulate the active document or the document that you make the active document. If you are editing a text file in the Visual Studio editor, a TextDocument object is associated with it. The default property for a Document object is the Name property. You can reference the object by using oVB.Documents.Item() or oVB.ActiveDocument.

A simple example of referencing the active document in the IDE is shown in Listing 5-2. If you execute this code in an add-in, a message box will display the name of the active document or code window, including its full path, and a text message denoting whether the document is read-only or writable.

Listing 5-2: Document Object Example

start example
     Dim doc As Document     Dim s As String     Set doc = oVB.ActiveDocument     s = "Active Document: "     s = s & doc.Path & doc.Name & " is " & Iif(doc.ReadOnly, "Read-Only", _         "Writable")     MsgBox(s) 
end example

Manipulating the Code Editor

The Visual Studio .NET Code Editor is a sophisticated text editor that handles the text editing for the .NET languages, such VB .NET, Visual C++ .NET, and Visual C# .NET. Text is written to a buffer that displays in a text document. You can use the automation objects of the Visual Studio .NET Code Editor to control the operation of the text behind the scenes in the text buffer as well as the view.


Two entities are being controlled by the Visual Studio .NET Code Editor. First, there is the text displayed in the Code Editor that you are viewing. Second, there is a text buffer that is being manipulated behind the scenes. Two different automation objects control these two distinct objects, TextPoint and EditPoint, which I discuss in the following sections. TextSelection refers to the visible text selection.You can assign multiple TextSelection objects, but they always refer to the same selected text.You can have multiple EditPoint objects, and they can all have different positions in the text buffer.

You can use four major objects in the Code Editor to control the operation of the editor:

  • TextSelection object: Use this object to manipulate text in the visible document. The TextSelection object represents the insertion point where the caret is currently positioned or the selected text in the visible document.

  • TextPoint object: This object allows you to find locations in a document. You can use the TextPoint object to find line numbers, characters in a line, absolute character locations from the beginning of a document, and display columns. TextPoint objects operate on text displayed in a code editor, which is different from the EditPoint object (described next). When you edit a document, TextPoint objects do not move relative to their surrounding text. This means that if text is inserted before a TextPoint, the value of its AbsoluteCharOffset property is incremented to reflect its new location because the TextPoint has moved further down in the document.

  • EditPoint object: This object is similar to the TextPoint object, but it can be moved around and can modify text in the text buffer.

  • VirtualPoint object: This object is similar to the TextPoint object except that it has an added capability to query virtual space locations in a document. TextSelection.StartPoint and TextSelection.EndPoint return VirtualPoint objects. Virtual space is the empty space to the right of existing lines of text, and virtual points exist in this area.

The TextSelection and EditPoint objects are the two main objects with which you can manipulate code in the Visual Studio .NET Code Editor. You can use these objects to

  • Select, delete, add, and move text around in the text buffer or the visible code window.

  • Move the caret, or insertion point, around in the text buffer or the visible code window.

  • Indent text in the text buffer or the visible code window.

  • Add, remove, and navigate to bookmarks in the Code Editor.

  • Find and replace text based on a specified pattern.

  • Create an outline section in the text buffer and visible code window. To create an outline means to create a Region, which can be collapsed (hidden) or expanded.

  • Retrieve information about the text, such as the top and bottom of the document, text position, and so forth.

TextSelection Object

The properties and methods of the TextSelection object are analogous to editor commands in the Visual Studio IDE. Like the IDE, text selection operations are affected by the Code Editor's global state. Any operation attempting to modify a text document will fail if it affects any characters contained in a read-only block or if the text document itself is read-only.

If you place the code snippet in Listing 5-3 in an add-in, it will comment a selected block of Visual Basic code using the TextSelection object. This snippet is designed to be used in an add-in, but you could also use it in a macro by changing oVB to DTE.

Listing 5-3: Using the TextSelection Object

start example
     Dim sel As TextSelection = DTE.ActiveDocument.Selection()     Dim stpt As EditPoint = sel.TopPoint.CreateEditPoint()     Dim endpt As TextPoint = sel.BottomPoint     Try         Do While (stpt.LessThan(endpt))             stpt.Insert("'")             stpt.LineDown()             stpt.StartOfLine()         Loop     Catch     End Try 
end example

Listing 5-3 illustrates the use of several properties and methods of the TextSelection object:

  • Insert: Moves the selection object to the end of the current line.

  • LineDown: Moves the pointer to the selected line down the number of lines indicated by the parameter passed to the method. The default parameter is 1. Although it is not illustrated in this example, the LineUp method moves the line pointer up a number of lines.

  • StartOfLine: Moves the object to the beginning of the current line.

Listing 5-3 also illustrates the use of the EditPoint and TextPoint objects. The lines of code extracted from the larger snippet set a pointer to the beginning of the selection by creating an EditPoint object:

 Dim stpt As EditPoint = sel.TopPoint.CreateEditPoint() 

The next line creates a TextPoint object that points to the bottom of the selected text block:

 Dim endpt As TextPoint = sel.BottomPoint 

VirtualPoint Object

You can use the VirtualPoint object to manipulate text beyond the right margin (the left margin in bidirectional windows) of the text document. The code snippet in Listing 5-4 inserts a comment at the end of the line when the cursor is positioned anywhere in a line of code.

Listing 5-4: Insert Method of the TextSelection Object

start example
     Dim objSel As TextSelection = oVB.ActiveDocument.Selection     objSel.EndOfLine()     objSel.Insert(" ' End of line comment") 
end example

For example, you can position the cursor anywhere in the following line:

     intNum = 1 

Now if you execute the code snippet using the VirtualPoint object shown in the previous line of code, the line of code will look like this:

     intNum = 1 ' End of line comment 

With the VirtualPoint object, you can find and display (for illustrative purposes) several points within a selected line of code. For example, the block of code in Listing 5-5 will display three different values.

Listing 5-5: Using the VirtualPoint Object

start example
     ' VirtualPoint Example     ' Before running this example, open a text document.     Dim objSel As TextSelection = DTE.ActiveDocument.Selection     Dim objActive As VirtualPoint = objSel.ActivePoint     ' Collapse the selection to the beginning of the line.     objSel.StartOfLine()     ' objActive is "live", tied to the position of the actual selection,     ' so it will reflect the new position.     Dim iCol As Long = objActive.DisplayColumn     ' Move the selection to the end of the line.     objSel.EndOfLine()     ' Display the DisplayColumn     MsgBox("DisplayColumn: " & iCol & Chr(10) & _             "Line length: " & (objActive.DisplayColumn - iCol) & _             " display characters." & Chr(10) & _             "VirtualCharOffset value: " & objActive.VirtualCharOffset &_                 vbCr &"VirtualDisplayColumn value: " & _             objActive.VirtualDisplayColumn) 
end example

In Figure 5-1, you will note a block of code with the cursor positioned at the beginning of line 88 in the code editor.

click to expand
Figure 5-1: Code sample to use the VirtualPoint example


To illustrate the VirtualPoint object, I am using the macro facility to run the code example. It is easier to do that for this simple example than to use an add-in. The code will execute in an add-in in exactly the same way that it will execute in the Macro Explorer. The only modification required in the code is changing DTE to oVB. Chapter 8 explores the macro facility in depth.

If you run the VirtualPoint example code snippet in Listing 5-5, you will see the MessageBox shown in Figure 5-2.

Figure 5-2: VirtualPoint code example message

Now what has this example shown you? The first line of the MessageBox shows the original DisplayColumn. You can see in the VirtualPoint code snippet that the DisplayColumn is set to column 1 by this line of code:

     ' Collapse the selection to the beginning of the line.     objSel.StartOfLine() 

After capturing "iCol", the code shown next moves to the end of the line of code.

Next, the second line of the MessageBox indicates that there are 16 DisplayColumns, including the white space at the beginning of the line. The third line conveys the value of the VirtualCharOffset, which in this case is the same as the new DisplayColumn value. The VirtualCharOffset returns the number of characters the VirtualPoint is from the left side of a line in the document. The fourth line of the MessageBox conveys the value of the VirtualDisplayColumn. This is the display column of the current position.

 < Free Open Study > 

Writing Add-Ins for Visual Studio  .NET
Writing Add-Ins for Visual Studio .NET
ISBN: 1590590260
EAN: 2147483647
Year: 2002
Pages: 172
Authors: Les Smith © 2008-2017.
If you may any questions please contact us: