Walkthrough: Changing the Actions Pane According to User Context

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.

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 Document-level projects Microsoft Office version Word 2007 Word 2003 For more information, see Features Available by Application and Project Type.

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.

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:

• Visual Studio Tools for Office (an optional component of Visual Studio 2008 Professional and Visual Studio Team System).

• Microsoft Office Word 2003 or Microsoft Office Word 2007.

Visual Studio Tools for Office is installed by default with the listed versions of Visual Studio. To check whether it is installed, see Installing Visual Studio Tools for Office.

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 Visual Studio Tools for Office Projects.

  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

1. Select the My Dynamic Actions Pane project in Solution Explorer.

2. On the Project menu, click Add New Item.

   The Add New Item dialog box appears.

3. In the Templates pane, select XML Schema.

4. Name the schema ActionsPaneSample.xsd and click Add.

5. In Solution Explorer, right-click ActionsPaneSample.xsd, and then click Open With.

6. In the Open With dialog box, select XML Editor, and then click OK.

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

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

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

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

1. Open the Templates and Add-ins dialog box. To do this in Word 2007:

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

   2. In the XML group, click Schema.

      The Templates and Add-ins dialog box opens.

   To open the Templates and Add-ins dialog box in Word 2003:

   1. On the Tools menu, point to Microsoft Office Word Tools, and then click Templates and Add-Ins.

      The Templates and Add-ins dialog box opens.

      Note

      If Microsoft Office Word Tools is not available on the Tools menu, click the document to give it focus. For more information, see Office Menus in the Visual Studio Environment.

2. In the Templates and Add-ins dialog box, click the XML Schema tab, and then click Add Schema.

3. Browse to the ActionsPaneSample.xsd schema you created earlier, which is located in your project directory, and click Open.

4. Click OK in the Schema Settings dialog box.

5. Click OK to close the Templates and Add-ins dialog box.

   The XML Structure task pane opens.

To map XML elements to your document

1. Click the Sample element in the XML Structure task pane.

2. Click Apply to Entire Document when prompted.

3. Select the three lines of text To, From, and Subject, and click the Insert element in the XML Structure task pane.

4. Place your cursor after To:, press the TAB key twice, and click the MemoTo element to insert it.

5. Place your cursor after From:, press the TAB key twice, and click the MemoFrom element.

6. Place your cursor after Subject:, press the TAB key once, and click the MemoSubject element.

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

8. Clear the Show XML tags in the document check box.

9. Click XML Options at the bottom of the XML Structure task pane.

10. Select the Ignore mixed content check box, and click OK.

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

1. Select the My Dynamic Actions Pane project in Solution Explorer.

2. On the Project menu, click Add New Item.

3. In the Add New Item dialog box, select Actions Pane Control, name it AddTextControl, and click Add.

4. Change the Size property of the actions pane control to 170, 135.

To add Windows Forms controls to the first actions pane control

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

2. Add a Textbox control to AddTextControl and change the following properties.

   Property	Value
   Name	toBox
   Size	110, 20

3. Add a second Label control to AddTextControl, and change the Text property to From:.

4. Add a second Textbox control to AddTextControl and change the following properties.

   Property	Value
   Name	fromBox
   Size	110, 20

5. Add a third Label control to AddTextControl under the previous text box, and change the Text property to Subject:.

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

7. Resize the subjectBox text box to enable multiple lines.

8. Add a Button control to AddTextControl and change the following properties.

   Property	Value
   Name	insertText
   Text	Insert

To create the second actions pane control

1. Add a second actions pane control to your project and name it ShowPropertiesControl.

2. Change the Size property of the actions pane control to 170, 50.

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

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

To create the third actions pane control

1. Add a third actions pane control to your project and name it ShowAllControl.

2. Change the Size property of the actions pane control to 170, 75.

3. From the Windows Forms tab of the Toolbox, add a GroupBox control to ShowAllControl and change the Text property to My Actions Pane.

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

5. For C#, change the Modifiers property of the check box to Internal.

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

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

2. 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();
   

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

4. 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);
       }
   }
   

5. 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);
       }
   }
   

6. 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;
   }
   

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

8. 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 Visual Studio Tools for Office.

   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

1. Press F5 to run your project.

2. Move your insertion point to the word To and verify that the addText actions pane control is visible on the actions pane.

3. Move your insertion point to inside the table and verify that the showProperties actions pane control is visible on the actions pane.

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

1. 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);
       }
   }
   

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

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

2. 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 = "";
   }
   

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

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

2. 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);
   }
   

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

1. Press F5 to run your project.

2. Confirm that the actions pane is visible.

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

4. Enter text in the To, From, and Subject text boxes on the actions pane, and click Insert.

5. Move your cursor to the table and confirm that the showProperties control appears on the actions pane.

6. Click the Table Properties button and confirm that the Table Properties dialog box opens.

7. Click the Show All check box and confirm that all controls on the actions pane are visible.

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

• Deploying the project. For more information, see How to: Deploy Office Solutions (2003 System).

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

See Also

Tasks

How to: Add an Actions Pane to Word Documents

How to: Add an Actions Pane to Excel Workbooks

How to: Manage Control Layout on Actions Panes

Concepts

Actions Pane Overview

XMLNodes Control