Visual Studio Tools for Office: Using C# with Excel, Word, Outlook, and InfoPath [Electronic resources] نسخه متنی

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.

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 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.

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.Chapters 21, "Working with XML in Excel," and 22, "Working with XML in Word"), not all documents need or want to use XML mapping.