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

The LineChanged Event

The automation object model defines a single event specific to editing: the LineChanged event. Having only one text-editing event at your disposal is both a blessing and a curse, analogous to owning a single flat screwdriver when half the world is built using Phillips screwsyou always know which tool you're going to use and you can disassemble just about anything, given time, but you sometimes find yourself wishing for a more varied toolbox.

The LineChanged event has three parameters to help you figure out why the event fired. The first two parameters, StartPoint and EndPoint, mark the beginning and end of the changes to the text buffer. You can use these TextPoint values to retrieve the changes, like so:

Dim text As String
text = StartPoint.CreateEditPoint.GetText(EndPoint)

And if you're ever curious about which document the changes belong to, you can follow the object hierarchy up a couple of levels to find the parent document:

Dim doc As Document
doc = StartPoint.Parent.Parent

The third parameter, Hint, is a bit flag that holds values from the vsT-extChanged enumeration (shown in Table 11-8). The flags set in Hint are evidence from the crime scene that you can piece together to recreate the actions leading up to the event. (In practice, the Hint parameter doesn't give you quite enough information to figure out exactly what led to the eventbut then, if it did, it wouldn't be called a hint.)

The LineChanged event doesn't really fire when the line changesthat is, it doesn't fire for each new character added or deleted from a line. Instead, the event fires when changes to a line are committed in some way, such as when the insertion point moves off the line, changes are saved to disk, or the document window loses focus. An undo context effectively disables this event until the undo context closes; afterwards, the event fires if any of the changes made within the undo context would have caused it to fire under normal circumstances (the insertion point moves off a changed line, the entire text buffer is replaced by an insert, and so forth). The event handler receives StartPoint and EndPoint values that reflect all uncommitted changes from before and during the undo context. Listing 11-2 demonstrates this effect.

Listing 11-2 Testing the effect of undo contexts on the LineChanged event

UndoContexts and LineChanged Events
Private Const title As String = "Text Editing Events"
<System.ContextStaticAttribute()> Public WithEvents _
TextEditorEvents1 As EnvDTE.TextEditorEvents
Sub LineChangedAndUndoContexts(Optional ByVal useUndoContext _
As String = "False")
' Description: Demonstrates the effect of undo contexts on the 
'              LineChanged event
TextEditorEvents1 = DTE.Events.TextEditorEvents()
Dim useUndo As Boolean = ToBoolean(useUndoContext)
' Create a new document
Dim txtDoc As TextDocument = GetTextDocument("LineChanged Test")
Dim editPnt As EditPoint = txtDoc.EndPoint.CreateEditPoint
' Insert text. Not a new line, so won't trigger LineChanged
editPnt.Insert("Beginning of document.")
If useUndo Then
Try
DTE.UndoContext.Open("LineChangedAndUndoContexts")
' Inside undo context, so new lines won't trigger 
' LineChanged until the undo context closes
editPnt.Insert(Environment.NewLine)
editPnt.Insert("Here's a new line." + Environment.NewLine)
DTE.UndoContext.Close()
Catch
End Try
Else
' No undo context, so new lines trigger LineChanged immediately
editPnt.Insert(Environment.NewLine)
editPnt.Insert("Here's a new line." + Environment.NewLine)
End If
End Sub
' LineChanged event handler
Public Sub TextEditorEvents1_LineChanged( _
ByVal StartPoint As EnvDTE.TextPoint, _
ByVal EndPoint As EnvDTE.TextPoint, _
ByVal Hint As Integer) Handles TextEditorEvents1.LineChanged
Dim output As New OutputWindowPaneEx(DTE, title)
output.WriteLine("--- TextEditorEvents1_LineChanged ---")
output.WriteLine("Changed text:")
output.WriteLine(StartPoint.CreateEditPoint.GetText(EndPoint))
output.WriteLine()
End Sub
Function ToBoolean(ByVal val As Object) As Boolean
Dim bool As Boolean = False
Try
' Convert the bool parameter
bool = System.Convert.ToBoolean(val)
Catch
End Try
Return bool
End Function

The LineChangedAndUndoContexts macro in Listing 11-2 creates a new document and adds a couple lines of text to it. Figure 11-5 shows the result of running this macro without using undo contextsthe LineChanged event fires once for each new line of text, which is the same as if you had typed in the lines by hand. Figure 11-6 shows what happens when you wrap the changes in an undo context. Because the new lines are created within an undo context, all the changes, including the ones before the undo context started, get rolled into one LineChanged event that fires after the undo context closes.

Multiple LineChanged Event Handlers

A LineChanged event handler can modify the text buffer without triggering LineChanged events, which allows you to add changes without fear of reentry. When multiple event handlers are involved, any changes that one event handler makes are seen by all event handlers downstream; the same Hint parameter gets passed along to each succeeding event handler, but the StartPoint and EndPoint parameters expand or contract to include any changes made by previous event handlers.