# Fields and Subtext Parts

> Collect fields of all WPF text parts, read MS Word fields with adapters such as MergeField, IfField and NextIfField, and keep data in subtext parts.

- **Product:** TX Text Control .NET for WPF
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET for WPF > Document Processing > Fields and Subtext Parts
- **3590 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/fields/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/fields/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/fields/llms-full.txt

---

How does an application find the customer name in a letter again, open the link a user clicks, or know that the cursor is inside the payment clause of a contract? Fields and subtext parts answer these questions. Fields mark short pieces of text such as names, links, bookmarks and MS Word fields; subtext parts mark longer ranges and can carry data. In a loaded document, your code collects the fields of every text part, reads and changes MS Word fields with typed field adapters and keeps data with ranges of text.

The code goes into *MainWindow.xaml.cs* of a window whose `TextControl` is named `textControl1` and which shows results in a `TextBlock` named `statusText`. Merge fields filled with data are described in [Merge Fields](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/fields/llms-full.txt), fillable form fields in [Forms and Conditional Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/form-fields/llms-full.txt) and page numbers in [Sections, Pages, Headers, and Footers](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/sections-headers/llms-full.txt).

*MainWindow.xaml.cs* needs these `using` directives:

```csharp
using System.Text;
using System.Windows;
using TXTextControl;
using TXTextControl.DocumentServer.Fields;
```

### The Kinds of Fields

Every field is a marked piece of text with properties such as a name and an ID, and each kind is kept in its own collection of `WPF.TextControl`: [TextFields](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/textfields-property/llms-full.txt), [ApplicationFields](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/applicationfields-property/llms-full.txt) for MS Word fields, [HypertextLinks](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/hypertextlinks-property/llms-full.txt), [DocumentTargets](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/documenttargets-property/llms-full.txt) for bookmarks and [DocumentLinks](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/documentlinks-property/llms-full.txt). [Fields, Hyperlinks, and Bookmarks](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/fields/llms-full.txt) explains each kind and shows how to insert, fill, find and remove text fields, insert links and bookmarks, handle the field events and handle clicks on links. Keep in mind:

- **Only the active text part.** The collections contain the fields of the text part with the input focus, which is the main text, a text frame, or a header or footer. [TextParts](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/textparts-property/llms-full.txt) gives you every part, as the next section shows.
- **MS Word fields are imported on request.** Set [LoadSettings.ApplicationFieldFormat](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/loadsettings/applicationfieldformat-property/llms-full.txt) before loading a Word document, or `ApplicationFields` stays empty.
- **Names and IDs of text fields are kept in the TX Text Control format**, `StreamType.InternalUnicodeFormat`.
- **Links don't navigate by themselves.** Open only web addresses from a `HypertextLinkClicked` handler, so that documents can't start programs; see [Handling Untrusted Documents](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/security/untrusted-documents/llms-full.txt).

### Find the Fields of All Text Parts

`TextParts` contains the main text, the text frames and the headers and footers, each as an [IFormattedText](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/iformattedtext/llms-full.txt) with its own field collections. This handler loads a Word template with its fields and lists the merge fields and links of every part:

```csharp
private void ListFields_Click(object sender, RoutedEventArgs e)
{
    LoadSettings loadSettings = new LoadSettings()
    {
        ApplicationFieldFormat = ApplicationFieldFormat.MSWord
    };

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

    StringBuilder list = new StringBuilder();

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

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

    statusText.Text = list.ToString();
}
```

[TypeName](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/applicationfield/typename-property/llms-full.txt) is the type of a Word field, and [Parameters](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/applicationfield/parameters-property/llms-full.txt) holds the rest of its field code. The field adapters in [Use Field Adapters for MS Word Fields](#use-field-adapters-for-ms-word-fields) read and write these settings with typed properties.

[ApplicationFieldCollection.Clear](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/applicationfieldcollection/clear-method/llms-full.txt) with `true` removes all fields of a collection and keeps their text, which turns them into plain text. `Remove(field, true)` does this for one field.

### Use Field Adapters for MS Word Fields

An `ApplicationField` gives you the type name and the raw parameters of a Word field, but it doesn't know what they mean. The classes of the `TXTextControl.DocumentServer.Fields` namespace are adapters for the common Word fields: an adapter wraps an application field and offers its settings as typed properties, so your code doesn't have to parse or build field codes.

- **Change an existing field:** pass the application field to the adapter's constructor, for example `new MergeField(field)`. Changes to the adapter's properties change the field in the document.
- **Create a new field:** create the adapter without parameters, set its properties and add its [ApplicationField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/fieldadapter/applicationfield-property/llms-full.txt) with `textControl1.ApplicationFields.Add`.

Every adapter class has the constant [TYPE\_NAME](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/fieldadapter/type-name-field/llms-full.txt), the type name of the Word field it handles. Comparing it with `TypeName` tells you which adapter fits a field:

| Adapter | Word field | Described in |
|---|---|---|
| [MergeField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/mergefield/llms-full.txt) | `MERGEFIELD`, a value from the data | [Merge Fields](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/fields/llms-full.txt) |
| [DateField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/datefield/llms-full.txt) | The current date in a format | [Merge Fields](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/fields/#insert-date-fields) |
| [IfField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/iffield/llms-full.txt) | `IF`, text that depends on a comparison | [Conditional Content](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/conditional-content/llms-full.txt) |
| [IncludeText](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/includetext/llms-full.txt) | `INCLUDETEXT`, another document included in a template | [Subtemplates](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/subtemplates/llms-full.txt) |
| [NextField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/nextfield/llms-full.txt), [NextIfField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/nextiffield/llms-full.txt) | `NEXT` and `NEXTIF`, which continue with the next data record, always or on a condition | [Overview](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/overview/llms-full.txt) of Mail Merge and Reporting |
| [FormText](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/formtext/llms-full.txt), [FormCheckBox](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/formcheckbox/llms-full.txt), [FormDropDown](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/formdropdown/llms-full.txt) | The legacy form fields of MS Word | [Content Controls](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/content-controls/llms-full.txt) |
| [ContentControlFieldAdapter](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/contentcontrolfieldadapter/llms-full.txt) and its six derived classes | The content controls of MS Word | [Content Controls](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/content-controls/llms-full.txt) |

The first six derive from [MailMergeFieldAdapter](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/mailmergefieldadapter/llms-full.txt), the legacy form fields from [FormFieldAdapter](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/formfieldadapter/llms-full.txt), and all of them from [FieldAdapter](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/fieldadapter/llms-full.txt). The following handler shows the settings of the Word field at the input position:

```csharp
private void ShowFieldSettings_Click(object sender, RoutedEventArgs e)
{
    // The application field at the input position, or null
    ApplicationField field = textControl1.ApplicationFields.GetItem();

    if (field == null)
    {
        statusText.Text = "No MS Word field at the input position";
    }
    else if (field.TypeName == MergeField.TYPE_NAME)
    {
        MergeField mergeField = new MergeField(field);
        statusText.Text = $"Merge field {mergeField.Name}, text before: \"{mergeField.TextBefore}\"";
    }
    else if (field.TypeName == IfField.TYPE_NAME)
    {
        IfField ifField = new IfField(field);
        statusText.Text = $"IF {ifField.Expression1} {ifField.Operator} {ifField.Expression2}";
    }
    else if (field.TypeName == NextIfField.TYPE_NAME)
    {
        NextIfField nextIfField = new NextIfField(field);
        statusText.Text = $"NEXTIF {nextIfField.Expression1} {nextIfField.Operator} {nextIfField.Expression2}";
    }
    else
    {
        statusText.Text = $"{field.TypeName} field: {string.Join(" ", field.Parameters)}";
    }
}
```

The code works as follows:

- [ApplicationFieldCollection.GetItem](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/applicationfieldcollection/getitem-method/llms-full.txt) without a parameter returns the field at the input position, or `null`.
- The constructors, such as the [MergeField constructor](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/mergefield/constructor/llms-full.txt), connect the adapter to the field. [Name](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/mergefield/name-property/llms-full.txt) and [TextBefore](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/mergefield/textbefore-property/llms-full.txt) of `MergeField` are settings of the field code.
- [Expression1](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/iffield/expression1-property/llms-full.txt), [Operator](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/iffield/operator-property/llms-full.txt) and [Expression2](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/iffield/expression2-property/llms-full.txt) of `IfField` form the comparison. `NextIfField` has the same three [properties](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/nextiffield/llms-full.txt), and its [Result](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/nextiffield/result-property/llms-full.txt) is the outcome of the comparison. [NextField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/nextfield/constructor/llms-full.txt) has no settings of its own.
- Other fields fall back to the raw `Parameters`.

[FieldAdapter.ShowDialog](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/fieldadapter/showdialog-method/llms-full.txt) opens the options dialog box of a field; in a WPF application, pass the `Window` as its owner, for example `mergeField.ShowDialog(this)`. [Reporting Ribbon and WPF Dialog Boxes](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/ribbon-dialogs/#open-the-dialog-boxes-from-code) opens it for the field at the input position.

### Mark Ranges With Subtext Parts

A [SubTextPart](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/subtextpart/llms-full.txt) covers a continuous range of text, tables and fields included, and stores a name, an ID and a [Data](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/subtextpart/data-property/llms-full.txt) string. Subtext parts nest but never overlap, and [Merge Blocks](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/blocks/llms-full.txt) are built on them. [Subtext Parts](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/subtext-parts/llms-full.txt) shows how to add, list, find, save and remove them and how to handle their events. The `Data` string survives only in the TX Text Control format; DOCX, DOC and RTF files keep the ranges, which come back as subtext parts when [LoadSettings.LoadSubTextParts](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/loadsettings/loadsubtextparts-property/llms-full.txt) is `true`. The blog article [The Power of SubTextParts: Typical Use Cases](https://www.textcontrol.com/blog/2024/02/09/the-power-of-subtextparts-typical-use-cases/) collects further uses; its code is written for the Windows Forms `TextControl`.

### Next Steps

- [Fields, Hyperlinks, and Bookmarks](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/fields/llms-full.txt): insert, find and remove fields, links and bookmarks and handle their events.
- [Subtext Parts](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/subtext-parts/llms-full.txt): add, find, save and remove subtext parts.
- [Merge Fields](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/fields/llms-full.txt): fill merge fields with data.
- [Content Controls](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/content-controls/llms-full.txt): read and create the content controls and legacy form fields of MS Word.
- [Forms and Conditional Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/form-fields/llms-full.txt): fields that users fill out.

---

## Nearby

- **Previous:** [Sections, Pages, Headers, and Footers](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/sections-headers/llms-full.txt)
- **Next:** [Forms and Conditional Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/form-fields/llms-full.txt)