What's New in Version 23.0 — TX Text Control .NET Server

Drawings, subtext parts and document properties are the additions of version 23.0 that TX Text Control .NET Server still builds on. The version also changed how merge blocks are stored in mail merge templates, and it let the Document Editor connect to the TX TextControl Service on another server.

Version 23.0 was released on December 9, 2015, as TX Text Control X13, together with TX Text Control .NET for Windows Forms, TX Text Control .NET for WPF and TX Text Control ActiveX. Its last full installer, that of Service Pack 1, is dated August 8, 2016. The features below are the ones added since version 22.0.

Version 23.0 at a Glance

Area	What is new
Drawings	Drawings and preset shapes compatible with MS Word
Formatted text	Subtext parts, collections for all text parts, symbol characters, Unicode bullets
Documents	Author, dates, keywords and subject saved with every format
Mail merge	Merge blocks as subtext parts, `MergeObject`, the `BlockMerging` event
Document Editor	Culture settings, a service on another server, an ASP.NET MVC helper, loading and saving in JavaScript

Drawings and Shapes

TX Text Control supports drawings and the preset shapes of ISO/IEC 29500-1, section 20.1.10.55. A drawing is a single shape or a canvas with several shapes. See Text Frames and Shapes and, for the Document Editor, Shapes.

Positioning. A DrawingFrame positions the drawing like an image or a text frame: as a single character, anchored to a paragraph or at a fixed position in the document. DrawingFrame.Drawing returns the drawing itself, whose shapes are in a Drawing.ShapeCollection.
The collection. ServerTextControl.Drawings returns the DrawingCollection, which adds and removes drawings. DrawingCreated and DrawingDeleted report the changes.
File formats. Drawings are saved and loaded with the TX Text Control format and DOCX. Other formats save the drawing's image.
Editor. Users can activate a drawing and change its shapes with the mouse and the keyboard. The editor's server side received a dialog box for the layout of drawings, the value DrawingLayoutDialog of TextViewGenerator.DialogBoxKind.

Subtext Parts

The main text, text frames, headers and footers are the text parts of a document. A SubTextPart is a smaller piece of text that you define to work on it separately. See Subtext Parts.

Defining one. A subtext part is defined by a start position and a length or by a selection. ServerTextControl.SubTextParts returns the SubTextPartCollection of the main text, which adds and removes subtext parts; text frames, headers and footers have their own.
Name, ID and highlighting. A subtext part has a name and an ID. It can be highlighted always or only while it contains the input position, set with HighlightMode.
Nesting. Subtext parts can contain other subtext parts, but they can't overlap.
Saving. SubTextPart.Save saves the content to a byte array or a string, in every format TX Text Control supports.
Loading. LoadSettings.LoadSubTextParts converts bookmarks that span several characters in DOCX, DOC and RTF documents to subtext parts.

Formatted Text

Collections for all text parts. Document links, document targets, frames, charts, barcodes and drawings are available in every text part: the main text, headers, footers and text frames. IFormattedText.Drawings is one of the new properties.
Symbol characters. TextCharCollection.Add received overloads that add symbol and control characters in code.
Bullets. The bullet of a list is no longer limited to the Windows Symbol font. ListFormat.FontName sets its font, and ListFormat.BulletCharacter can be any Unicode character. See Paragraphs.

Document Properties

General document properties are saved with every supported format: SaveSettings.Author, CreationDate, CreatorApplication, DocumentKeywords, DocumentSubject and LastModificationDate. After a document is loaded, the properties of the same names of LoadSettings, such as LoadSettings.Author, return them. See Document Metadata.

Mail Merge

MailMerge creates documents from a template and data.

Merge blocks as subtext parts. Merge blocks, the sections of a template that are repeated for each record, are stored as subtext parts instead of document targets. Templates with blocks in the old format still load. See Merge Blocks.
A single object. MailMerge.MergeObject merges one object. Before, a single record of object data had to be wrapped in an enumerable type such as an array or a list. See Data Sources.
Empty blocks and images. RemoveEmptyBlocks removes the content of merge blocks without data (default true), and RemoveEmptyImages removes images without merge data (default false). See Conditional Content.

The Data of a Merge Block

The BlockMerging event occurs before a merge block is merged. Its BlockMergingEventArgs contain the name of the block, the column names of its table and, in BlockData, the data rows. The event arguments derive from CancelEventArgs, so a handler can cancel the merge of the block.

The rows and tables of this data are described by two interfaces, also new in version 23.0:

Interface	Members
IDataRowAdapter	`Item` returns the content of a column by its name, `Table` the table the row belongs to, and GetChildRows the rows of a child relation by its name, or `null` if the relation doesn't exist
IDataTableAdapter	`TableName`, `ColumnNames`, `Rows` (the rows as `IDataRowAdapter` objects) and `ChildTableNames`, the names of the table's child relations

Document Editor

In version 23.0, the Document Editor was the ASP.NET Web Forms control Web.TextControl, which worked with the TX TextControl Service, a Windows service on the server. Both are legacy technologies today; .NET Framework Applications describes their deployment.

Culture. Web.TextControl.Culture sets the culture of the editor, which affects formats such as dates, and UICulture the language of its user interface. Without a culture, the editor uses the language of the browser for its texts and units of measurement.
ASP.NET MVC. An HTML helper, HtmlHelperExtension.TXTextControl, renders the editor in an ASP.NET MVC view as a Web.MVC.TextControl, configured with TextControlSettings.
JavaScript API. The TXTextControl object received saveDocument, which saves the current document from the browser, loadDocument, and loadSelection and saveSelection, which insert formatted text at the selection and save the selection in a document format. The two selection methods are obsolete today.
Undo steps. TextViewGenerator.BeginUndoAction and EndUndoAction group all changes between them into one step that is undone and redone at once. UndoActionName returns its name.
Inserting frames with the mouse. New overloads of TextFrameCollection.Add, BarcodeCollection.Add and DrawingCollection.Add take a frame and a FrameInsertionMode value. The user then draws the frame in the document with the mouse, and the object is inserted when the mouse button is released.

Connect to a Service on Another Server

The Web Forms editor and the ASP.NET MVC editor of this version communicate with the TX TextControl Service through a WebSocket handler. Before version 23.0, the service had to run on the same machine as the IIS web server that hosts the editor. Two properties let the WebSocket handler connect to a service on another server, for example behind a load balancer:

Property	Sets
Web.TextControl.ServiceAddress	The IP address of the service, a `System.Net.IPAddress`. The default is 127.0.0.1, the local computer.
Web.TextControl.ServicePort	The port of the service, an `int`

Setting either property affects all instances of Web.TextControl. The properties aren't static only so that they appear in the Visual Studio designer. The ASP.NET MVC editor has the same two properties in TextControlSettings.ServiceAddress and TextControlSettings.ServicePort, which affect all instances of TextControlSettings.

ASP.NET Core applications of today's version don't use this service: they run the Document Editor backend, as Architecture explains.

Document Viewer

The Document Viewer of this version, DocumentServer.Web.DocumentViewer, received page animations, rounded page corners and ShowEditButton, which shows or hides the edit button.

Upgrade to Version 23.0

Merge block format. Templates created with version 23.0 store merge blocks as subtext parts. Templates with blocks in the old format, based on document targets, still load.
Update notes. TextViewGenerator.DialogBoxKind was extended with DrawingLayoutDialog, and BarcodeCollection.Add and TextFrameCollection.Add received the overloads for inserting a frame with the mouse.
Obsolete members. ListFormat.CharAfterNumber and CharBeforeNumber, which the list of version 23.0 names, are obsolete today; Deprecated APIs names their replacements.
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 23.0 lists for TX Text Control .NET Server. .NET names are relative to the TXTextControl namespace. Each name links to its current reference page, and "(obsolete)" marks the members that are obsolete today. The list also names classes that existed before, such as SaveSettings and ListFormat, as it appears in that documentation. The reference marks the Charts property of FootnoteSection and FootnoteText as introduced in version 23.0, but both classes came with footnotes in version 32.0, so they are left out here.

New Classes

.NET Members by Class

Class	Properties	Methods	Events
DataVisualization.DrawingCollection		Add, CopyTo, DeactivateItem, GetActivatedItem, GetItem, Remove
DataVisualization.DrawingEventArgs	DrawingFrame
DataVisualization.DrawingFrame	Drawing, ExportCompressionQuality, ExportFileName, ExportFilterIndex, ExportResolution, SaveMode	Activate, AddUndoUnit, Refresh
DocumentServer.DataSources.IDataRowAdapter	Item, Table	GetChildRows
DocumentServer.DataSources.IDataTableAdapter	ChildTableNames, ColumnNames, Rows, TableName
DocumentServer.MailMerge	RemoveEmptyBlocks, RemoveEmptyImages	MergeObject	BlockMerging
DocumentServer.MailMerge.BlockMergingEventArgs	BlockData, BlockName, ColumnNames
DocumentServer.MailMerge.ImageMergedEventArgs	Merged
DocumentServer.Web.DocumentViewer	PageAnimationDuration, PageAnimations, RoundedPageCorners, ShowEditButton
Drawing.Selection	CanBringForward, CanBringToFront, CanSendBackward, CanSendToBack, Shapes	BringForward, BringToFront, IsCommonValueSelected, SendBackward, SendToBack
Drawing.Shape	Angle, AutoSize, Bounds, CanFitToCanvas, Flip, Index, IsSelected, Location, Movable, ShapeFill, ShapeOutline, Sizable, Size, Type	FitToCanvas
Drawing.Shape.Fill	Color
Drawing.Shape.Outline	Color, Width
Drawing.ShapeCollection	Item	Add, Insert, Remove
Drawing.ShapeEventArgs	Shape
HeaderFooter	Barcodes, Charts, DocumentLinks, DocumentTargets, Drawings, Frames, SubTextParts
IFormattedText	Barcodes, DocumentLinks, DocumentTargets, Drawings, Frames, SubTextParts
ListFormat	BulletCharacter, BulletSize, CharAfterNumber (obsolete), CharBeforeNumber (obsolete), FirstNumber, FontName, FormatCharacter, HangingIndent, LeftIndent, Level, NumberFormat, RestartNumbering, Type
LoadSettings	Author, CreationDate, CreatorApplication, DocumentKeywords, DocumentSubject, LastModificationDate, LoadSubTextParts
MainText	Charts
SaveSettings	Author, BytesWritten, CreationDate, CreatorApplication, CssFileName, CssSaveMode, DocumentKeywords, DocumentSubject, DocumentTitle, ImageSavePath, LastModificationDate, PageMargins, PageSize, SavedFile, SavedStreamType
ServerTextControl	Drawings, SubTextParts	OnDrawingCreated, OnDrawingDeleted	DrawingCreated, DrawingDeleted
ServerVisualization.TextViewGenerator	DrawingMarkerLines, RedoActionName, UndoActionName	BeginUndoAction, EndUndoAction, OnDrawingDeselected, OnDrawingSelected, OnSubTextPartClicked, OnSubTextPartDoubleClicked, OnSubTextPartEntered, OnSubTextPartLeft, OnTextFieldClicked, OnTextFieldEntered, OnTextFieldLeft	DrawingDeselected, DrawingSelected, SubTextPartClicked, SubTextPartDoubleClicked, SubTextPartEntered, SubTextPartLeft, TextFieldClicked, TextFieldEntered, TextFieldLeft
SubTextPart	HighlightColor, HighlightMode, ID, Length, Name, NestedLevel, Number, OuterMostSubTextPart, OuterSubTextPart, Start, Text	Save, ScrollTo
SubTextPartCollection	Count, IsSynchronized, Item, SyncRoot	Add, CopyTo, GetEnumerator, GetItem, Remove
SubTextPartEventArgs	SubTextPart
TextCharCollection		Add, Remove
TextFrame	Barcodes, Charts, DocumentLinks, DocumentTargets, Drawings, Frames, SubTextParts
TextFrameCollection		GetActivatedItem
Web.MVC.ControlBase		Render
Web.MVC.ControlsFactory		TextControl
Web.MVC.HtmlHelperExtension		TXTextControl
Web.MVC.TextControl		LoadText, LoadXMLDatabase, SetFileDirectory
Web.MVC.TextControlSettings	APIRoute, BackColor, ContextMenusEnabled, ControlChars, Culture, DatabaseFileDirectory, Dock, DocumentFileDirectory, DocumentTargetMarkers, EditMode, FormattingPrinter, Height, ImageFileDirectory, SaveDocumentQuestionDialogEnabled, ServiceAddress, ServicePort, StaticFilesPath, StatusBarColor, TableGridLines, TextFieldsEditable, TextFrameMarkerLines, UICulture, Width
Web.TextControl	Culture, FormattingPrinter, ServiceAddress, ServicePort, UICulture	ResetContents

Document Editor JavaScript API

Object	Properties	Methods
DocumentLoadedEventArgs	fileName
FileDroppedEventArgs	cancel, fileName, fileSize, fileType
SaveDocumentResult	bytesWritten, data, streamType
TextDroppedEventArgs	cancel, text, textType
TextFieldEventArgs	textField
TextFieldInfo	bounds, containsInputPosition, deleteable, doubledInputPosition, editable, formattingBounds, id, isSpellCheckingEnabled, length, name, showActivated, start, text, type
TextPastedEventArgs	cancel, text, textType
TXTextControl	isLoadingDialogEnabled	loadDocument, loadSelection (obsolete), saveDocument, saveSelection (obsolete)

Next Steps

Version 24.0: the features of the next version.
Version 22.0: the features of the previous version.
Older Versions: all versions from 29.0 back to 10.1.
TX Text Control X13 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 Server 23.0