Working with the Actions Pane in Visual Studio Tools for Office
- Introduction to the Actions Pane
- Working with the ActionsPane Control
- Conclusion
This chapter is from the book
This chapter is from the book
This chapter is from the book
Introduction to the Actions Pane
Developing a solution that runs within an Office application provides considerable benefits because you can take advantage of the functionality that already exists in Office. Sometimes, however, it is hard to design a user interface that meets your needs, as most of the user interface space is controlled by the Office application. Office 2003 and VSTO introduce a number of new user interface capabilities, including the ability to use Windows Forms controls on the document. (See Chapter 14, "Using Windows Forms in VSTO," for more information on this capability.)
Placing a control on the document is not always the right paradigm for the user interface of your application. Putting a control onto the document can often lead to issues with layout when the controls are laid out relative to a range or paragraph, for example. If you use a button on a Word document, by default, it will be inline with the text. This means that when you reformat the document, the button will move with the text. Obviously, being able to move a control with the text is something that you would want if you are developing a flow-based user interface. But this model quickly becomes difficult when you are developing more traditional user interfaces. Things get even more complex if you start to consider what type of behavior you want when the user prints a document. Do you want your Windows Forms controls to be printed with the rest of the document, for example?
To address these user interface challenges, Office 2003 introduced the ability to put your own custom user interface into the Document Actions task pane of Word and Excel. The task pane is designed to provide a contextual user interface that is complementary to the document. Word, for example, provides a task pane that shows the styles and formats available in the current document and displays the style of the current selection in the document, as shown in Figure 15.1. To display the task pane, choose Task Pane from the View menu.
)
Figure 15.1 The Styles and Formatting task pane in Word.
The active task pane can be changed by making a selection from the drop-down list of available task panes at the top of the task pane, as shown in Figure 15.2. The active task pane is a per-document setting. You can have only one task pane visible at a time per document. The drop-down list shows several task panes that are built into Office. The task pane acts like a toolbar when you drag it to move it to another location. It can float above the document. It can also be docked to the left, top, right, or bottom of the application window space.
)
Figure 15.2 Selecting a task pane in Word.
Figure 15.2 lists several of the built-in task panes available in Word, including Getting Started, Help, and Clip Art. The task pane in the list that is customizable by your VSTO Word or Excel application is called the Document Actions task pane. In VSTO and in this book, we often refer to the Document Actions task pane as the actions pane, as kind of a contraction between the Document Actions and the task pane. ActionsPane is the name of the control in the VSTO programming model that you will use to put your own content in the Document Actions task pane. Note that the Document Actions task pane is listed as an available task pane for a document that has a VSTO customization associated with it that uses the ActionsPane control.
Listing 15.1 shows a simple VSTO Excel customization that displays a Windows Forms button control in the Document Actions task pane. In Excel, the ActionsPane control is a member of the ThisWorkbook class. Because this code is written in Sheet1, we use the Globals object to access the ThisWorkbook class and, from the ThisWorkbook class, to access the ActionsPane control. The ActionsPane control has a Controls collection that contains the controls that will be shown in the Document Actions task pane. We add to this collection of controls a Windows Forms button control we created previously. Note that just the action of adding a control to the Controls collection causes the Document Actions task pane to be shown at startup.
Example 15.1. A VSTO Excel Customization That Adds a Button to the Actions Pane
Public Class Sheet1
Public myButton As New Button
Private Sub Sheet1_Startup(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.Startup
myButton.Text = "Hello World"
Globals.ThisWorkbook.ActionsPane.Controls.Add(myButton)
End Sub
End Class
Figure 15.3 shows the result of running Listing 15.1. The Document Actions task pane is shown with a Windows Forms button displayed in the pane.
)
Figure 15.3 The result of running Listing 15.1.
Listing 15.2 shows a similar VSTO Word customization that displays a Windows Forms Button control in the Document Actions task pane. In Word, the ActionsPane control is a member of the ThisDocument class.
Example 15.2. A VSTO Word Customization That Uses the Actions Pane
Public Class ThisDocument
Public myButton As New Button
Private Sub ThisDocument_Startup(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.Startup
myButton.Text = "Hello World"
ActionsPane.Controls.Add(myButton)
End Sub
End Class
The Document Action task pane is actually part of a larger application development platform provided in Office 2003 called Smart Documents. The vision was that Smart Documents would integrate the new XML features available in Word and Excel and in the Document Actions task pane. This combination of XML and the Document Actions task pane provides an application development platform that makes it easier to build documents that are "smart" about their content and provide the appropriate user interface.
Smart Documents were designed primarily for the COM world. So although Smart Documents provided a powerful platform, they did not fit easily into the .NET development methodology. Why?
- The way you create a Smart Document is first to create a component that implements the ISmartDocument interface. This interface is rather COM-centric.
- To use a Smart Document, you must have XML schema mapped in your document. Although XML mapping provides considerable functionality to your application programming (see Chapter 21, "Working with XML in Excel," and Chapter 22, "Working with XML in Word"), not all documents need or want to use XML mapping.
- The Document Actions task pane supports only a small set of built-in controls and ActiveX controls. To use a Windows Forms control, you would have to register it as an ActiveX control and then attempt to get that to work within the Document Actions task pane. This requires COM registration and COM interop.
- The Smart Documents infrastructure requires you to create an expansion pack, which includes the following:
- - Manifest.xml, which contains links to all the components within the expansion pack
- - Document to be used
- - Schema for the Smart Document
- - Configuration XML file, which contains the definition of the controls to be used
VSTO provides the ActionsPane control to give you access to all the features provided by Smart Documents with a much more .NET development experience. You do not have to implement the ISmartDocument interface or use schema mapping in the document. You do not have to register Windows Forms controls in the registry so that they can act as ActiveX controls. You do not have to create an expansion pack. Because using the ActionsPane control is so much simpler than using Smart Documents and provides all the benefits, this book does not consider building Smart Documents in the old COM way.
The ActionsPane feature of VSTO is actually implemented under the covers as a specialized Smart Document solution; when you look at a customized VSTO document and examine the attached XML schemas, you will see that a schema called ActionsPane is attached automatically. This schema provides the plumbing to connect VSTO's ActionsPane control to the Smart Document platform. When you install the VSTO runtime (see Chapter 20, "Deployment"), the ActionsPane schema is also installed and registered with Excel and Word, enabling the ActionsPane control to access the Document Actions task pane.