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. However, it is sometimes 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. For example, 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. 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 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. For example, do you want your Windows Forms controls to be printed with the rest of the document?

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. For example, Word 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 in the View menu.

Figure 15-1. The Styles and Formatting task pane in Word.

The active task pane can be changed by dropping down the drop-down menu at the top of the task pane and selecting from the available task panes, as shown in Figure 15-2. The active task pane is a per-document setting. You can only have one task pane visible at a time per document. The drop-down menu shows several task panes that are built in to 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 the Getting Started task pane, Help, Clip Art, and so on. 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 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 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 have previously created. Note that just the action of adding a control to the Controls collection causes the Document Actions task pane to be shown at startup.

Listing 15-1. A VSTO Excel Customization That Adds a Button to the Actions Pane

using System; using System.Data; using System.Drawing; using System.Windows.Forms; using Microsoft.VisualStudio.OfficeTools.Interop.Runtime; using Excel = Microsoft.Office.Interop.Excel; using Office = Microsoft.Office.Core; namespace ExcelWorkbook1 { public partial class Sheet1 { public Button myButton = new Button(); private void Sheet1_Startup(object sender, EventArgs e) { myButton.Text = "Hello World"; Globals.ThisWorkbook.ActionsPane.Controls.Add(myButton); } #region VSTO Designer generated code private void InternalStartup() { this.Startup += new EventHandler(Sheet1_Startup); } #endregion } }

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.

Listing 15-2. A VSTO Word Customization That Uses the Actions Pane

using System; using System.Data; using System.Drawing; using System.Windows.Forms; using Microsoft.VisualStudio.OfficeTools.Interop.Runtime; using Word = Microsoft.Office.Interop.Word; using Office = Microsoft.Office.Core; namespace WordDocument1 { public partial class ThisDocument { public Button myButton = new Button(); private void ThisDocument_Startup(object sender, EventArgs e) { myButton.Text = "Hello World"; ActionsPane.Controls.Add(myButton); } #region VSTO Designer generated code private void InternalStartup() { this.Startup += new EventHandler(ThisDocument_Startup); } #endregion } }

What About Smart Documents?

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 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 primarily designed for the COM world. So although smart documents provided a powerful platform, it did not fit easily into the .NET development methodology. Why?

1. The way you create a smart document is by first creating a component that implements the ISmartDocument interface. This interface is rather COM-centric.
2. 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 Chapters 21, "Working with XML in Excel," and 22, "Working with XML in Word"), not all documents need or want to use XML mapping.
3. The Document Actions task pane only supports 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.
4. The smart documents infrastructure requires you to create an expansion pack, which includes the following:

   Manifest.xmlcontains links to all the components within the expansion pack

   The document to be used

   Schema for the smart document

   Configuration XML filecontains the definition of the controls to be used

VSTO provides the ActionsPane control to enable 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 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 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 solutionwhen you look at a customized VSTO document and examine the attached XML schemas, you will see a schema is automatically attached called ActionsPane. 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.