# Form Fields and Conditional Instructions > Design Windows Forms forms with text, check box, drop-down and date fields, protect and preview them, read values and check them with conditional instructions. - **Product:** TX Text Control .NET for Windows Forms - **Section:** Documentation - **Kind:** Topic - **Path:** TX Text Control .NET for Windows Forms > Document Editor > Form Fields and Conditional Instructions - **4924 words** - **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/form-fields/ - **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/form-fields/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/form-fields/llms-full.txt --- Booking requests, applications and questionnaires are documents in which users fill in only some places: a text box, a check box, a drop-down list or a date. With form fields, a Windows Forms application designs such forms in a `TextControl`, protects everything else, reads what users enter and checks the entries with conditional instructions, rules that validate, enable or fill fields depending on other fields. The examples extend the application of [Create Your First Windows Forms Application](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/document-editor/first-application/llms-full.txt), and *Form1.cs* needs `using TXTextControl;`. 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-winforms/overview/editions/llms-full.txt). [Create a PDF Form](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/pdf/form/llms-full.txt) is a short tutorial that turns form fields into a fillable PDF. ### Form Field Types A form field is a field that users fill out. All form fields derive from [FormField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/formfield/llms-full.txt), which is a [TextField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textfield/llms-full.txt), and all of them are in the collection [TextControl.FormFields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/formfields-property/llms-full.txt): | Form field | Class | What the user does | |---|---|---| | Text form field | [TextFormField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textformfield/llms-full.txt) | Types text | | Check box | [CheckFormField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/checkformfield/llms-full.txt) | Checks or unchecks it | | Drop-down list | [SelectionFormField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/selectionformfield/llms-full.txt) with `Editable` set to `false` | Chooses one of the items | | Combo box | [SelectionFormField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/selectionformfield/llms-full.txt) with `Editable` set to `true` | Chooses an item or types a value | | Date form field | [DateFormField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/dateformfield/llms-full.txt) | Picks a date in a date picker or types it | ### Design a Form With the Ribbon The **Form Fields** tab of the ribbon, [RibbonFormFieldsTab](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonformfieldstab/llms-full.txt), inserts all five types from the **Insert Form Fields** button. Its other groups edit, delete and navigate form fields, set up form validation and show the properties of the selected field, such as its name and the items of a drop-down list: ![The Form Fields tab of TX Text Control Words with a booking request form: a date field, two text fields and an open drop-down list, and the drop-down list properties in the ribbon.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/form-fields-tab-booking.231799ef.webp) To add the tab to your form, click the smart tag of the ribbon in the designer and click **Add a RibbonFormFieldsTab**, as in [Create Your First Windows Forms Application](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/document-editor/first-application/#add-the-ribbon-tabs). In code, [FormField.FormFieldDialog](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/formfield/formfielddialog-method/llms-full.txt) opens the built-in dialog box of a form field. ### Insert Form Fields in Code The following handler writes a small booking form: a label, then a form field, for each of the four types: ```csharp private void insertFormButton_Click(object sender, EventArgs 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); } ``` The code works as follows: - The constructors of [TextFormField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textformfield/constructor/llms-full.txt), [DateFormField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/dateformfield/constructor/llms-full.txt) and [SelectionFormField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/selectionformfield/constructor/llms-full.txt) take the width in twips that the field has while it is empty; 0 means a default width. The `SelectionFormField` overload used here takes the items and the index of the preselected one instead, where -1 selects none. [CheckFormField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/checkformfield/constructor/llms-full.txt) takes the initial state. - [Name](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textfield/name-property/llms-full.txt) identifies the value in your code, in conditional instructions and in exported PDF forms. [FormField.DescriptiveText](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/formfield/descriptivetext-property/llms-full.txt) adds a description for screen readers. - `AddFormField` is the helper of [Create a PDF Form](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/pdf/form/#insert-the-form-fields), which explains how [FormFieldCollection.Add](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/formfieldcollection/add-method/llms-full.txt) and the input position work together. Each type has its own settings: [SelectionFormField.Items](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/selectionformfield/items-property/llms-full.txt) for the list, [CheckFormField.Checked](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/checkformfield/checked-property/llms-full.txt) with the characters for both states, and [DateFormField.Date](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/dateformfield/date-property/llms-full.txt) with a [DateFormat](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/dateformfield/dateformat-property/llms-full.txt), which uses the format of the text's culture when it is empty. [FormField.Enabled](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/formfield/enabled-property/llms-full.txt) set to `false` keeps users from filling in a single field of a protected form. ### Let Users Fill Out the Form A form is ready for users when everything except the form fields is protected. Users of TX Text Control Words do this on the **Permissions** tab: they select **Fill in Form Fields** and **Read Only** and click **Enforce Protection**, optionally with a password. ![The Permissions tab with Fill in Form Fields, Read Only and Enforce Protection selected, and the Enforce Protection dialog box asking for an optional password.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/permissions-form-fields.9d1cd2f9.webp) In code, it takes three settings: ```csharp private void protectFormButton_Click(object sender, EventArgs e) { // Users can fill in the form fields and change nothing else textControl1.DocumentPermissions.AllowEditingFormFields = true; textControl1.DocumentPermissions.ReadOnly = true; textControl1.EditMode = EditMode.ReadAndSelect; } ``` - [DocumentPermissions.ReadOnly](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/documentpermissions/readonly-property/llms-full.txt) protects the text, and [AllowEditingFormFields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/documentpermissions/alloweditingformfields-property/llms-full.txt) keeps the form fields editable. - [EditMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/editmode-property/llms-full.txt) `ReadAndSelect` enforces the permissions. [CanEditFormFields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/caneditformfields-property/llms-full.txt) tells whether form fields can be edited in the current state. [Document Protection and Editable Regions](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/protection/llms-full.txt) explains document permissions, passwords and editable regions. ### Read the Values The values are in the form fields: the `Text` of text, selection and date fields, `Checked` of check boxes and `Date` of date fields: ```csharp private void readValuesButton_Click(object sender, EventArgs 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(values.ToString()); } ``` `StringBuilder` needs `using System.Text;`. To react to each entry, handle one event per type. Each handler receives the field that has changed: | Event | Occurs when | Event arguments | |---|---|---| | [FormFieldTextChanged](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/formfieldtextchanged-event/llms-full.txt) | The text of a text form field has been changed and the field is left | [TextFormFieldEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textformfieldeventargs/llms-full.txt) | | [FormFieldCheckChanged](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/formfieldcheckchanged-event/llms-full.txt) | A check box has been checked or unchecked | [CheckFormFieldEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/checkformfieldeventargs/llms-full.txt) | | [FormFieldSelectionChanged](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/formfieldselectionchanged-event/llms-full.txt) | An item has been selected, or a new text typed and the field left | [SelectionFormFieldEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/selectionformfieldeventargs/llms-full.txt) | | [FormFieldDateChanged](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/formfielddatechanged-event/llms-full.txt) | A date has been picked, or a valid date typed and the field left | [DateFormFieldEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/dateformfieldeventargs/llms-full.txt) | ```csharp public Form1() { InitializeComponent(); textControl1.FormFieldCheckChanged += textControl1_FormFieldCheckChanged; } private void textControl1_FormFieldCheckChanged(object sender, CheckFormFieldEventArgs e) { Text = e.CheckFormField.Name + ": " + e.CheckFormField.Checked; } ``` The events report changes made by the user. They aren't raised when your code changes a value through a property such as `CheckFormField.Checked`, `SelectionFormField.SelectedIndex` or `DateFormField.Date`. ### Validate Entries With Conditional Instructions A *conditional instruction* consists of conditions on the values of form fields and instructions that are carried out when the conditions are fulfilled. An instruction can enable or disable a form field, mark its value as valid or invalid, set a value, or replace the items of a drop-down list. For example: "If the number of nights is less than 2 or greater than 14, mark it as invalid." The rules are stored in the document and run while the form is filled out, so the form checks itself without code in your application. Users work with conditional instructions in the **Form Validation** group of the **Form Fields** tab: **Enable Form Validation** turns validation on, **Manage Conditional Instructions** shows the **Conditional Instructions** sidebar with the rules of the document, and **Highlight Invalid Values** marks the values that a rule has found invalid. In your form, connect the sidebar with the [ConditionalInstructionsSidebar](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonformfieldstab/conditionalinstructionssidebar-property/llms-full.txt) property of the tab; [Sidebar and Panels](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/sidebar/llms-full.txt) describes sidebars. ![TX Text Control Words with the Form Fields tab, the booking request form and the Conditional Instructions sidebar showing the conditions and actions of Validate Arrival.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/conditional-instr-sidebar.0bb7d792.webp) [Conditional Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/conditional-instructions/llms-full.txt) explains how to turn on validation, create rules in the dialog box and in C#, combine conditions, use else, initial and change instructions and check invalid values, and builds the complete rules of a booking form. The TX Text Control Words sample *Conditional Instructions*, installed in *%USERPROFILE%\\Documents\\TX Text Control 34.0.NET for Windows Forms\\CSharp\\TX Words\\Conditional Instructions*, loads a booking form with conditional instructions and previews it as a protected form. 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 a complete form with rules. ### Preview the Form While you design a form, you want to try out its rules without losing the unprotected template. The TX Text Control Words sample *Conditional Instructions* does this with a **Preview** button: it saves the document and its permissions, protects the document as a form and, when the preview ends, loads the saved document again. The following handler is a toggle button of the same kind; it needs [IsFormFieldValidationEnabled](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/isformfieldvalidationenabled-property/llms-full.txt) to be `true`, because otherwise the rules don't run: ```csharp private byte[] formTemplate; private bool savedAllowEditingFormFields; private bool savedReadOnly; private void previewButton_Click(object sender, EventArgs e) { if (formTemplate == null) { // Keep the template and its permissions textControl1.Save(out formTemplate, BinaryStreamType.InternalUnicodeFormat); savedAllowEditingFormFields = textControl1.DocumentPermissions.AllowEditingFormFields; savedReadOnly = textControl1.DocumentPermissions.ReadOnly; // Protect the document as a form: the initial instructions run textControl1.DocumentPermissions.AllowEditingFormFields = true; textControl1.DocumentPermissions.ReadOnly = true; textControl1.EditMode = EditMode.ReadAndSelect; } else { // Loading the template also resets the edit mode textControl1.Load(formTemplate, BinaryStreamType.InternalUnicodeFormat); formTemplate = null; textControl1.DocumentPermissions.AllowEditingFormFields = savedAllowEditingFormFields; textControl1.DocumentPermissions.ReadOnly = savedReadOnly; } } ``` The code works as follows: - [Save](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/save-method/llms-full.txt) with [BinaryStreamType](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/binarystreamtype/enumeration/llms-full.txt) `InternalUnicodeFormat` writes the whole document to a byte array in the TX Text Control format. - The three settings of [Let Users Fill Out the Form](#let-users-fill-out-the-form) turn the document into a form. Everything the user enters during the preview changes only this copy. - [Load](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/load-method/llms-full.txt) with the same byte array brings back the template as it was before the preview. The edit mode doesn't have to be reset, because loading the saved content already does that; the two document permissions are restored by hand. The sample also hides the ribbon groups to the right of **Form Validation** and disables **Enable Form Validation** while the preview is on. Turn on **Highlight Invalid Values** to see which values the rules mark as invalid. The **Preview** button is at the right of the **Form Validation** group, as the picture in [Validate Entries With Conditional Instructions](#validate-entries-with-conditional-instructions) shows. ### Save and Export Forms Form fields are saved and loaded with the TX Text Control format and with DOC, DOCX and RTF. When a Word document is loaded, its form fields become TX Text Control form fields, unless [LoadSettings.ApplicationFieldFormat](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/loadsettings/applicationfieldformat-property/llms-full.txt) loads them as MS Word fields. Saved as PDF, form fields become fillable PDF form fields with their names and values; [PDF Forms](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/pdf/forms/llms-full.txt) shows how to create, read and flatten PDF forms, and [Forms and Conditional Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/form-fields/llms-full.txt) in Document Processing works with form fields without a user interface. ### Next Steps - [Conditional Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/conditional-instructions/llms-full.txt): all conditions and instructions, and a complete booking form. - [Signature Fields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/signature-fields/llms-full.txt): places for signatures in a form. - [Document Protection and Editable Regions](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/protection/llms-full.txt): permissions, passwords and editable regions. - [Events](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/events/llms-full.txt): all form field events. - [PDF Forms](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/pdf/forms/llms-full.txt): forms in PDF documents. --- ## Nearby - **Previous:** [Subtext Parts](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/subtext-parts/llms-full.txt) - **Next:** [Signature Fields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/signature-fields/llms-full.txt)