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

Form fields and the rules that connect them are the main addition of version 28.0, and TX Text Control .NET for WPF received a ribbon tab, dialog boxes and a sidebar for both. Document targets, the bookmarks of a document, changed their class hierarchy in this version, 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 Windows Forms 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 does the same without a user interface. See Form Fields and Conditional Instructions and, for code without a visible control, Forms and Conditional Instructions.

• 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 is 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 selects in a date control or types. DateFormat formats it.
• Enabled state. FormField.Enabled switches a form field on or off.
• Events. TextControl raises FormFieldCheckChanged when the check state changes, FormFieldDateChanged for a new date, FormFieldSelectionChanged for a newly selected item and FormFieldTextChanged when the text of a text form field changes.
• Filling forms in protected documents. DocumentPermissions.AllowEditingFormFields keeps form fields editable when the edit mode has been changed from Edit to ReadAndSelect. TextControl.CanEditFormFields tells whether form fields can be edited under the current permissions and edit mode. See Document Protection and Editable Regions.
• Colors. TextControlColors.FormFieldColor and ActiveFormFieldColor set the highlight colors of form fields and of the form field that contains the input position.
• Ribbon. The new RibbonFormFieldsTab, connected through TextControl.RibbonFormFieldsTab, is a ribbon tab for inserting and editing form fields.
• 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.
• Keyboard and mouse. Form fields have keys and mouse actions of their own, listed in Form Fields and Conditional Instructions.

Conditional Instructions

Conditional instructions are a rule engine for forms. 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 lists the instructions of the document, and ConditionalInstructionDialog one that defines a single instruction.
• Sidebar. The Conditional Instructions sidebar manages the instructions beside the document. RibbonFormFieldsTab.ConditionalInstructionsSidebar and ConditionalInstructionsHorizontalSidebar name the sidebars that the ribbon tab opens.
• Protected documents. TextControl.IsFormFieldValidationEnabled sets whether conditional instructions are applied while the document is read-only and the edit mode is ReadAndSelect. The default is false.

Form Fields and Conditional Instructions shows conditional instructions at work, and Sidebar and Panels connects sidebars to the ribbon.

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 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. DocumentTargetCreated and DocumentTargetDeleted of TextControl pass a DocumentTargetEventArgs object. DocumentTargetCollection.GetItems is also new.

See Fields for links and bookmarks today.

Dialog Boxes

TextControl.DialogUnit sets the measuring unit of sizes and distances in the built-in dialog boxes. Built-in Dialog Boxes lists the dialog boxes.

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 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.

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 WPF. Names are relative to the TXTextControl namespace. Each name links to its current reference page.

New Classes

• CheckFormField
• CheckFormFieldEventArgs
• Condition
• ConditionalInstruction
• ConditionalInstructionCollection
• DateFormField
• DateFormFieldEventArgs
• DocumentTargetEventArgs
• FormField
• FormFieldCollection
• Instruction
• SelectionFormField
• SelectionFormFieldEventArgs
• TextFormField
• TextFormFieldEventArgs
• WPF.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.