Programming Document-Level Customizations
Applies to |
|---|
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type
Microsoft Office version
For more information, see Features Available by Application and Project Type. |
When you extend Microsoft Office Word or Microsoft Office Excel by using a document-level customization, you can perform the following tasks:
Automate the Microsoft Office application by using the object model of the application.
Add controls to the surface of the document.
Call Visual Basic for Applications (VBA) code in the document from the customization assembly.
Call code in the customization assembly from VBA.
Manage certain aspects of the document while it is on a server that does not have Microsoft Office installed.
Customize the user interface (UI) of the application.
For general information about document-level customizations and other types of solutions you can create by using Visual Studio Tools for Office, see Office Solutions Development Overview.
Writing Code in Document-Level Projects
When you create a document-level project, Visual Studio Tools for Office automatically generates a class in the project that you can use to start writing your code. Visual Studio Tools for Office generates different classes for Word and Excel:
In document-level projects for Word, the class is called ThisDocument by default.
Document-level projects for Excel have multiple generated classes: one for the workbook itself, and one for each worksheet. By default, these classes have the following names:
ThisWorkbook
Sheet1
Sheet2
Sheet3
The generated class includes event handlers that are called when the document is opened or closed. To run code when the document is opened, add code to the Startup event handler. To run code just before the document is closed, add code to the Shutdown event handler. For more information, see Visual Studio Tools for Office Project Events.
Each of the automatically generated classes in a document-level project derives from a Visual Studio Tools for Office class called a host item. For example, the ThisDocument class in a Word project derives from the Microsoft.Office.Tools.Word.Document host item. For more information, see Host Items and Host Controls Overview.
Accessing the Object Model of the Host Application
To access the object model of the host application, use members of the generated class in your project. Each of these classes corresponds to a class in the object model of Excel or Word, and they contain most of the same properties, methods, and events. For example, the ThisDocument class in a document-level project for Word provides most of the same members as the Document class in the Word object model.
The following code example shows how to use the Word object model to save the document that is part of a document-level customization for Word. This example is intended to be run from the ThisDocument class.
Me.Save()
this.Save();
To do the same thing from outside the ThisDocument class, use the Globals object to access the ThisDocument class. For more information about the Globals object, see Global Access to Objects in Visual Studio Tools for Office Projects.
For example, you can add this code to an actions pane code file if you want to include a Save button in the actions pane UI.
Globals.ThisDocument.Save()
Globals.ThisDocument.Save();
Because the ThisDocument class derives from the Microsoft.Office.Tools.Word.Document host item, the Save method that is called in this code is really the Save method of the Microsoft.Office.Tools.Word.Document host item. This method corresponds to the Save method of the Document class in the Word object model.
For more information about using the object models of Word and Excel, see Word Object Model Overview and Excel Object Model Overview.
Adding Controls to Documents
To customize the UI of the document, you can add Windows Forms controls or host controls to the document surface. By combining different sets of controls and writing code, you can bind the controls to data, collect information from the user, and respond to user actions.
Host controls are classes that extend some of the objects in the Word and Excel object model. For example, the Microsoft.Office.Tools.Excel.ListObject host control provides all of the functionality of the ListObject in Excel. However, the Microsoft.Office.Tools.Excel.ListObject host control also has additional events and data binding capabilities.
For more information, see Host Items and Host Controls Overview and Windows Forms Controls on Office Documents Overview.
Combining VBA and Document-Level Customizations
You can use VBA code in a document that is part of a Visual Studio Tools for Office document-level customization. In all document-level projects, you can call VBA code in the document from the customization assembly. In document-level projects for the 2007 Microsoft Office system, you can also configure your project to enable VBA code in the document to call code in the customization assembly.
For more information, see Combining VBA and Document-Level Customizations.
Managing Documents on a Server
You can manage several different aspects of document-level customizations on a server that does not have Microsoft Office Word or Microsoft Office Excel installed. For example, you can access and modify data in the data cache of the document. You can also manage the Visual Studio Tools for Office customization assembly that is associated with the document. For example, you can programmatically remove the assembly from the document so that the document no longer runs your code, or you can programmatically attach an assembly to a document.
For more information, see Managing Documents on a Server by Using the ServerDocument Class.
Customizing the User Interface of Microsoft Office Applications
You can customize the UI of Word and Excel by using a document-level customization.
Both the 2007 and 2003 Releases of Microsoft Office
For Microsoft Office 2003 and the 2007 Microsoft Office system, you can customize the UI in the following ways:
Add host controls or Windows Forms controls to the document surface.
For more information, see Word Host Controls, Excel Host Controls, and Windows Forms Controls on Office Documents Overview.
Add an actions pane to the document.
For more information, see Actions Pane Overview.
Add smart tags to the document.
For more information, see Smart Tags Overview.
The 2007 Release
For Word 2007 and Excel 2007, you can also customize the UI in the following ways:
Add custom tabs to the Ribbon.
For more information, see Ribbon Overview.
Add custom groups to a built-in tab on the Ribbon.
For more information, see How to: Customize a Built-in Tab.
The 2003 Release
For Word 2003 and Excel 2003, you can also customize the UI in the following ways:
Add custom toolbars and toolbar items.
For more information, see How to: Create Office Toolbars Programmatically.
Add menus and menu items.
For more information, see How to: Create Office Menus Programmatically.
For more information about customizing the UI of Microsoft Office applications, see Office UI Customization.
See Also
Concepts
Combining VBA and Document-Level Customizations
Managing Documents on a Server by Using the ServerDocument Class
Getting Extended Objects from Native Office Objects in Document-Level Customizations