Inserting elements using WordApplication

How WordApplication insert elements

Each of the elements listed in the document tree structure inherit from the Element class, which provides most of the methods for inserting new elements into a document. WordApplication will allow you to call any Insert method on almost any type of element, but the behavior of that method will change depending on what type of element the method is called on and what type of element the method is inserting.

For example:

• Inserting a new Section automatically inserts a new Paragraph and CharacterRun within that Section.
• Inserting a new Paragraph automatically inserts a new CharacterRun within that Paragraph.

To further illustrate this point, we will examine calling InsertTextAfter on a Section

Example: Calling InsertCharacterRunAfter on a Section

This example shows the behavior of WordWriter when inserting an element two levels deeper than the current element.

A CharacterRun must be the child of a Paragraph, but InsertTextAfter can be called on a Section. In this case, a new CharacterRun will be inserted at the end of the last Paragraph in the Section.

To achieve the most predictable behavior, it is recommended practice to call a Create or Insert method on an object appropriate to what is being inserted.

So, for example, instead of calling InsertTextAfter on a Section object as described above, it should be called on a Paragraph, ListEntry, or Field contents.

Here is an example Word document before running either of the code samples above:

Here is the output from the example after running either of the code samples:

List of Insert Behaviors

The following table lists some common examples of how WordWriter behaves when a Create or Insert method is called on different elements.

Each column represents the following:

• Parent element: Element on which InsertXBefore or InsertXAfter is called.
• Element to be inserted: Type of element which is being inserted. Use the appropriate InsertXBefore or InsertXAfter for this type.
• InsertXBefore Behavior: What the InsertXBefore method does in this case.
• InsertXAfter Behavior: What the InsertXAfter method does in this case.

Notes:

• To insert a Section, use CreateSectionBefore or CreateSectionAfter.
• To insert a CharacterRun, use InsertTextBefore or InsertTextAfter.