TX Text Control .NET for Windows Forms

Fields and Subtext Parts

Topic

Fields mark the pieces of a document that your code has to find again: a customer name, a link to a website, a bookmark, a Word merge field. Subtext parts do the same for longer ranges, such as a clause of a contract or an address block, and can carry data of their own. In a Windows Forms application, both work in code and in the editor: the user clicks a link, your application opens it; the input position enters a clause, your application shows its data.

Each example is a handler in Form1.cs with the TextControl named textControl1. Filling merge fields with data is the subject of Merge Fields, form fields are covered in Forms and Conditional Instructions, and page numbers in Sections, Pages, Headers, and Footers.

The Kinds of Fields

A field is a marked piece of text with a name, an ID and other properties: a TextField, an ApplicationField of MS Word, a HypertextLink, a bookmark (DocumentTarget) or a DocumentLink to a bookmark. Kinds of Fields lists their collections. The collections of TextControl contain the fields of the text part with the input focus only, and fields of MS Word documents become application fields only when LoadSettings.ApplicationFieldFormat is set before loading.

Insert a Text Field

A text field is inserted at the input position with TextFieldCollection.Add, after CanAdd has confirmed that a field can go there. Insert and Fill Text Fields inserts a field for a customer name, fills it and explains Name, ID, HighlightMode, Editable and Deleteable.

Add Hypertext Links and Bookmarks

A hypertext link points to a website or a file, a bookmark marks a position, and a document link points to a bookmark. Each is inserted at the input position with the Add method of its collection, as Insert Hyperlinks and Bookmarks shows, together with the formatting of links inserted in code.

Open Links When the User Clicks Them

The editor does not open links by itself. It raises HypertextLinkClicked or DocumentLinkClicked, and your application decides what the click does. Handle Clicks on Links opens websites, jumps to bookmarks and opens linked files, and Find, List and Remove Fields lists the events of text fields, such as TextFieldClicked.

Find the Fields of All Text Parts

To reach every field of a document, including headers, footers and text frames, loop through TextParts. Each part implements IFormattedText, which has the same field collections. The following handler loads an MS Word document with its fields and lists them in a message box; it needs using System.Text; at the top of Form1.cs:

private void listFieldsButton_Click(object sender, EventArgs e)
{
    TXTextControl.LoadSettings loadSettings = new TXTextControl.LoadSettings()
    {
        ApplicationFieldFormat = TXTextControl.ApplicationFieldFormat.MSWord
    };

    textControl1.Load("template.docx", TXTextControl.StreamType.WordprocessingML, loadSettings);

    StringBuilder list = new StringBuilder();

    foreach (TXTextControl.IFormattedText textPart in textControl1.TextParts)
    {
        foreach (TXTextControl.ApplicationField field in textPart.ApplicationFields)
        {
            list.AppendLine($"{textPart.GetType().Name}: {field.TypeName} = \"{field.Text}\"");
        }

        foreach (TXTextControl.HypertextLink link in textPart.HypertextLinks)
        {
            list.AppendLine($"{textPart.GetType().Name}: link to {link.Target}");
        }
    }

    MessageBox.Show(list.ToString());
}

For an application field, TypeName is the Word field type, such as MERGEFIELD, and Parameters holds the rest of the field code. Work With MS Word Fields changes these fields and turns them into plain text with Clear(true).

Mark Ranges With Subtext Parts

A SubTextPart marks a continuous range of text, such as a clause, with a name, an ID and a string of data of your own, for example JSON. Merge blocks are subtext parts too, as Merge Blocks explains. Subtext Parts creates, finds, saves and removes them, describes the events that report when the user enters one, and lists which formats keep them. To mark a whole paragraph, pass Paragraph.Start, which is one-based like the start position of the SubTextPart constructor, and the paragraph's Length minus 1, so that the paragraph end stays outside.

Next Steps