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