# Form Fields and Conditional Instructions

> Create WPF forms with the RibbonFormFieldsTab or C#: text, check box, drop-down and date fields, form protection, field values and conditional instructions.

- **Product:** TX Text Control .NET for WPF
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET for WPF > Document Editor > Form Fields and Conditional Instructions
- **5599 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/form-fields/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/form-fields/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/form-fields/llms-full.txt

---

A form is a protected document in which users can change only the form fields: text boxes, check boxes, drop-down lists, combo boxes and date pickers. The WPF `TextControl` lets users or your code design such forms, fill them out, validate the entries with conditional instructions and hand the values to your application.

The examples use a window with a `TextControl` named `textControl1`, as in [Create Your First WPF Application](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/getting-started/document-editor/first-application/llms-full.txt). Form fields were introduced in version 28.0 and are part of the Enterprise edition; see [Editions and Feature Availability](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/overview/editions/llms-full.txt). The tutorial [Create a PDF Form](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/getting-started/pdf/form/llms-full.txt) saves form fields as a fillable PDF.

### Form Field Types

Form fields are text fields that users fill out. Their base class is [FormField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/formfield/llms-full.txt), and [WPF.TextControl.FormFields](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/formfields-property/llms-full.txt) contains all of them:

| Form field | Class | What the user does |
|---|---|---|
| Text form field | [TextFormField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/textformfield/llms-full.txt) | Types text |
| Check box | [CheckFormField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/checkformfield/llms-full.txt) | Checks or unchecks it |
| Drop-down list | [SelectionFormField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/selectionformfield/llms-full.txt), `Editable` is `false` | Selects an item |
| Combo box | [SelectionFormField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/selectionformfield/llms-full.txt), `Editable` is `true` | Selects an item or types text |
| Date form field | [DateFormField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/dateformfield/llms-full.txt) | Picks a date or types it |

### Add the Form Fields and Permissions Tabs

[WPF.RibbonFormFieldsTab](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/ribbonformfieldstab/llms-full.txt) inserts, edits and navigates form fields, manages form validation and shows the properties of the selected field. [WPF.RibbonPermissionsTab](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/ribbonpermissionstab/llms-full.txt) protects the finished form. The following *MainWindow.xaml* connects both tabs with the `TextControl`, gives the conditional instructions a sidebar and adds buttons for the code of this page:

```xml
<Window x:Class="SampleApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:WPF="clr-namespace:TXTextControl.WPF;assembly=TXTextControl.WPF"
        Title="MainWindow" Height="600" Width="900">
    <DockPanel>
        <Ribbon DockPanel.Dock="Top">
            <WPF:RibbonPermissionsTab x:Name="ribbonPermissionsTab" />
            <WPF:RibbonFormFieldsTab x:Name="ribbonFormFieldsTab"
                                    ConditionalInstructionsSidebar="sidebarRight" />
        </Ribbon>
        <WPF:Sidebar x:Name="sidebarRight" DockPanel.Dock="Right" />
        <StackPanel DockPanel.Dock="Top" Orientation="Horizontal">
            <Button Content="Insert Form" Click="InsertForm_Click" />
            <Button Content="Add Rules" Click="AddRules_Click" />
            <Button Content="Protect Form" Click="ProtectForm_Click" />
            <Button Content="Read Values" Click="ReadValues_Click" />
            <Button Content="Preview Form" Click="PreviewForm_Click" />
        </StackPanel>
        <WPF:TextControl x:Name="textControl1"
                        RibbonPermissionsTab="ribbonPermissionsTab"
                        RibbonFormFieldsTab="ribbonFormFieldsTab"
                        FormFieldCheckChanged="textControl1_FormFieldCheckChanged" />
    </DockPanel>
</Window>
```

- [RibbonFormFieldsTab](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/ribbonformfieldstab-property/llms-full.txt) and [RibbonPermissionsTab](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/ribbonpermissionstab-property/llms-full.txt) of the `TextControl` take the names of the tabs.
- [ConditionalInstructionsSidebar](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/ribbonformfieldstab/conditionalinstructionssidebar-property/llms-full.txt) is the name of the [WPF.Sidebar](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/sidebar/llms-full.txt) in which **Manage Conditional Instructions** shows the instructions of the document. [Sidebar and Panels](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/ribbon-ui/sidebar/llms-full.txt) covers sidebars.

In TX Text Control Words, the WPF sample application, the **Form Fields** tab and the sidebar look like this:

![The WPF Form Fields tab of TX Text Control Words with a booking request form and the Conditional Instructions sidebar, which lists the rules of the form and describes the conditions and actions of Validate Arrival.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-wpf/conditional-instr-sidebar.e7bf0dc0.webp)

### Insert Form Fields in Code

*MainWindow.xaml.cs* starts like this:

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

The following handler writes a booking form with one field of each type:

```csharp
private void InsertForm_Click(object sender, RoutedEventArgs e)
{
    textControl1.Selection.Text = "Arrival: ";
    AddFormField(new DateFormField(0) { Name = "Arrival" });

    textControl1.Selection.Text = "\nNumber of nights: ";
    AddFormField(new TextFormField(1000) { Name = "Nights" });   // width in twips while empty

    textControl1.Selection.Text = "\nAccommodation: ";
    AddFormField(new SelectionFormField(new string[] { "Single room", "Double room", "Suite" }, -1)
    {
        Name = "Accommodation",
        Editable = false   // false: drop-down list, true: combo box
    });

    textControl1.Selection.Text = "\nBreakfast: ";
    AddFormField(new CheckFormField(false) { Name = "Breakfast" });
}

// Insert a form field and move the input position behind it
private void AddFormField(FormField formField)
{
    textControl1.FormFields.Add(formField);
    textControl1.InputPosition = new InputPosition(
        formField.Start + formField.Length - 1,
        TextFieldPosition.OutsideTextField);
}
```

- [TextFormField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/textformfield/constructor/llms-full.txt), [DateFormField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/dateformfield/constructor/llms-full.txt) and [SelectionFormField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/selectionformfield/constructor/llms-full.txt) have a constructor that takes the width in twips while the field is empty, 0 for a default width. The `SelectionFormField` overload used here takes the items and the preselected index, -1 for none. [CheckFormField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/checkformfield/constructor/llms-full.txt) takes the checked state.
- [Name](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/textfield/name-property/llms-full.txt) is how your code, conditional instructions and PDF forms refer to the field. [DescriptiveText](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/formfield/descriptivetext-property/llms-full.txt) describes it for screen readers.
- [FormFieldCollection.Add](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/formfieldcollection/add-method/llms-full.txt) inserts the field at the input position, and [InputPosition](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/inputposition-property/llms-full.txt) with `TextFieldPosition.OutsideTextField` places the cursor behind it.

Further settings are [SelectionFormField.Items](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/selectionformfield/items-property/llms-full.txt), [CheckFormField.Checked](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/checkformfield/checked-property/llms-full.txt), [DateFormField.Date](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/dateformfield/date-property/llms-full.txt) and [DateFormField.DateFormat](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/dateformfield/dateformat-property/llms-full.txt). [FormField.FormFieldDialog](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/formfield/formfielddialog-method/llms-full.txt) opens the built-in dialog box of a form field.

### Protect the Form

On the **Permissions** tab, users select **Fill in Form Fields** and **Read Only** and click **Enforce Protection**. While the protection is enforced, the other permission buttons are unavailable:

![The WPF Permissions tab of TX Text Control Words with Read Only and Enforce Protection active and the other permission buttons unavailable.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-wpf/permissions-form-fields.ff7b0fd0.webp)

The same in code:

```csharp
private void ProtectForm_Click(object sender, RoutedEventArgs e)
{
    // Users can fill in the form fields and change nothing else
    textControl1.DocumentPermissions.AllowEditingFormFields = true;
    textControl1.DocumentPermissions.ReadOnly = true;
    textControl1.EditMode = EditMode.ReadAndSelect;
}
```

[AllowEditingFormFields](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/documentpermissions/alloweditingformfields-property/llms-full.txt) and [ReadOnly](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/documentpermissions/readonly-property/llms-full.txt), from [WPF.TextControl.DocumentPermissions](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/documentpermissions-property/llms-full.txt), take effect in the `ReadAndSelect` [edit mode](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/editmode-property/llms-full.txt). In a protected form, [FormField.Enabled](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/formfield/enabled-property/llms-full.txt) set to `false` locks a single field. [Document Protection and Editable Regions](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/protection/llms-full.txt) covers permissions and passwords.

### Read the Values

```csharp
private void ReadValues_Click(object sender, RoutedEventArgs e)
{
    StringBuilder values = new StringBuilder();

    foreach (FormField formField in textControl1.FormFields)
    {
        string value = formField switch
        {
            CheckFormField checkField => checkField.Checked ? "yes" : "no",
            DateFormField dateField => dateField.Date?.ToShortDateString() ?? "",
            _ => formField.Text
        };

        values.AppendLine(formField.Name + ": " + value);
    }

    MessageBox.Show(this, values.ToString());
}

private void textControl1_FormFieldCheckChanged(object sender, CheckFormFieldEventArgs e)
{
    Title = e.CheckFormField.Name + ": " + e.CheckFormField.Checked;
}
```

The loop reads `Text`, `Checked` or `Date`, depending on the type. For each type there is an event, raised when the user changes a value, not when your code sets a property such as `Checked` or `Date`: [FormFieldTextChanged](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/formfieldtextchanged-event/llms-full.txt) with [TextFormFieldEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/textformfieldeventargs/llms-full.txt), [FormFieldCheckChanged](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/formfieldcheckchanged-event/llms-full.txt) with [CheckFormFieldEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/checkformfieldeventargs/llms-full.txt), [FormFieldSelectionChanged](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/formfieldselectionchanged-event/llms-full.txt) with [SelectionFormFieldEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/selectionformfieldeventargs/llms-full.txt) and [FormFieldDateChanged](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/formfielddatechanged-event/llms-full.txt) with [DateFormFieldEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/dateformfieldeventargs/llms-full.txt). Typed text and typed dates are reported when the user leaves the field.

### Validate Entries With Conditional Instructions

Conditional instructions add rules to a form: conditions on form field values, and instructions that enable or disable a field, mark its value as valid or invalid, set its value or replace the items of a drop-down list. Users create them with **Manage Conditional Instructions** on the **Form Fields** tab, and the **Form Validation** group of the tab highlights the values a rule has marked as invalid and moves between them.

[Conditional Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/conditional-instructions/llms-full.txt) covers the ribbon items, every operator and instruction type and the rules of a complete booking form. [Create Rules in Code](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/conditional-instructions/#create-rules-in-code) adds rules with `ConditionalInstruction` objects, and [Initial and Change Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/conditional-instructions/#initial-and-change-instructions) decides when an instruction runs. The TX Text Control Words sample *Conditional Instructions* in *%USERPROFILE%\\Documents\\TX Text Control 34.0.NET for WPF\\CSharp\\TX Words\\Conditional Instructions* previews a booking form with rules, as [Preview a Form](#preview-a-form) shows. The blog article [Building a Credit Card Payment Form with Conditional Instructions](https://www.textcontrol.com/blog/2023/03/24/building-a-credit-card-payment-form-with-conditional-instructions/) builds another form.

### Preview a Form

While designing a form, you want to try its rules without protecting the document for good. The TX Text Control Words sample *Conditional Instructions* has a **Preview** button on the **Form Fields** tab for this, which is enabled while **Enable Form Validation** is on. The picture in [Add the Form Fields and Permissions Tabs](#add-the-form-fields-and-permissions-tabs) shows the sample in preview mode. The button is part of the sample, not of `RibbonFormFieldsTab`; the following handler for the **Preview Form** button of *MainWindow.xaml* does the same:

```csharp
private byte[] formBeforePreview;
private bool allowEditingBeforePreview;
private bool readOnlyBeforePreview;

private void PreviewForm_Click(object sender, RoutedEventArgs e)
{
    if (formBeforePreview == null)
    {
        // Keep the designed form and its permissions
        textControl1.Save(out formBeforePreview, BinaryStreamType.InternalUnicodeFormat);
        allowEditingBeforePreview = textControl1.DocumentPermissions.AllowEditingFormFields;
        readOnlyBeforePreview = textControl1.DocumentPermissions.ReadOnly;

        // Switch to a form: the conditional instructions run
        textControl1.IsFormFieldValidationEnabled = true;
        textControl1.DocumentPermissions.AllowEditingFormFields = true;
        textControl1.DocumentPermissions.ReadOnly = true;
        textControl1.EditMode = EditMode.ReadAndSelect;
    }
    else
    {
        // Discard the test entries and return to the design
        textControl1.Load(formBeforePreview, BinaryStreamType.InternalUnicodeFormat);
        formBeforePreview = null;
        textControl1.DocumentPermissions.AllowEditingFormFields = allowEditingBeforePreview;
        textControl1.DocumentPermissions.ReadOnly = readOnlyBeforePreview;
        textControl1.EditMode = EditMode.Edit;
    }
}
```

The code works as follows:

- [Save](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/save-method/llms-full.txt) with `BinaryStreamType.InternalUnicodeFormat` writes the form with its fields and rules into a byte array before the preview starts, and the handler stores the two permissions it changes.
- `AllowEditingFormFields`, `ReadOnly` and the `ReadAndSelect` edit mode make the document a form, so the rules are applied as they will be for users. Turn on **Highlight Invalid Values** to see the values the rules mark as invalid.
- A second click reloads the saved form with [Load](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-wpf/textcontrol/load-method/llms-full.txt), which discards what was entered during the preview, and restores the permissions. The sample leaves resetting the edit mode to `Load`, which sets it back to `Edit`; the handler sets it explicitly.

While the preview runs, the sample also disables **Enable Form Validation** and hides the ribbon groups after **Form Validation**, so that the form can't be changed. [Template Preview](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/template-preview/llms-full.txt) uses the same save-and-reload pattern for merge previews.

### Forms in Files

Forms are saved and loaded with the TX Text Control format, DOC, DOCX and RTF. Form fields of Word documents are loaded as form fields, unless [LoadSettings.ApplicationFieldFormat](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol/loadsettings/applicationfieldformat-property/llms-full.txt) loads them as MS Word fields. [Content Controls](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/content-controls/llms-full.txt) describes both ways for the content controls and legacy form fields of Word documents, and the field adapter classes that read and create them in code. A PDF export turns the form fields into fillable PDF form fields; see [PDF Forms](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/pdf/forms/llms-full.txt). [Forms and Conditional Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/form-fields/llms-full.txt) in Document Processing works with form fields in `ServerTextControl`.

### Next Steps

- [Conditional Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-processing/conditional-instructions/llms-full.txt): operators, instruction types, else values and a complete booking form.
- [Signature Fields](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/signature-fields/llms-full.txt): add places for signatures to a form.
- [Document Protection and Editable Regions](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/protection/llms-full.txt): protect documents with permissions and passwords.
- [PDF Forms](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/pdf/forms/llms-full.txt): create, read and flatten PDF forms.

---

## Nearby

- **Previous:** [Subtext Parts](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/subtext-parts/llms-full.txt)
- **Next:** [Signature Fields](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/document-editor/signature-fields/llms-full.txt)