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

A TextControl that rescales itself when its window moves to a display with another scale factor, and tables of contents with their own dialog box and ribbon tab, are the Windows Forms additions of version 29.0. The version also brought the DocumentSettings class with a sidebar to edit it, files embedded in PDF documents, the DocumentServer.PDF namespace and barcodes as part of TX Text Control itself.

Version 29.0 was released on December 2, 2020, as TX Text Control X19, together with TX Text Control .NET Server, TX Text Control .NET for WPF, TX Text Control ActiveX and TX Spell .NET 8.0. Its last full installer, that of Service Pack 3, is dated July 21, 2021. The features below are the ones added since version 28.0; the next version is Version 30.0.

Version 29.0 at a Glance

Per-Monitor DPI Awareness

Since the Windows 10 Creators Update (version 1703), an application is drawn for the DPI of the display on which most of its main window is. With version 29.0, a TextControl supports setups with several displays of different scale factors: when the application moves from one display to another, or the scale factor changes while it runs, the TextControl and all its toolbars and ribbons change their scaling at once.

In the .NET Framework 4.7 and later, this high DPI support is opt-in and is switched on in the application's configuration file. The TX Words sample programs of this version contain such a configuration file. High DPI and Display Scaling shows the configuration for today's applications.

Tables of Contents

A table of contents is generated from the structure level of the paragraphs in a document. See Tables of Contents.

• Structure levels. ParagraphFormat.StructureLevel sets the level of a paragraph, from 0 to 10, where 0 means that the paragraph belongs to the body of the document. The level is usually part of a ParagraphStyle rather than set per paragraph. The dialog box for paragraph attributes received a field for the structure level.
• For the user. TextControl.TableOfContentsDialog opens a dialog box in which the user sets all parameters of a new table of contents. The RibbonReferencesTab, also new, is a ribbon tab for creating and editing tables of contents.
• In code. Create a TableOfContents object and add it with TableOfContentsCollection.Add. The collection of the main text is TextControl.TablesOfContents; headers, footers and text frames have their own. The table is inserted at the current input position, with or without page numbers.
• What it contains. MinimumStructureLevel and MaximumStructureLevel select the paragraphs. A title, a highlight color and a highlight mode, HighlightMode, complete the settings. A document can hold several tables of contents with different levels.
• Styles. The entries take the font and paragraph attributes of the paragraphs they list. TX Text Control also creates a formatting style for the title and each level, named TOC_Title, TOC_Level1, TOC_Level2 and so on, so that users can change the appearance through the styles.
• Links. With HasLinks, each entry becomes a DocumentLink with a matching document target. A click on an entry with the CTRL key held down scrolls to its page. DocumentLink.AutoGenerationType tells whether a link was created this way.
• Updates and events. TableOfContents.Update regenerates the entries. TableOfContentsCreated, TableOfContentsDeleted, TableOfContentsEntered and TableOfContentsLeft occur on the TextControl.
• Tab leaders. ParagraphFormat.TabLeaders, also new, sets the characters that fill the space before a tab position, such as the dots before a page number.

Document Settings

TextControl.DocumentSettings returns a DocumentSettings object with the general settings of the document the user works on: author, creation date, creator application, base path, keywords, subject, title, embedded files and user-defined properties. The values can be changed while the document is open. Save stores them with the document, and a property of SaveSettings with the same name overrides a value for one save. See Document Properties.

The Document Settings Sidebar

The Sidebar received a layout for the document settings, the value DocumentSettings of SidebarContentLayout. It shows the following settings:

• Title, author, subject and keywords in text boxes the user edits.
• The creation date, set to the current date when the content of the TextControl is reset, or the creation date of a loaded document.
• Custom properties, the user-defined document properties. Add... opens the Add Custom Property dialog box, and Delete removes a property.
• Embedded files in PDF. Add... opens a file dialog and sets a MIME type that fits the file extension; Edit... opens the Edit Embedded File dialog box for the MIME type, the relationship and the description; Save... saves an embedded file and Remove deletes it. The files are loaded only if LoadSettings.PDFImportSettings includes LoadEmbeddedFiles, and they are saved only in PDF documents.

Controls of the sidebar that an application doesn't need are hidden or removed through Sidebar.FindItem and the values of Sidebar.DocumentSettingsItem. Sidebar and Panels describes the sidebar and its layouts.

PDF Documents

Version 29.0 extended both directions of the PDF support: files can be embedded when a PDF is saved, and a new namespace reads data out of existing PDF documents.

• Embedded files. EmbeddedFile holds a file and its data, with optional properties such as the MIME type, the relationship, a description and dates. LoadSaveSettingsBase.EmbeddedFiles, available as SaveSettings.EmbeddedFiles and LoadSettings.EmbeddedFiles, embeds files when a PDF is saved and returns them when a PDF is loaded. To load them, LoadSettings.PDFImportSettings has to include LoadEmbeddedFiles. See Attachments.
• AcroForm import. DocumentServer.PDF.Forms.GetAcroFormFields returns the form fields of a PDF document as AcroForms.FormField objects: text fields, check boxes, choice fields, combo boxes, list boxes, radio buttons and buttons. Its typical use is reading the values of a form that users filled out. See Reading Form Fields and Values.
• Text search. DocumentServer.PDF.Contents.Lines.Find searches the lines of a PDF document for a string, a regular expression or a geometric position and returns ContentLine objects with the text, the page and the position of each line. See Text Extraction.

Mail Merge

MailMerge creates documents from a template and data. Its repeating merge blocks, sections of the template that are repeated for each record, carry filter and sorting information since version 26.0, and version 29.0 made that information editable in code.

• MergeBlockInfo from an existing block. A new MergeBlockInfo constructor creates the object from a merge block of a template, a SubTextPart. The object then contains the block's Filters, SortingInstructions, merge fields, child blocks and the name of its data table.
• Write it back. After the information is changed, MergeBlockInfo.Apply stores it in the document.

Sorting and Filtering describes filters and sorting instructions.

Subtext Parts

SubTextPart.GetChildren returns the subtext parts nested in a subtext part, and SubTextPart.GetTextFields the text fields it contains. See Subtext Parts.

Ribbons and Styles

• Quick access toolbar. RibbonForm.QuickAccessToolbarPosition places the quick access toolbar above or below the ribbon.
• Minimized ribbon. Ribbon.Minimized shows the ribbon minimized when the application starts.
• Drop-down menus in list views. When the view mode of a RibbonListView includes ListViewMode.DropDown, each item shows a drop-down menu. The new RibbonListViewItemDropDown class holds its settings, and the events ItemDropDownOpening and ItemDropDownClosed report when it opens and closes.
• Style changes. TextControl.FormattingStyleChanged occurs after the attributes of one or more formatting styles have changed.

Built-in Ribbon Tabs describes the ribbon of today's version.

Barcodes

The barcode component TX Barcode .NET became part of TX Text Control, so barcodes no longer need a separate product. Barcode.TXBarcodeControl creates a barcode. In a document, a barcode is a BarcodeFrame in a BarcodeCollection, positioned like an image or a text frame. The new Barcode.BarcodeTypeSettings class sets whether a barcode has a check value and whether it shows it. See Charts and Barcodes.

Upgrade to Version 29.0

• Update notes. The update notes of version 29.0 list one entry: LoadSettings.PDFImportSettings was extended with the settings LoadEmbeddedFiles, LoadMetadata and GenerateXMLAsEmbeddedFile. Of the three, only LoadEmbeddedFiles is a value of the current PDFImportSettings enumeration. Today, the metadata, the form fields and the text coordinates of a PDF document come from LoadEmbeddedData and LoadSettings.EmbeddedData. The What's New documentation of version 30.0 repeats the same entry.
• Breaking changes. No change of version 29.0 is known to break existing code. 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 29.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

• Barcode.BarcodeTypeSettings
• Barcode.TXBarcodeControl
• DocumentLink
• DocumentServer.PDF.AcroForms.FormButton
• DocumentServer.PDF.AcroForms.FormCheckBox
• DocumentServer.PDF.AcroForms.FormChoiceField
• DocumentServer.PDF.AcroForms.FormComboBox
• DocumentServer.PDF.AcroForms.FormField
• DocumentServer.PDF.AcroForms.FormListBox
• DocumentServer.PDF.AcroForms.FormRadioButton
• DocumentServer.PDF.AcroForms.FormTextField
• DocumentServer.PDF.Contents.ContentLine
• DocumentServer.PDF.Contents.Lines
• DocumentServer.PDF.Forms
• DocumentSettings
• DocumentTarget
• EmbeddedFile
• TableOfContents
• TableOfContentsCollection
• TableOfContentsEventArgs
• Windows.Forms.Ribbon.RibbonListView.RibbonListViewItemDropDown
• Windows.Forms.Ribbon.RibbonReferencesTab

.NET Members by Class

Next Steps

• Version 30.0: the features of the next version.
• Version 28.0: the features of the previous version.
• Older Versions: all versions from 29.0 back to 10.1.
• TX Text Control X19 and TX Spell 8.0 Have Been Released: the release announcement on the Text Control Blog.