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

Version 24.0 gave Windows Forms applications a ribbon: a RibbonForm main window, a Ribbon with an application menu and contextual tabs, and predefined tabs that cover the features of the TextControl. Colored paragraphs, user-defined document properties, zoom options, typed exceptions and a mail merge that reads JSON data came with it, together with dialog boxes and the DataSourceManager class for building mail merge templates.

Version 24.0 was released on November 30, 2016, as TX Text Control X14, together with TX Text Control .NET Server, TX Text Control .NET for WPF and TX Text Control ActiveX. Its last full installer, that of Service Pack 2, is dated June 13, 2017. The features below are the ones added since version 23.0.

Version 24.0 at a Glance

Area	What is new
Ribbons	`RibbonForm`, `Ribbon`, predefined ribbon tabs, contextual tab groups, a quick access toolbar
Viewing and toolbars	Zooming to the whole page, the page width or the text width, read-only toolbars
Formatting	Colored paragraph backgrounds and frame lines, new `InputFormat` properties, paper sizes of the printer
Documents	User-defined document properties, encrypted PDF import, typed exceptions
Text fields	Text fields of several types in document order
Mail merge	JSON data, the template location in merge events, `DataSourceManager` and dialog boxes for merge blocks and data sources

Windows Forms Ribbon Controls

The class library received the controls to build a Windows Forms application with a ribbon instead of a menu and toolbars. See Built-in Ribbon Tabs.

The main window. The form inherits from RibbonForm, which draws the quick access toolbar and the contextual tabs in its border. SetQuickAccessToolbarStandardItems sets the standard items of the quick access toolbar; users add and remove further items through a context menu.
The ribbon. A Ribbon docked at the top of the window has the application menu as its first tab, filled through ApplicationMenuItems, and arranges the commands of the application in RibbonTab controls. The tabs hold groups of buttons, split buttons, toggle buttons, combo boxes, text boxes and list views. TextControl.Ribbon connects the TextControl with the ribbon.
Contextual tabs. Tabs that are only relevant in a particular context are grouped and added to the ContextualTabGroupCollection that Ribbon.ContextualTabGroups returns.
Predefined tabs. RibbonFormattingTab and RibbonInsertTab cover the general editing features. RibbonPageLayoutTab edits the page setup, RibbonFrameLayoutTab images, text frames, drawings, barcodes and charts, and RibbonTableLayoutTab tables. RibbonProofingTab sets spelling, hyphenation and language options, RibbonViewTab the view settings, and RibbonReportingTab adds mail merge and reporting. The FindItem method of each tab returns one of its items, so that an application can change or hide it.
Appearance and read-only mode. Ribbon.DisplayColors sets the colors of the tabs and the application menu. A ribbon with ReadOnly set to true still shows the formatting attributes of the connected TextControl, but they can't be changed.

Custom Tabs and Commands adds tabs and groups of your own.

Viewing and Toolbars

Zoom options. TextControl.Zoom zooms the content so that the whole page, the width of the page or the complete text of a line is visible, selected with the new ZoomOption enumeration. The StatusBar received two buttons for these options. See Viewing, Zooming, and Navigation.
Read-only toolbars. A ButtonBar or RulerBar with ReadOnly set to true shows the formatting attributes of the connected TextControl without letting the user change them. See Toolbars and Mini Toolbars.
Frame events. The TextControl raises events for frames, the images, text frames and other objects placed in a document, such as FrameClicked, FrameSelected, FrameMoved and FrameSized. TextFrameAppearanceChanged occurs when the background, the transparency, the border or the inner margins of a text frame change.

Colored Paragraphs and Text Formatting

Paragraph colors. ParagraphFormat.BackColor colors the background of a paragraph and ParagraphFormat.FrameLineColor the lines of its frame. The InputFormat class, the dialog box for paragraph attributes, the TX Text Control format and all filters support the colors.
InputFormat. TopAligned, BottomAligned and VerticallyCentered set the vertical text alignment. FrameFillColor sets the background of table cells, FrameLineColor the frame color and FrameLineWidth the width of frame lines.
Color dialogs. FrameFillColorDialog, FrameLineColorDialog and PageColorDialog open the built-in dialog boxes for these colors and the page color. LoadSettings.LoadDocumentBackColor and SaveSettings.SaveDocumentBackColor decide whether the background color of a document is loaded and saved.
Styles. FormattingStyle.BaseStyle returns the style a style is based on, and Selection.RemoveInlineStyles removes inline styles from the selected text.

See Text and Paragraph Formatting.

Paper Sizes

TextControl.GetSupportedPaperSizes returns the names and sizes of all paper sizes that are supported at the moment, as PaperSize objects. The list depends on the formatting device, set with TextControl.FormattingPrinter. See Sections, Pages, Headers, and Footers.

User-Defined Document Properties

SaveSettings.UserDefinedDocumentProperties takes a UserDefinedPropertyDictionary with properties of the types String, Boolean, Int32 and Double, which are saved with the document. The TX Text Control format, RTF, DOC and DOCX support them. After a document is loaded, LoadSettings.UserDefinedDocumentProperties returns them. See Document Properties.

Text Fields

IFormattedText.GetTextFields and TextControl.GetTextFields return the text fields of one or more field types. With several types, the fields are in the order in which they appear in the document. PageNumberFieldCollection.GetItem gets one page number field of a collection. See Fields, Hyperlinks, and Bookmarks.

PDF Import and Error Handling

Encrypted PDF files. PDF import loads encrypted files. See Passwords and Access Permissions.
Typed exceptions. A TextControl throws a TextEditorException when an error occurs while text is edited and a FilterException, with its Reason, when a document can't be converted from or to another format. A LicenseLevelException means that the licensed product level doesn't contain a feature.
Standard exceptions. A parameter or property value that is wrong raises an ArgumentException, an ArgumentNullException or an ArgumentOutOfRangeException, and a call that is invalid in the object's current state an InvalidOperationException.

See Exceptions and Error Handling.

Mail Merge

MailMerge creates documents from a template and data.

JSON data. MailMerge.MergeJsonData merges a JSON string with a single object or an array of objects with the same structure. See JSON and XML.
Where an event occurred. Most events of a merge run tell where in the template they occurred: FieldMergedEventArgs, ImageMergedEventArgs and ImageFieldMergedEventArgs received MergeBlockName, NestingDepth and, depending on the class, TableCell and DataRow. See Merge Events.
Data source information. DataSourceManager handles the supported kinds of data, from data sets and data tables to JSON, XML, objects and assemblies, describes their tables, columns and relations, inserts merge block templates and merges. The classes DataTableInfo, DataColumnInfo, DataRelationInfo, MergeBlockInfo and MergeBlockSettings came with it, and RibbonReportingTab.DataSourceManager gives the reporting tab its data.
Merge block names. MailMerge.MergeBlockNamePrefix returns the prefix txmb_ of internal merge block names, and LoadSaveSettingsBase.ReportingMergeBlockFormat sets how merge blocks are saved in a document.

Dialog Boxes for Templates

The new namespace DocumentServer.Windows.Forms holds modal dialog boxes, each shown with its ShowDialog method:

Dialog box	Lets the user
InsertMergeBlockDialog	Design a merge block based on the current data source and insert it
EditMergeBlocksDialog	Remove or rename the merge blocks of the document
DatabaseConnectionDialog	Build a connection string and connect to a data source
EditDataRelationsDialog	Add data relations to the data source or remove them
DataSourceExtractionDialog	Save an excerpt of the loaded data source

Reporting Ribbon and Dialog Boxes describes the reporting tab and its dialog boxes today.

Upgrade to Version 24.0

Update notes. DrawingFrame.Refresh received an overload that refreshes part of a drawing. MailMerge.MergeObjects also merges collections of System.Collections.Generic.Dictionary objects with string keys. BarcodeLayoutDialog, DrawingLayoutDialog, ImageAttributesDialog and TextFrameAttributesDialog of TextControl received overloads that select the tab shown when the dialog box opens.
Breaking changes. No change of version 24.0 for Windows Forms 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 24.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, and it also names classes that existed before, such as ParagraphFormat, as it appears in that documentation.

New Classes

.NET Members by Class

Class	Properties	Methods	Events
ButtonBar	ReadOnly
DocumentServer.DataSources.DataColumnInfo	Caption, ColumnName, DataTableInfo, DataType
DocumentServer.DataSources.DataColumnInfoCollection	Count, IsReadOnly, Item	CopyTo, GetEnumerator
DocumentServer.DataSources.DataRelationInfo	ChildColumnName, ChildTableName, ParentColumnName, ParentTableName, RelationName
DocumentServer.DataSources.DataRelationInfoCollection	Count, IsReadOnly, Item	CopyTo, GetEnumerator
DocumentServer.DataSources.DataSourceManager	ConnectionString, DataProviderName, DataRelations, DataTables, IsMergingPossible, MasterDataTableInfo, PossibleMergeBlockTables, PossibleMergeFieldColumns	InsertMergeBlock, IsMergeBlock, LoadAssembly, LoadDataSet, LoadDataSourceConfig, LoadDataTable, LoadJson, LoadObjects, LoadSingleObject, LoadXmlFile, LoadXmlString, Merge, SaveDataSourceConfig	ConnectionStringChanged, DataProviderNameChanged, DataRelationsChanged, DataTablesChanged, IsMergingPossibleChanged, MasterDataTableInfoChanged, PossibleMergeBlockTablesChanged, PossibleMergeFieldColumnsChanged
DocumentServer.DataSources.DataTableInfo	ChildRelations, ChildTables, Columns, TableName
DocumentServer.DataSources.DataTableInfoCollection	Count, IsReadOnly, Item	CopyTo, GetEnumerator
DocumentServer.DataSources.MergeBlockInfo	ChildBlocks, ColumnNames, TableName
DocumentServer.DataSources.MergeBlockSettings	BlockTemplateType, CreateHeaderRow, FieldDisplayMode, HighlightColor
DocumentServer.MailMerge	MergeBlockNamePrefix	MergeJsonData
DocumentServer.MailMerge.DataRowMergedEventArgs	DataRow
DocumentServer.MailMerge.FieldMergedEventArgs	DataRow, MergeBlockName, NestingDepth, TableCell
DocumentServer.MailMerge.ImageFieldMergedEventArgs	MergeBlockName, NestingDepth, TableCell
DocumentServer.MailMerge.ImageMergedEventArgs	DataRow, MergeBlockName, NestingDepth
DocumentServer.Windows.Forms.DataSourceExtractionDialog	FileName, MaxRows, SelectedTable
DocumentServer.Windows.Forms.InsertMergeBlockDialog	AddTableHeaderRow, BlockType, HighlightColor, MergeBlockInfo
Drawing.ViewChangedEventArgs	ClipRectangle
FilterException	Reason
FormattingStyle	BaseStyle
FrameEventArgs	Frame
HeaderFooter		GetTextFields
IFormattedText		GetTextFields
InputFormat	BottomAligned, FrameFillColor, FrameLineColor, FrameLineWidth, TopAligned, VerticallyCentered
LoadSaveSettingsBase	ReportingMergeBlockFormat
LoadSettings	DocumentAccessPermissions, LoadDocumentBackColor, UserDefinedDocumentProperties
PageNumberFieldCollection		GetItem
PaperSize	Height, Name, Width
ParagraphFormat	AbsoluteLineSpacing, Alignment, BackColor, BottomDistance, Frame, FrameDistance, FrameLineColor, FrameLineWidth, FrameStyle, HangingIndent, LeftIndent, LineSpacing, RightIndent, TabPositions, TabTypes, TopDistance
RulerBar	ReadOnly
SaveSettings	SaveDocumentBackColor, UserDefinedDocumentProperties
Selection		RemoveInlineStyles
ServerTextControl		GetSupportedPaperSizes, GetTextFields, OnDocumentLoaded	DocumentLoaded
TextControl	Ribbon	FrameFillColorDialog, FrameLineColorDialog, GetSupportedPaperSizes, GetTextFields, OnDocumentLoaded, OnFrameClicked, OnFrameDeselected, OnFrameDoubleClicked, OnFrameLayoutChanged, OnFrameMoved, OnFrameRightClicked, OnFrameSelected, OnFrameSized, OnTextFrameAppearanceChanged, PageColorDialog, Zoom	DocumentLoaded, FrameClicked, FrameDeselected, FrameDoubleClicked, FrameLayoutChanged, FrameMoved, FrameRightClicked, FrameSelected, FrameSized, TextFrameAppearanceChanged
TextFrame		GetTextFields
UserDefinedPropertyDictionary	Item, Names, Values	Add, Contains, Remove
Windows.Forms.Ribbon.ContextualTabGroup	BackColor, ContextualTabs, Header, Name, Visible
Windows.Forms.Ribbon.DialogBoxLauncher	ContextMenuStrip, Enabled, ToolStripItemImage, ToolTip, Visible		Click
Windows.Forms.Ribbon.HorizontalRibbonGroup		Add, AddRange, Insert, InsertRange
Windows.Forms.Ribbon.Ribbon	ApplicationMenuHelpPaneItems, ApplicationMenuItems, ContextualTabGroups, DisplayColors, ReadOnly
Windows.Forms.Ribbon.Ribbon.Colors	ApplicationMenuColor, ApplicationMenuTabColor, ApplicationMenuTabHighlightColor, HighlightTabColor, MenuColor, TabColor	ResetApplicationMenuColor, ResetApplicationMenuTabColor, ResetApplicationMenuTabHighlightColor, ResetHighlightTabColor, ResetMenuColor, ResetTabColor
Windows.Forms.Ribbon.RibbonButton	Description, DisplayMode, IsAddToQuickAccessToolbarEnabled, KeyTip, LargeIcon, ParentCollection, SmallIcon, Text, ToolTip
Windows.Forms.Ribbon.RibbonComboBox	KeyTip, ParentCollection, ToolTip
Windows.Forms.Ribbon.RibbonForm		SetQuickAccessToolbarStandardItems
Windows.Forms.Ribbon.RibbonFormattingTab		FindItem
Windows.Forms.Ribbon.RibbonFrameLayoutTab		FindItem
Windows.Forms.Ribbon.RibbonGroup	DialogBoxLauncher, IsAddToQuickAccessToolbarEnabled, LargeIcon, RibbonItems, RowCount, ShowSeperator, SmallIcon, Text, ToolTip
Windows.Forms.Ribbon.RibbonGroupCollection	Item	Add, Insert, Remove
Windows.Forms.Ribbon.RibbonInsertTab		FindItem
Windows.Forms.Ribbon.RibbonItemCollection	Item	Add, AddRange, Contains, Insert, InsertRange, Remove
Windows.Forms.Ribbon.RibbonLabel	ParentCollection, SmallIcon, Text, ToolTip
Windows.Forms.Ribbon.RibbonListView	CellPadding, ColumnCount, ColumnWidth, Deselectable, DropDownItems, HideItems, HideSelectedItems, ItemsSource, KeyTip, MaxVisibleRows, MinColumnCount, MultiSelect, ParentCollection, RibbonListViewItems, RowCount, RowHeight, ScrollButtonsVisible, SelectedIndices, SelectedItems, ShowBorder, ShowItemsInDropDown, ToolTip, ViewMode	ScrollTo	DropDownClosed, DropDownOpening, ItemClick, ItemMouseEnter, ItemMouseLeave
Windows.Forms.Ribbon.RibbonListView.RibbonListViewItem	Icon, IsSelected, Tag, Text, ToolTip
Windows.Forms.Ribbon.RibbonListView.RibbonListViewItemCollection	Item	Add
Windows.Forms.Ribbon.RibbonListView.RibbonListViewItemEventArgs	Item
Windows.Forms.Ribbon.RibbonMenuButton	DropDownItems		DropDownClosed, DropDownOpening
Windows.Forms.Ribbon.RibbonPageLayoutTab		FindItem
Windows.Forms.Ribbon.RibbonProofingTab		FindItem
Windows.Forms.Ribbon.RibbonReportingTab	DataSourceManager	FindItem
Windows.Forms.Ribbon.RibbonSeperator	Alignment, ParentCollection
Windows.Forms.Ribbon.RibbonSplitButton	ButtonEnabled, Checkable, Checked		ButtonClick, CheckedChanged
Windows.Forms.Ribbon.RibbonTab	KeyTip, RibbonGroups
Windows.Forms.Ribbon.RibbonTableLayoutTab		FindItem
Windows.Forms.Ribbon.RibbonTextBox	DisplayMode, KeyTip, Label, LargeIcon, ParentCollection, ShowUpDownButtons, SmallIcon, Text, TextAlign, TextBoxLabel, TextBoxWidth, ToolTip, ValidationMode		DownButtonClicked, TextValidated, UpButtonClicked
Windows.Forms.Ribbon.RibbonToggleButton	Checked		CheckedChanged
Windows.Forms.Ribbon.RibbonToolTip	Description, Title		Opening
Windows.Forms.Ribbon.RibbonViewTab		FindItem

Next Steps

Version 25.0: the features of the next version.
Version 23.0: the features of the previous version.
Older Versions: all versions from 29.0 back to 10.1.
TX Text Control X14 for Windows Forms, WPF, ASP.NET and ActiveX Released: the release announcement on the Text Control Blog.

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