Walkthrough: Changing the Actions Pane According to User Context

Article
02/04/2013

Important The information set out in this topic regarding Microsoft Word is presented exclusively for the benefit and use of individuals and organizations who are located outside the United States and its territories or who are using, or developing programs that run on, Microsoft Word products that were licensed by Microsoft before January 2010, when Microsoft removed an implementation of particular functionality related to custom XML from Microsoft Word. This information regarding Microsoft Word may not be read or used by individuals or organizations in the United States or its territories who are using, or developing programs that run on, Microsoft Word products that were licensed by Microsoft after January 10, 2010; those products will not behave the same as products licensed before that date or purchased and licensed for use outside the United States.

This walkthrough demonstrates how to respond to XMLNode events. As a user moves the cursor through a document, controls on the actions pane are hidden or become visible.

Applies to: The information in this topic applies to document-level projects for Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type.

This walkthrough illustrates the following tasks:

Adding controls to the actions pane.
Showing the actions pane when the application opens.
Hiding and showing controls on the actions pane based on user actions in XML nodes.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

Prerequisites

You need the following components to complete this walkthrough:

An edition of Visual Studio 2010 that includes the Microsoft Office developer tools. For more information, see [Configuring a Computer to Develop Office Solutions](bb398242\(v=vs.100\).md).

Word 2007 or Word 2010.

Creating the Project

The first step is to create a Word document project.

To create a new project

Create a Word document project with the name My Dynamic Actions Pane. In the wizard, select Create a new document. For more information, see How to: Create Office Projects in Visual Studio.

Visual Studio opens the new Word document in the designer and adds the My Dynamic Actions Pane project to Solution Explorer.

Creating a Schema to Map to the Document

To create the XML nodes, drag elements from an XML schema to the document. First create a schema file, then create a document that corresponds to the schema, and then map the elements to the document.

To create the XML schema

Select the My Dynamic Actions Pane project in Solution Explorer.
On the Project menu, click Add New Item.

The Add New Item dialog box appears.
In the Templates pane, select XML Schema.
Name the schema ActionsPaneSample.xsd and click Add.
In Solution Explorer, right-click ActionsPaneSample.xsd, and then click Open With.
In the Open With dialog box, select XML Editor, and then click OK.

Replace the text in the XML editor with the following text.

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema targetNamespace="https://schemas.microsoft.com/vsto/samples" elementFormDefault="qualified"
    xmlns="https://schemas.microsoft.com/vsto/samples"
    xmlns:mstns="https://schemas.microsoft.com/vsto/samples"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="Sample" type="SampleType"></xs:element>
  <xs:complexType name="SampleType">
    <xs:all>
      <xs:element name="Insert" type="InsertType" minOccurs="0" maxOccurs="1" />
      <xs:element name="Table" type="xs:string" minOccurs="0" maxOccurs="1" />
    </xs:all>
  </xs:complexType>
  <xs:complexType name="InsertType">
    <xs:sequence>
      <xs:element name="MemoTo" type="xs:string" minOccurs="1" maxOccurs="1"/>
      <xs:element name="MemoFrom" type="xs:string" minOccurs="1" maxOccurs="1"/>
      <xs:element name="MemoSubject" type="xs:string" minOccurs="1" maxOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Save your project.

Adding Text and XML to the Document

The document for this walkthrough is in the form of a memorandum. Add text to the document, and then map XML elements to places in the document.

To add text to your document

In Solution Explorer, right-click ThisDocument.cs or ThisDocument.vb, and then click View Designer.
Add the following text to your Word document.

MEMORANDUM

To:

From:

Subject:

The following table lists the contact information you requested:

Name

Address

City

State

Postal Code

Nancy Davolio

507 - 20th Ave. E., Apt. 2A

Seattle

WA

98122

Next, map XML elements to the text in the memorandum. An XMLNode control is created for each XML element that you map. The XMLNode control is named by appending the parent and child element names to the word Node. For example, if you map the Insert element from the schema above, it is named SampleInsertNode. For more information about controls, see Host Items and Host Controls Overview.

To attach the schema to your document

On the Ribbon, click the Developer tab.

Note

If the Developer tab is not visible, you must first show it. For more information, see How to: Show the Developer Tab on the Ribbon.
In the XML group, click Schema.

The Templates and Add-ins dialog box opens.
In the Templates and Add-ins dialog box, click the XML Schema tab, and then click Add Schema.
Browse to the ActionsPaneSample.xsd schema you created earlier, which is located in your project directory, and click Open.
Click OK in the Schema Settings dialog box.
Click OK to close the Templates and Add-ins dialog box.

The XML Structure task pane opens.

To map XML elements to your document

Click the Sample element in the XML Structure task pane.
Click Apply to Entire Document when prompted.
Select the three lines of text To, From, and Subject, and click the Insert element in the XML Structure task pane.
Place your cursor after To:, press the TAB key twice, and click the MemoTo element to insert it.
Place your cursor after From:, press the TAB key twice, and click the MemoFrom element.
Place your cursor after Subject:, press the TAB key once, and click the MemoSubject element.
Select the table so that the entire table is highlighted, and click the Table element to apply it.

The XML tags appear within the table cells.
Clear the Show XML tags in the document check box.
Click XML Options at the bottom of the XML Structure task pane.
Select the Ignore mixed content check box, and click OK.
Close the XML Structure task pane.

Adding Controls to the Actions Pane

To design the layout of controls on the actions pane, you use the designer of a control called the actions pane control, which is basically the same as a user control. You can drag other controls, such as buttons and text boxes, onto the actions pane control and arrange them. To change the actions pane according to user context, you add and design an actions pane control for each context, and then show and hide them as appropriate.

This walkthrough uses three actions pane controls. The first actions pane control contains three text boxes and a button so users can enter data and add it to the document. The second actions pane control contains a button that opens the Table Properties dialog box. The third actions pane control contains a check box that shows all controls on the actions pane, regardless of where the cursor is in the document.

To add an actions pane control

Select the My Dynamic Actions Pane project in Solution Explorer.
On the Project menu, click Add New Item.
In the Add New Item dialog box, select Actions Pane Control, name it AddTextControl, and click Add.
Change the Size property of the actions pane control to 170, 135.

To add Windows Forms controls to the first actions pane control

From the Windows Forms tab of the Toolbox, drag a Label control to AddTextControl, and change the Text property to To:.
Add a Textbox control to AddTextControl and change the following properties.

Property

Value

Name

toBox

Size

110, 20
Add a second Label control to AddTextControl, and change the Text property to From:.
Add a second Textbox control to AddTextControl and change the following properties.

Property

Value

Name

fromBox

Size

110, 20
Add a third Label control to AddTextControl under the previous text box, and change the Text property to Subject:.
Add a third Textbox control to AddTextControl next to the previous label, and change the following properties.

Property

Value

Name

subjectBox

Multiline

True

Size

110, 40
Resize the subjectBox text box to enable multiple lines.
Add a Button control to AddTextControl and change the following properties.

Property

Value

Name

insertText

Text

Insert

Property	Value
Name	toBox
Size	110, 20

Property	Value
Name	fromBox
Size	110, 20

Property	Value
Name	subjectBox
Multiline	True
Size	110, 40

Property	Value
Name	insertText
Text	Insert

To create the second actions pane control

Add a second actions pane control to your project and name it ShowPropertiesControl.
Change the Size property of the actions pane control to 170, 50.
From the Windows Forms tab of the Toolbox, drag a Button control to ShowPropertiesControl and change the following properties.

Property

Value

Name

tableProperties

Text

Table Properties

Enabled

False

Size

100, 23
For C#, change the Modifiers property of the button to Internal.

Property	Value
Name	tableProperties
Text	Table Properties
Enabled	False
Size	100, 23

To create the third actions pane control

Add a third actions pane control to your project and name it ShowAllControl.
Change the Size property of the actions pane control to 170, 75.
From the Windows Forms tab of the Toolbox, add a GroupBox control to ShowAllControl and change the Text property to My Actions Pane.
Add a CheckBox control to ShowAllControl on top of the group box and change the following properties.

Property

Value

Name

showCheck

Text

Show All Controls
For C#, change the Modifiers property of the check box to Internal.

Property	Value
Name	showCheck
Text	Show All Controls

Adding Code to Respond to User Context

Now you can write code to show the actions pane, and add and remove actions pane controls according to the cursor location in the document. The code goes in the event handlers of the XMLNode controls.

To add code to XMLNode control events

In Solution Explorer, right-click ThisDocument.vb or ThisDocument.cs, and then click View Code.

Create a variable reference for each actions pane control in the declarations section of ThisDocument.

Dim addText As New AddTextControl
Dim showProperties As New ShowPropertiesControl
Dim showAll As New ShowAllControl

Friend WithEvents showCheck As System.Windows.Forms.CheckBox

private AddTextControl addText = new AddTextControl();
private ShowPropertiesControl showProperties = new ShowPropertiesControl();
private ShowAllControl showAll = new ShowAllControl();

In the Startup event handler of ThisDocument, write the following code to add the ShowAllControl control and show the actions pane.
```
Me.ActionsPane.Controls.Add(showAll)
showCheck = showAll.showCheck
```
```
this.ActionsPane.Controls.Add(showAll);
```
Note

The order in which you add controls to the actions pane determines their placement. If you have a control that will always be visible at the top of the actions pane, you should add it first. Order is also dependent on the StackOrder property of the actions pane. For more information, see How to: Manage Control Layout on Actions Panes.

Add the following code to the ContextEnter event handler of the SampleInsertNode control.

Private Sub SampleInsertNode_ContextEnter(ByVal sender As Object, _
    ByVal e As Microsoft.Office.Tools.Word.ContextChangeEventArgs) _
    Handles SampleInsertNode.ContextEnter

    If showAll.showCheck.Checked = False Then
        Me.ActionsPane.Controls.Add(addText)
        Me.ActionsPane.Controls.Remove(showProperties)
    End If
End Sub

private void SampleInsertNode_ContextEnter(object sender,
    Microsoft.Office.Tools.Word.ContextChangeEventArgs e)
{
    if (showAll.showCheck.Checked == false)
    {
        this.ActionsPane.Controls.Add(addText);
        this.ActionsPane.Controls.Remove(showProperties);
    }
}

Add the following code to the ContextLeave event handler of the SampleInsertNode control to hide the control after the user has moved the cursor outside of this XML node.

Private Sub SampleInsertNode_ContextLeave(ByVal sender As Object, _
    ByVal e As Microsoft.Office.Tools.Word.ContextChangeEventArgs) _
    Handles SampleInsertNode.ContextLeave

    If showAll.showCheck.Checked = False Then
        Me.ActionsPane.Controls.Remove(addText)
    End If
End Sub

private void SampleInsertNode_ContextLeave(object sender,
    Microsoft.Office.Tools.Word.ContextChangeEventArgs e)
{
    if (showAll.showCheck.Checked == false)
    {
        this.ActionsPane.Controls.Remove(addText);
    }
}

Add the following code to the ContextEnter event handler of the SampleTableNode control.

Private Sub SampleTableNode_ContextEnter(ByVal sender As Object, _
    ByVal e As Microsoft.Office.Tools.Word.ContextChangeEventArgs) _
    Handles SampleTableNode.ContextEnter

    If showAll.showCheck.Checked = False Then
        Me.ActionsPane.Controls.Remove(addText)
        Me.ActionsPane.Controls.Add(showProperties)
    End If

    showProperties.tableProperties.Enabled = True
End Sub

private void SampleTableNode_ContextEnter(object sender,
    Microsoft.Office.Tools.Word.ContextChangeEventArgs e)
{
    if (showAll.showCheck.Checked == false)
    {
        this.ActionsPane.Controls.Remove(addText);
        this.ActionsPane.Controls.Add(showProperties);
    }
    showProperties.tableProperties.Enabled = true;
}

Add the following code to the ContextLeave event handler of the SampleTableNode control to hide the control after the user has moved the cursor outside of this XML node.

Private Sub SampleTableNode_ContextLeave(ByVal sender As Object, _
    ByVal e As Microsoft.Office.Tools.Word.ContextChangeEventArgs) _
    Handles SampleTableNode.ContextLeave

    If showAll.showCheck.Checked = False Then
        Me.ActionsPane.Controls.Remove(showProperties)
    End If

    showProperties.tableProperties.Enabled = False
End Sub

private void SampleTableNode_ContextLeave(object sender,
    Microsoft.Office.Tools.Word.ContextChangeEventArgs e)
{
    if (showAll.showCheck.Checked == false)
    {
        this.ActionsPane.Controls.Remove(showProperties);
    }
    showProperties.tableProperties.Enabled = false;
}

In C#, you must add event handlers for the XMLNode controls. You can place this code in the Startup event handler of ThisDocument. For information about creating event handlers, see How to: Create Event Handlers in Office Projects.

this.SampleInsertNode.ContextEnter +=new Microsoft.Office.Tools.Word.
    ContextChangeEventHandler(SampleInsertNode_ContextEnter); 

this.SampleInsertNode.ContextLeave += new Microsoft.Office.Tools.Word.
    ContextChangeEventHandler(SampleInsertNode_ContextLeave);

this.SampleTableNode.ContextEnter += new Microsoft.Office.Tools.Word.
    ContextChangeEventHandler(SampleTableNode_ContextEnter);

this.SampleTableNode.ContextLeave += new Microsoft.Office.Tools.Word.
    ContextChangeEventHandler(SampleTableNode_ContextLeave);

Checkpoint

Save your project and verify that the actions pane controls change as you move your cursor through the document.

To test your project

Press F5 to run your project.
Move your insertion point to the word To and verify that the addText actions pane control is visible on the actions pane.
Move your insertion point to inside the table and verify that the showProperties actions pane control is visible on the actions pane.
Move your insertion point to the word MEMORANDUM and verify that neither the addText nor the showProperties actions pane controls are visible on the actions pane.

Adding Code to Respond to Control Events on the Actions Pane

So far, the controls on the actions pane do not do anything. The last step is to write code to show all controls, insert text, and show the Table Properties dialog box.

To show all controls on the actions pane

Add the following code to ThisDocument.

Private Sub showCheck_CheckStateChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) _
    Handles showCheck.CheckStateChanged

    If showAll.showCheck.Checked = True Then
        Me.ActionsPane.Controls.Add(addText)
        Me.ActionsPane.Controls.Add(showProperties)
    Else
        Me.ActionsPane.Controls.Remove(addText)
        Me.ActionsPane.Controls.Remove(showProperties)
    End If
End Sub

private void showCheck_CheckStateChanged(object sender, EventArgs e)
{
    if (showAll.showCheck.Checked)
    {
        this.ActionsPane.Controls.Add(addText);
        this.ActionsPane.Controls.Add(showProperties);
    }
    else
    {
        this.ActionsPane.Controls.Remove(addText);
        this.ActionsPane.Controls.Remove(showProperties);
    }
}

In C#, you must add an event handler for the checkbox control. You can place this code in the Startup event handler of ThisDocument.
```
showAll.showCheck.CheckStateChanged += new EventHandler(showCheck_CheckStateChanged);
```

To insert text when the Insert button is clicked

In Solution Explorer, right-click AddTextControl.vb or AddTextControl.cs, and then click View Code.

In the Click event handler of the insertText button, write the following code.

Private Sub insertText_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) _
    Handles insertText.Click

    With Globals.ThisDocument
        .InsertMemoFromNode.Text = Me.fromBox.Text
        .InsertMemoToNode.Text = Me.toBox.Text
        .InsertMemoSubjectNode.Text = Me.subjectBox.Text
    End With

    ' Clear the text boxes.
    Me.fromBox.Text = ""
    Me.toBox.Text = ""
    Me.subjectBox.Text = ""
End Sub

private void insertText_Click(object sender, System.EventArgs e)
{
    Globals.ThisDocument.InsertMemoFromNode.Text = this.fromBox.Text;
    Globals.ThisDocument.InsertMemoToNode.Text = this.toBox.Text;
    Globals.ThisDocument.InsertMemoSubjectNode.Text = this.subjectBox.Text;

    // Clear the text boxes.
    this.fromBox.Text = "";
    this.toBox.Text = "";
    this.subjectBox.Text = "";
}

In C#, you must add an event handler for the button. You can place this code in the AddTextControl constructor after the call to InitializeComponent.
```
public AddTextControl()
{
    InitializeComponent();
    this.insertText.Click += new System.EventHandler(this.insertText_Click);
}
```

To show the Table Properties dialog box

In Solution Explorer, right-click ShowPropertiesControl.vb or ShowPropertiesControl.cs, and then click View Code.

Add the following code to the Click event handler of the tableProperties button.

Private Sub tableProperties_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) _
    Handles tableProperties.Click

    Globals.ThisDocument.Application.Dialogs( _
        Word.WdWordDialog.wdDialogTableProperties).Show()
End Sub

private void tableProperties_Click(object sender, System.EventArgs e)
{
    object timeout = 0;

    Globals.ThisDocument.Application.Dialogs[
        Microsoft.Office.Interop.Word.WdWordDialog.wdDialogTableProperties]
            .Show(ref timeout);
}

In C#, you must add an event handler for the button. You can place this code in the ShowPropertiesControl constructor after the call to InitializeComponent.
```
public ShowPropertiesControl()
{
    InitializeComponent();
    this.tableProperties.Click += new System.EventHandler(this.tableProperties_Click);
}
```

Testing the Application

Now you can further test your document to verify the functionality of the actions pane controls.

To test your document

Press F5 to run your project.
Confirm that the actions pane is visible.
Move your cursor to the section of the document that contains the To, From, and Subject lines, and confirm that the addText controls appear on the actions pane.
Enter text in the To, From, and Subject text boxes on the actions pane, and click Insert.
Move your cursor to the table and confirm that the showProperties control appears on the actions pane.
Click the Table Properties button and confirm that the Table Properties dialog box opens.
Click the Show All check box and confirm that all controls on the actions pane are visible.
Move your cursor outside of the table and confirm that the Table Properties button becomes disabled.

Next Steps

This walkthrough shows the basics of changing the actions pane based on user context. Here are some tasks that might come next:

Binding data to controls in Word. For more information, see Walkthrough: Binding Data to Controls on a Word Actions Pane.
Binding data to controls in Excel. For more information, see Walkthrough: Binding Data to Controls on an Excel Actions Pane.
Deploying the project. For more information, see Deployment Overview (Office Development in Visual Studio).