What's New in TX Text Control .NET for Windows Forms 28.0

Forms that users fill out in the TextControl arrived with version 28.0: four kinds of form fields, a ribbon tab to insert them and a rule engine, the conditional instructions, with its own dialog boxes and sidebar. The version also changed the class hierarchy of document targets, the bookmarks of a document, which can require changes to existing code.

Version 28.0 was released on March 16, 2020, as TX Text Control X18, together with TX Text Control .NET Server, TX Text Control .NET for WPF and TX Text Control ActiveX. The last full installer of version 28.0 is dated October 26, 2020, shortly after Service Pack 4. The features below are the ones added since version 27.0.

Version 28.0 at a Glance

Form Fields

Four new kinds of text fields let you design forms and let users fill them out. TextControl.FormFields returns the FormFieldCollection of the main text; headers, footers and text frames have their own, and ServerTextControl.FormFields gives the same access without a user interface. See Form Fields and Conditional Instructions for the editor and Forms and Conditional Instructions for document processing.

• Check boxes. A CheckFormField is checked or unchecked by the user. Its text can't be edited; it is the Unicode character for the checked or the unchecked state, set with CheckedCharacter and UncheckedCharacter.
• Text fields. A TextFormField is a text input field. EmptyWidth sets its width while it is empty.
• Selection fields. A SelectionFormField offers the user a combo box or a drop-down list, depending on whether its text can be changed. Items holds the entries.
• Date fields. A DateFormField holds a date that the user picks in a date control or types. DateFormat formats it.
• Enabled state. FormField.Enabled switches a form field on or off.
• Events. The TextControl raises FormFieldCheckChanged when a check box changes its state, FormFieldDateChanged when a date changes, FormFieldSelectionChanged when another item is selected and FormFieldTextChanged when the text of a text form field changes.
• Filling forms in protected documents. DocumentPermissions.AllowEditingFormFields keeps form fields editable when EditMode has been changed from Edit to ReadAndSelect. TextControl.CanEditFormFields tells whether form fields can be edited.
• Colors. TextControl.Colors.FormFieldColor sets the highlight color of form fields and ActiveFormFieldColor that of the form field with the current input position.
• File formats. Form fields are saved and loaded with the TX Text Control format, DOC, DOCX and RTF. A document saved as PDF contains them as PDF form fields. A form field of MS Word becomes a form field or an application field, depending on LoadSettings.ApplicationFieldFormat.
• Mouse and keyboard. Users work with form fields through their own mouse and keyboard assignments; Keyboard Shortcuts lists the keys of today's version.

The Form Fields Ribbon Tab

The RibbonFormFieldsTab is a ribbon tab for inserting and editing form fields. It works with the TextControl connected to the ribbon that hosts it. ConditionalInstructionsSidebar and ConditionalInstructionsHorizontalSidebar connect the tab to the sidebars that show the conditional instructions. Built-in Ribbon Tabs describes the ribbon tabs of today's version.

Conditional Instructions

Conditional instructions are a rule engine for forms, which brings logic and workflows into a document. A ConditionalInstruction holds a list of Instruction objects that are executed when its Condition objects are met. FormFieldCollection.ConditionalInstructions returns the ConditionalInstructionCollection of a document.

• Conditions. A condition is met when the value of its form field compares successfully with a required value.
• Instructions. An instruction does one of four things to a form field: it changes FormField.Enabled, marks the value as valid or invalid, sets a new value or replaces the Items of a selection field.
• Else values. An instruction can have an else value, which is applied when the conditions aren't met.
• Dialog boxes. TextControl.ManageConditionalInstructionsDialog opens a dialog box that adds, edits and deletes the instructions of a document. ConditionalInstructionDialog opens the dialog box that creates or edits one instruction; it also opens from the Conditional Instructions sidebar.
• Protected documents. TextControl.IsFormFieldValidationEnabled decides whether conditional instructions are applied when EditMode is ReadAndSelect and the document permissions make the document read-only. Its default value is false.

Form Fields and Conditional Instructions shows how to validate entries with conditional instructions, and Sidebar and Panels describes the sidebars.

Document Targets and Bookmarks

A DocumentTarget is a bookmark: a position in the document that a link can point to.

• Any position. A document target can be inserted at any text position, including inside a text field and at its beginning or end, and several targets can share one position. The built-in BookmarkDialog lets users insert several bookmarks at the same input position as well.
• No longer a text field. To make this possible, DocumentTarget no longer inherits from TextField. Members it used to inherit, such as the ID and ScrollTo, are now implemented by DocumentTarget itself, and inherited members that had no meaning for a target, such as Text and Editable, are gone.
• Events. TextControl.DocumentTargetCreated and DocumentTargetDeleted pass a DocumentTargetEventArgs object. DocumentTargetCollection.GetItems is also new.
• Text field events of ServerTextControl. TextFieldCreated and TextFieldDeleted of ServerTextControl occur when a text field is created or deleted.

Fields, Hyperlinks, and Bookmarks shows how to insert bookmarks.

Dialog Boxes and Ribbons

• Measuring unit. TextControl.DialogUnit sets the unit of sizes and distances in the built-in dialog boxes. With Auto, the unit depends on the culture of the current thread; Centimeter, Inch and Millimeter set it explicitly. See Built-in Dialog Boxes.
• Ribbon list views. RibbonListView.SelectWithArrowKeys decides whether an item chosen with the arrow keys is also selected, and EditItemTextBoxEmptyWidth sets the width of the edit box of an item without text.

Upgrade to Version 28.0

• DocumentTarget no longer inherits from TextField. Code that treats a DocumentTarget as a TextField, casts it to one or calls a member that only TextField has, such as Text or Editable, doesn't compile against version 28.0. Use the members of DocumentTarget itself, such as TargetName.
• TextFieldType.DocumentTarget removed. The value DocumentTarget of the TextFieldType enumeration was removed. Code that passes it, for example to GetTextFields, has to change; the targets of the main text are in TextControl.DocumentTargets.
• Update notes. TextFieldType was extended with CheckFormField, DateFormField, SelectionFormField, TextFormField and FormFields. LoadSettings.ApplicationFieldFormat accepts the new value MSWordTXFormFields of ApplicationFieldFormat, which loads the form fields of MS Word as form fields of TX Text Control.
• Other breaking changes. Breaking Changes starts with version 30.0.

New Classes, Properties, Methods and Events

These are the classes and members that the What's New documentation of version 28.0 lists for TX Text Control .NET for Windows Forms. Names are relative to the TXTextControl namespace. Each name links to its current reference page. The list includes the members of ServerTextControl, the document processing class without a user interface that is part of this product too.

New Classes

• CheckFormField
• CheckFormFieldEventArgs
• Condition
• ConditionalInstruction
• ConditionalInstructionCollection
• DateFormField
• DateFormFieldEventArgs
• DocumentTargetEventArgs
• FormField
• FormFieldCollection
• Instruction
• SelectionFormField
• SelectionFormFieldEventArgs
• TextFormField
• TextFormFieldEventArgs
• Windows.Forms.Ribbon.RibbonFormFieldsTab

.NET Members by Class

Next Steps

• Version 29.0: the features of the next version.
• Version 27.0: the features of the previous version.
• Older Versions: all versions from 29.0 back to 10.1.
• TX Text Control X18 has been Released: the release announcement on the Text Control Blog.