VSTO Extensions to the Word and Excel Object Models

This chapter finishes with a detailed list of all new properties, events, and methods aggregated onto the Word and Excel objects by the VSTO aggregates, with the exception of the new data binding features (which are covered in Chapter 17, "VSTO Data Programming"). For Outlook, only the Application object is aggregated, and no new events, methods, or properties are added to that object.

As mentioned previously, every aggregated object now has a Tag property that you can use for any purpose you choose and an InnerObject property that you can use to access the aggregated object. In addition, each host control now has a Delete method that removes it (if it can be added dynamically at runtime) from its document or worksheet. Because every aggregating object has these properties and methods now, they are not mentioned again in the following topics.

The Word Document Class

VSTO Word projects have exactly one host item class. Every customized document class inherits from the aggregating class Microsoft.Office.Tools .Word.Document and implements the properties, methods, and events defined by the Microsoft.Office.Interop.Word.Document interface.

Document objects in VSTO source the new events shown in Table 13.1, all of which are raised by the Document object when the Application object raises the identically named event.

Table 13.1. New Events on VSTO's Aggregated Document Object

Event Name	Delegate	Notes
ActivateEvent	WindowEventHandler	From Application, renamed from WindowActivate
BeforeClose	CancelEventHandler	From Application
BeforeDoubleClick	ClickEventHandler	From Application
BeforePrint	CancelEventHandler	From Application
BeforeRightClick	ClickEventHandler	From Application
BeforeSave	SaveEventHandler	From Application
CloseEvent	DocumentEvents2_CloseEventHandler	From Document, renamed
Deactivate	WindowEventHandler	From Application
EPostageInsert	EventHandler	From Application
EPostagePropertyDialog	EventHandler	From Application
MailMergeAfterMerge	MailMergeAfterMergeEventHandler	From Application
MailMergeAfterRecordMerge	EventHandler	From Application
MailMergeBeforeMerge	EventHandler	From Application
MailMergeBeforeRecordMerge	CancelEventHandler	From Application
MailMergeDataSourceLoad	EventHandler	From Application
MailMergeDataSourceValidate	HandledEventHandler	From Application
MailMergeWindowSendTo-Custom	EventHandler	From Application
MailMergeWizardStateChange	MailMergeWizardStateChangeEventHandler	From Application
New	DocumentEvents2_NewEventHandler	From Document, delayed
Open	DocumentEvents2_OpenEventHandler	From Document, delayed
SelectionChange	SelectionEventHandler	From Application
Shutdown	EventHandler
Startup	EventHandler
SyncEvent	DocumentEvents2_Sync-EventHandler	From Application, renamed
WindowSize	WindowEventHandler	From Application
XMLAfterInsert	DocumentEvents2_XMLAfterInsertHandler	From Document
XMLBeforeDelete	DocumentEvents2_XMLBeforeDeleteHandler	From Document

Notice that the Sync and Close events have been renamed to prevent a naming conflict; C# does not allow a class to have an event and a method with the same name.

The Document class now has OnStartup and OnShutdown methods that force the Document object to source the Startup and Shutdown events.

The New and Open events are delayed so that they are not raised until the aggregate class is fully initialized. These events normally would be raised before any user-authored code could run. If user code does not run until after the event has been raised, however, how would you add an event handling delegate to listen to the event? Therefore, the events are delayed until after the customization's event binding code can run.

The event delegate types could use some additional explanation. All the event delegate types that begin with DocumentEvents2_ are from the Word PIA. The System.EventHandler, System.ComponentModel.CancelEventHandler, and System.ComponentModel.HandledEventHandler delegates are straightforward. All the remaining delegate types are defined in the Microsoft.Office.Tools.Word namespace and have signatures as follows:

Public Delegate Sub ClickEventHandler(ByVal sender As Object, _   ByVal e As Microsoft.Office.Tools.Word.ClickEventArgs) Public Delegate Sub MailMergeAfterMergeEventHandler( _   ByVal sender As Object, ByVal e As _   Microsoft.Office.Tools.Word.MailMergeAfterMergeEventArgs) Public Delegate Sub MailMergeWizardStateChangeEventHandler( _   ByVal sender As Object, ByVal e As _   Microsoft.Office.Tools.Word.MailMergeWizardStateChangeEventArgs) Public Delegate Sub SaveEventHandler(ByVal sender As Object, _   ByVal e As Microsoft.Office.Tools.Word.SaveEventArgs) Public Delegate Sub SelectionEventHandler(ByVal sender _   As Object, ByVal e As _   Microsoft.Office.Tools.Word.SelectionEventArgs) Public Delegate Sub WindowEventHandler(ByVal sender As Object, _   ByVal e As Microsoft.Office.Tools.Word.WindowEventArgs) 

The arguments classes of each are as follows:

• The ClickEventArgs class inherits from System.ComponentModel.CancelEventArgs and, therefore, has a Cancel property. It also exposes the selection that was clicked:

    Public Class ClickEventArgs     Inherits CancelEventArgs     Public Sub New(ByVal selection As Selection, _       ByVal cancel As Boolean)     Public ReadOnly Property Selection As Selection   End Class 

• The MailMergeAfterMergeEventArgs class exposes the new document created:

  Public Class MailMergeAfterMergeEventArgs   Inherits EventArgs   Public Sub New(ByVal newDocument As Document)   Public ReadOnly Property NewDocument As Document End Class 

• The MailMergeWizardStateChangeEventArgs class exposes the previous, current, and handled states:

  Public Class MailMergeWizardStateChangeEventArgs   Inherits EventArgs   Public Sub New(ByVal fromState As Integer, _     ByVal toState As Integer, ByVal handled As Boolean)   Public ReadOnly Property FromState As Integer   Public ReadOnly Property Handled As Boolean   Public ReadOnly Property ToState As Integer End Class 

• The SaveEventArgs class allows the handler to instruct the event source whether the Save As dialog box should display. This is also a cancelable event:

    Public Class SaveEventArgs     Inherits CancelEventArgs     Public Sub New(ByVal showSaveAsUI As Boolean, _       ByVal cancel As Boolean)     Public Property ShowSaveAsDialog As Boolean   End Class 

• The SelectionEventArgs class provides the selection that was changed:

  Public Class SelectionEventArgs   Inherits EventArgs   Public Sub New(ByVal selection As Selection)   Public ReadOnly Property Selection As Selection End Class 

• The WindowEventArgs class provides the window that was activated, deactivated, or resized:

  Public Class WindowEventArgs   Inherits EventArgs   Public Sub New(ByVal window As Window)   Public ReadOnly Property Window As Window End Class 

In addition to the new events, the Document object contains two new collections. First, as discussed earlier in this chapter, the Document object aggregate contains a collection of controls. Second, the Document object now contains a VSTOSmartTags collection (discussed further in Chapter 16, "Working with Smart Tags in VSTO").

The derived class can be customized further to add new events, methods, and properties. As you edit the document in the Word designer, any bookmarks or other host controls (buttons, check boxes, and so on) that you drop onto the design surface will be added as members of the document class. Similarly, any XML mapping added to the document will be added to the document class as either an XMLNode member (if the mapping is to a single node) or an XMLNodes member (if the mapping is to a repeatable node).

The document class has one additional new method: RemoveCustomization, which takes no arguments and has no return value. Calling this method on the aggregated document object removes the customization information from the document, so that after it is saved and reloaded the customization code will no longer run.

The ActiveWritingStyle and Compatibility properties from the Document PIA interface are parameterized properties. Because C# does not support calling parameterized properties, the document class uses helper classes that enable a C# developer to use parameterized indexers from C#. The properties ActiveWritingStyle and Compatibility use these helper classes. The syntax you use when calling these properties changes from the syntax that you would use with the Document object from the PIA

Me.Compatibility( _   Word.WdCompatibility.wdAlignTablesRowByRow) = True 

to the syntax that you would use with the aggregated Document class:

Me.Compatibility.Item( _   Word.WdCompatibility.wdAlignTablesRowByRow) = True 

Finally, the document class has a new property, ThisApplication, that refers to the Application object. This property exists to help migrate VSTO 2003 code that referred to a ThisApplication object. The document class also has an ActionsPane property, which is covered in detail in Chapter 15, "Working with the Actions Pane."

The Word Bookmark Host Control

Bookmark objects in the Word object model do not source any events. The aggregated host control Bookmark in VSTO sources the new events shown in Table 13.2.

Table 13.2. New Events on VSTO's Aggregated Bookmark Object

Event Name	Delegate
BeforeDoubleClick	ClickEventHandler
BeforeRightClick	ClickEventHandler
Deselected	SelectionEventHandler
Selected	SelectionEventHandler
SelectionChange	SelectionEventHandler

The delegate types and their corresponding argument classes are documented in the document class topic earlier in this chapter.

As a convenience for both view programming and data binding, bookmark host controls also aggregate more than 150 methods and properties of the Range object that they represent. These two lines of code, for example, are functionally identical:

columns = Me.Bookmark1.Range.Columns columns = Me.Bookmark1.Columns 

The methods and properties of the Range object aggregated onto the Bookmark object are for the most part straightforward proxies that just call the method or property accessor on the aggregated range, so almost all the methods will be functionally identical whether you call them from the Range or the Bookmark.

Three exceptions apply. First, setting the Text property on the Range object directly sometimes results in the bookmark itself being deleted by Word. If you set the Text property by calling the new property added to the Bookmark aggregate, it ensures that the bookmark is not deleted.

Second and third, the Information and XML properties from the PIA interface are parameterized properties. Because C# does not support calling parameterized properties, the bookmark host control uses helper classes that enables a C# developer to use parameterized indexers from C#. The properties InformationType and XMLType use these helper classes. The syntax you use when calling these properties changes from the syntax that you would use with the Range object from the PIA

info = Me.myBookmark.Range.Information(WdInformation.wdCapsLock) 

to the syntax that you would use with the aggregated Bookmark class:

info = Me.myBookmark.Information.Item(WdInformation.wdCapsLock) 

The Word XMLNode and XMLNodes Host Control Classes

When you map a schema into a Word document, element declarations that have a maxOccurs attribute in the schema equal to 1 are represented in the host item class as XMLNode objects. All others are represented as XMLNodes objects, because there could be more than one of them.

Table 13.3 shows the new events in VSTO that the XMLNode and XMLNodes objects source.

Table 13.3. New Events on VSTO's Aggregated XMLNode and XMLNodes Objects

Event Name	Delegate
AfterInsert	NodeInsertAndDeleteEventHandler
BeforeDelete	NodeInsertAndDeleteEventHandler
ContextEnter	ContextChangeEventHandler
ContextLeave	ContextChangeEventHandler
Deselect	ContextChangeEventHandler
Select	ContextChangeEventHandler
ValidationError	EventHandler

As you can see, we have two new delegate classes and, therefore, two new event argument classes. These events are normally sourced by the application object.

The delegates and event argument classes are all in the Microsoft .Office.Tools.Word namespace. The delegate classes are as follows:

  Public Delegate Sub ContextChangeEventHandler( _     ByVal sender As Object, _     ByVal e As Microsoft.Office.Tools.Word.ContextChangeEventArgs)   Public Delegate Sub NodeInsertAndDeleteEventHandler( _     ByVal sender As Object, ByVal e As _     Microsoft.Office.Tools.Word.NodeInsertAndDeleteEventArgs) 

• When a node is inserted or deleted, it is often interesting to know whether the change is a result of the user's inserting or deleting the element directly, or whether this is part of an undo or redo operation. Therefore, this flag is exposed on the event arguments class:

  Public NotInheritable Class NodeInsertAndDeleteEventArgs   Inherits EventArgs   Public Sub New(ByVal inUndoRedo As Boolean)   Public ReadOnly Property InUndoRedo As Boolean End Class 

• When a node is selected or deselected, the appropriate event is raised. A context change is a special kind of selection change in which the insertion point of the document moves from one XML node to another. Therefore, the event arguments for the ContextEnter and ContextLeave events specify both the node that was until recently the home of the insertion point and the new home:

Public Class ContextChangeEventArgs   Inherits EventArgs   Public Sub New(ByVal oldXMLNode As XMLNode, _     ByVal newXMLNode As XMLNode, ByVal selection As Selection, _     ByVal reason As Integer)   Public ReadOnly Property NewXMLNode As XMLNode   Public ReadOnly Property OldXMLNode As XMLNode   Public ReadOnly Property Reason As Integer   Public ReadOnly Property Selection As Selection End Class 

The XMLNode interface in the PIA has two parameterized properties, ValidationError and XML, that are not supported in C#. Therefore, these properties have been redefined to return helper classes that implement parameterized indexers instead. To specify the parameters for these parameters in Visual Basic, use the Item method as described with other modified parameterized properties in this chapter.

XMLNode objects also implement several convenient new methods for manipulating the XML bound to the document:

Public Sub Load(ByVal fileName As String) Public Sub LoadXml(ByVal xml As String) Public Sub LoadXml(ByVal document As XmlDocument) Public Sub LoadXml(ByVal xmlElement As XmlElement) 

All these methods take the contents of the XML in the argument and insert it into the given node and its children. The onus is on the caller, however, to ensure both that the XML inserted into the node corresponds to the schematized type of the node and that any child nodes exist and are mapped into the document appropriately. These methods neither create nor delete child nodes.

As a further convenience for both view and data programming, the XMLNode object provides a property that aggregates the Text property of the node's range:

Public Property NodeText As String 

Chapter 15, "Working with the ActionsPane," Chapter 17, "VSTO Data Programming," and Chapter 22, "Working with XML in Word," cover data binding scenarios and actions pane scenarios for XMLNode and XMLNodes objects in detail. That sums up the VSTO extensions to the Word object model. The extensions to the Excel object models are similar but somewhat more extensive because of the larger number of host controls.

The Excel Workbook Host Item Class

The aggregating workbook class raises the same 29 events as the aggregated workbook class, with the same delegate types. Aside from renaming the Activate event to ActivateEvent, so as to prevent a collision with the method of the same name, there are no changes to the events raised by the Workbook object.

The Workbook object does have two new events raised when the customization starts and shuts down:

Public Event Startup As EventHandler Public Event Shutdown As EventHandler 

The aggregated Workbook object also has two new methods, OnStartup and OnShutdown, that cause the workbook to raise the Startup and Shutdown events.

As with the Word document class, the Excel workbook class gains a ThisApplication property, which refers to the Excel Application object; an ActionsPane property, covered in Chapter 15, "Working with the Actions Pane"; and a VstoSmartTags collection, covered in Chapter 16, "Working with Smart Tags in VSTO." The Workbook object also has one additional new method: RemoveCustomization, which takes no arguments and has no return value. Calling this method on the aggregated Workbook object removes the customization information from the spreadsheet, so that after it is saved and reloaded, the customization code will no longer run.

There is only one other minor change to the view programming model of the workbook class. Because C# cannot use parameterized properties, the Colors property now returns a helper class (scoped to the host item class itself) that allows you to use a parameterized indexer.

The Excel Worksheet Host Item Class

Much like the workbook, the aggregating worksheet class does not have any major changes to its view programming model. The aggregating worksheet class raises the same eight events as the aggregated worksheet class, with the same delegate types. Aside from renaming the Activate event to ActivateEvent, so as to prevent a collision with the method of the same name, there are no changes to the events raised by the Worksheet object.

The Worksheet object does have two new events raised when the customization starts and shuts down:

Public Event Shutdown As EventHandler Public Event Startup As EventHandler 

The Worksheet object has two new methods, OnStartup and OnShutdown, that cause the worksheet to raise the Startup and Shutdown events. The worksheet also provides the Controls collection mentioned earlier in this chapter.

Worksheets classes can be customized by subclassing; the derived classes generated by the design have properties representing charts, named ranges, XML-mapped ranges, list objects, and other controls on each sheet.

There is only one other minor change to the view programming model of the worksheet class. Because C# cannot use parameterized properties, the Range property now returns a helper class (scoped to the worksheet class itself) that allows you to use a parameterized indexer.

The Excel Chart Sheet Host Item Class and Chart Host Control

Chart sheet host items and chart host controls are practically identical; the only difference between them as far as VSTO is concerned is that chart sheets are host items classes with their own designer and code-behind file. Charts, by contrast, are treated as controls embedded in a worksheet.

Both rename the Activate and Select events (to ActivateEvent and SelectEvent, respectively) to prevent name conflicts with the methods of the same name. The chart sheet host item class raises Startup and Shutdown events and has OnStartup and OnShutdown methods, just as the worksheet class does.

Both the chart and the chart sheet have a parameterized HasAxis property that cannot be called from C#. The property, therefore, now returns an instance of a helper class that allows you to use a parameterized indexer instead.

The Excel NamedRange, XmlMappedRange, and ListObject Host Controls

All three of these controls are special kinds of Range objects. They raise the new events shown in Table 13.4.

Table 13.4. New Events on VSTO's Aggregated NamedRange, XmlMappedRange, and ListObject Objects

Event Name	Delegate
BeforeDoubleClick	DocEvents_BeforeDoubleClickEventHandler
BeforeRightClick	DocEvents_BeforeRightClickEventHandler
Change	DocEvents_ChangeEventHandler
Deselected	DocEvents_SelectionChangeEventHandler
Selected	DocEvents_SelectionChangeEventHandler
SelectionChange	DocEvents_SelectionChangeEventHandler

All the event delegates are from the Microsoft.Office.Tools.Interop .Excel namespace in the Excel PIA.

The list object raises several more events in addition to those above, but because they all are primarily used to implement data binding functionality, Chapter 17, "VSTO Data Programming," covers them.

Many parameterized properties in both the NamedRange and XmlMappedRange interfaces are not supported by C#. To make this functionality usable more easily from C#, these properties now return helper classes (scoped to the NamedRange or XmlMappedRange classes themselves) that expose parameterized indexers. The properties that are changed in this way are End, AddressLocal, Address, Characters, Item, Offset, and Resize.

As a convenience for both view and data programming, NamedRange host controls also expose directly all the methods of the associated Name object:

• Public Property RefersTo As String

• Public Property RefersToLocal As String

• Public Property RefersToR1C1 As String

• Public Property RefersToR1C1Local As String

• Public ReadOnly Property RefersToRange As Range

If somehow, the NamedRange object has been bound to a non-named range, these will throw a NotSupportedException.

The NamedRange object also has a Name property that is somewhat confusing. The property-getter returns the Name object associated with this named range. If you pass a Name object to the setter, it will set the Name property, just as you would expect. If you pass a String, however, it will attempt to set the Name property of the underlying Name object.

The NamedRange host control also slightly changes the exception semantics of the Name property in two ways. First, in the standard Excel object model, setting the Name property of the name object of a named range to the name of another named range deletes the range, oddly enough; doing the same to a VSTO NamedRange host control raises an ArgumentException and does not delete the offending range.

Second, in the standard Excel object model, setting the Name property to an invalid string fails silently. The VSTO NamedRange object throws an ArgumentException if the supplied name is invalid.

Note

The XMLMappedRange and ListObject host controls do not aggregate the methods of the Name object or change the error-handling semantics of the name setter. The changes to the Name property semantics apply only to the NamedRange object.

XML mapped ranges and list objects are the Excel equivalents of the XMLNode and XMLNodes controls in Word. The XML mapped range represents a mapped singleton element, and the list object represents a set of rows. We cover data binding scenarios in Chapter 17, "VSTO Data Programming," and other XML scenarios in Excel in Chapter 21, "Working with XML in Excel." In this chapter, we just discuss their use as host controls.

The list object host control has one new property:

Public ReadOnly Property IsSelected As Boolean 

This property is most useful for determining whether there is an insert row. Excel does not display an insert row if the list object's range is not selected.

The list object host control also slightly changes the error-handling semantics of the DataBodyRange, HeaderRowRange, InsertRowRange, and TotalsRowRange. All these properties now return Nothing rather than throw an exception if you attempt to access the property on a list object that lacks a body, header, insert row, or totals row, respectively.

Chapter 17, "VSTO Data Programming," discusses other new properties and methods added to the list object used for data binding.