XMLNodes Control
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 to document-level projects for Word 2013 and Word 2010. For more information, see Features Available by Office Application and Project Type.
The XMLNodes control is a collection of mapped XML node objects that exposes events. The XMLNodes control is created only when a repeating schema element is mapped onto a Microsoft Office Word document. If the repeating element contains child elements, each of the child elements is also created as an XMLNodes control.
After Visual Studio creates the collection of XML nodes, you can program against the control directly without having to traverse the Word object model. The XMLNodes control can be deleted only by removing the element mapping from the document.
Note
If you access a child element of the XMLNodes control through the Item property, it returns a XMLNode object rather than a XMLNode control. For more information, see Programmatic Limitations of Host Items and Host Controls.
Binding Data to the Control
An XMLNodes control does not support data binding. This is because the XMLNodes control does not have complex data binding capabilities, and simple data binding cannot represent repeating data.
Formatting
Any formatting that can be applied to text within the document can be applied to an XMLNodes control.
Events
The events available for the XMLNodes control are:
Comparing Events
You can capture an event when the user moves his or her cursor inside the context of a particular XMLNodes control. For example, you might have an XMLNodes control named Customer that has a child XMLNodes control named Company, and Company has two child XMLNodes controls named CompanyName and CompanyRegion as follows:
<Customer>
<Company>
<CompanyName>
<CompanyRegion>
If you want to show a control on the actions pane whenever the cursor is moved into the Company node, it should not matter whether the cursor is placed in CompanyName or CompanyRegion because they are both within the context of Company. In this case, you can write your code in the ContextEnter event of Company.
In most cases, when the cursor enters an XMLNodes control, both the Select and ContextEnter events are raised. The following table shows differences between these events.
Select event |
ContextEnter event |
|---|---|
Occurs when the cursor is placed inside one of the nodes of the XMLNodes collection. |
Occurs when the cursor is placed inside one of the nodes or descendant nodes of the XMLNodes collection, from an area outside of the context of the node. In other words, it is raised only when the context changes, and can be raised for multiple nested XMLNodes controls. |
For example, when you move the cursor from outside of Customer into CompanyName, the ContextEnter events for Customer, Company, and CompanyName are raised. If you then move the cursor from CompanyName to CompanyRegion, the ContextEnter event only for CompanyRegion is raised, because the context is the same for both Company and Customer. You can have multiple Company nodes in your document. If you move the cursor from the CompanyName node of one Company to the CompanyName node of another Company, the context is the same, so only the Select event is raised.
The same differences exist between the ContextLeave event and the Deselect event.
See Also
Tasks
How to: Add XMLNodes Controls to Word Documents
How to: Map Schemas to Word Documents Inside Visual Studio
Concepts
Host Items and Host Controls Overview