What's New in TX Text Control .NET Server 30.0

Version 30.0 gave TX Text Control .NET Server comments that MS Word reads, SVG images and a mail merge that fills form fields. Its additions over version 29.0 reach from the character attributes of the .NET API to the new sidebars of the Document Editor and the signing methods of the Document Viewer.

Version 30.0 was released in November 2021, together with TX Text Control .NET for Windows Forms, TX Text Control .NET for WPF, TX Text Control ActiveX and TX Spell .NET 9.0. Version 29.0 was sold as TX Text Control X19; from version 30.0 on, the product is named after its version number. The current version is Version 34.0, and the changes of the 30.0 service packs are listed on Service Packs.

Version 30.0 at a Glance

Comments

A comment is a note that is attached to a piece of text, and version 30.0 adds comments and replies to documents and to the API. Each comment is a CommentedText object in the CommentCollection of a text part, such as ServerTextControl.Comments for the main text. Comments shows how to add, list, answer and remove them in code, and Comments in the Document Editor how users work with them.

• Edit, reply and highlight. EditComment and ReplyToComment of CommentedText open a comment input control to change the comment or to answer it, and Select selects the commented text. HighlightMode and HighlightColor decide whether and in which color the commented text is highlighted. DefaultHighlightColor is the color for comments whose author is unknown; the comments of the current user are highlighted in red.
• Active and inactive comments. An inactive comment isn't highlighted, and CommentCollection.GetItem doesn't return it. CommentedText.Active switches the state.
• Events. CommentCreated and CommentDeleted of ServerTextControl pass a CommentEventArgs object. ServerVisualization.TextViewGenerator, a ServerTextControl that shows its text as a generated image, also raises CommentChanged, CommentedTextEntered, CommentedTextLeft and CommentStateChanged. Its properties CommentHighlightMode and EditableRegionHighlightMode set whether all commented texts and all editable regions of the document are highlighted; the second applies to editable regions whose own highlight mode is Auto.

Character Attributes and Styles

Version 30.0 adds character attributes for typographic details such as diagonal fractions and ordinal indicators.

• Automatic sub- and superscript. Selection.AutoBaseline scales the font and moves the text above or below the baseline, with the values the font defines. It can be combined with a baseline position of your own, set with Selection.Baseline. If the font defines none, the text is scaled to 50% and moved 40% above or 15% below the baseline. Besides Superscript and Subscript, the value SuperscriptUpperEdge doesn't extend above capital letters, and SubscriptBaseline scales the text without moving it below the baseline, for example for the numerator and denominator of a diagonal fraction.
• Capitals. Selection.Capitals shows lowercase letters as capitals of the same size (Capitals) or as smaller capitals: PetiteCapitals have the height of a lowercase x, and SmallCapitals are 10% higher.
• Spacing and scaling. Selection.CharacterSpacing adds a fixed value in twips to each character; a negative value reduces the spacing. Selection.CharacterScaling sets the character width in percent of the average character width.
• Change the capitalization. Selection.ChangeCapitalization converts the selected text with a CapitalizationSettings value: to upper or lower case, each word or sentence capitalized, or the case toggled.
• Formatting styles. All new attributes are also properties of FormattingStyle, and all text filters load and save them. FormattingStyle.Culture sets the language of a character or paragraph style, which is used for spell checking and hyphenation; null means the neutral culture.

SVG Images

Documents can contain images in the Scalable Vector Graphics format (SVG), with all the formatting options of other images. When a document is saved as PDF, SVG images are converted to PDF vector graphics.

The SVG support is based on W3C SVG 1.1 (Second Edition). References to external images or style sheets, interactivity and animation, advanced text transformations, patterns, masking, compositing and filter effects aren't supported. Supported File Formats lists all image formats.

Text Frames

The border of a text frame can have a color, set with TextFrame.BorderColor, and can be a single or double line, set with TextFrame.BorderStyle and the values of FrameStyle. The Document Editor's JavaScript API has the same settings for the TextFrame object: setBorderColor and setBorderStyle change them, and getBorderColor and getBorderStyle read them.

Mail Merge

MailMerge creates documents from a template and data. In version 30.0, it can merge data into form fields, the fields that users fill out in a document form.

• Form field merge type. MailMerge.FormFieldMergeType decides what happens to form fields. With None, the default, they aren't merged. With Preselect, their content is preselected with the data, and the document remains a form. With Replace, they are replaced with the data, and empty fields are removed according to RemoveEmptyFields.
• FormFieldMerged event. FormFieldMerged occurs when a form field has been merged. Its FormFieldMergedEventArgs contain the form field, the data row, whether the field has been merged and, if the field is in a merge block or a table, the block and the table cell. A handler can change the text of the field.
• Inserted merge blocks. MergeBlockSettings.AddResult tells whether DataSourceManager.InsertMergeBlock has inserted the new merge block.

Merge fields and form fields can be merged in the same run. The blog article Merging Form Fields using the MailMerge Class shows both merge types.

Document Editor

The Document Editor is the WYSIWYG word processor that you embed in your web application. Its JavaScript API received the comment interface of the .NET API and the new character attributes, and its user interface changed.

• Comments. TXTextControl.comments returns the CommentCollection of the main text, which inherits FormattedText.comments. Its methods add comments and replies and find the next or previous comment. The editor raises the events commentCreated, commentDeleted, commentChanged, commentedTextEntered, commentedTextLeft and commentStateChanged. The event arguments describe the comment with a CommentedTextInfo object, which holds the comment, the author, the creation time, the position and length of the commented text and its highlight settings. setCommentHighlightMode and setEditableRegionHighlightMode of TXTextControl set the highlight mode of all comments and all editable regions. On the Proofing ribbon tab, a new group adds, removes and navigates comments, and a comment can be attached to a tracked change. See Comments.
• Character attributes. Selection and FormattingStyle have get and set methods for automatic sub- and superscript, capitals, character spacing and character scaling. FormattingStyle.setCulture takes a culture string such as "de-DE".
• Sidebars. The editor has two new sidebars: the Field Navigator and an overview of the comments. A toggle button in the top right corner of the ribbon opens them; TXTextControl.sideBarToggleButton configures which sidebars it offers.
• Ruler bars and status bar. TXTextControl.rulerBar, verticalRulerBar and statusBar return objects that change the colors, the scale unit and the behavior of the ruler bars and the texts and areas of the status bar. Both kinds of bar have a displayColors property, which returns a RulerBarViewGeneratorColors or StatusBarViewGeneratorColors object with get, set and reset methods for colors such as the background and text color, and resetDisplayColors restores all colors. RulerBarViewGenerator.setBorderStyle sets the border style of a ruler bar. The status bar has a method for the label of each area, such as setLineText, setColumnText, setPageText and setSectionText, for example to translate the labels, and methods such as setShowLine, setShowSectionCounter and setShowLanguage that show or hide single areas. The border style methods of the status bar and some of its color methods are obsolete: since version 33.0, the status bar has no border style, frame or gradients; see Deprecated APIs.
• Form field events. The editor raises formFieldCheckChanged, formFieldDateChanged, formFieldSelectionChanged and formFieldTextChanged when a user changes a form field. Their arguments are CheckFormFieldEventArgs, DateFormFieldEventArgs, SelectionFormFieldEventArgs and TextFormFieldEventArgs. Their formField property describes the changed field with an info object, for example CheckFormFieldInfo with the checked state, or DateFormFieldInfo with the date, the date format and the width of the empty field in twips. FormattedText.formFields returns the form fields of a text part.
• Page number fields. HeaderFooter.pageNumberFields returns a PageNumberFieldCollection that adds and removes page number fields in a header or footer. Each PageNumberField sets its number format, its start number and whether it shows the total number of pages.
• Input position and undo. setInputPositionByTextPosition, setInputPositionByPage and setInputPositionByLocation set the input position. All changes between beginUndoAction and endUndoAction are undone and redone in one step.
• Ribbon design. The ribbon has a new design with hover effects and a cleaner minimized mode.

Document Viewer

The Document Viewer shows documents in the browser and lets users sign them. The TXDocumentViewer.signatures object of its JavaScript API received methods to control the signing process: startSigningProcess opens the signature dialog, submit submits the signed document, and setSubmitCallback sets the function that is called when the document is submitted. setCustomSigning enables a custom signing process, and storeSignature and retrieveSignature keep a signature in the browser's local storage. cancelSigningProcess cancels the signing and closes the dialog, clearSignaturePad clears the pad the user signs on, getCustomSigning returns whether the custom signing process is enabled, and setBeforeSubmitCallback sets a further function that is called on submitting the document.

New Classes and Members

The What's New documentation of version 30.0 lists these classes, properties, methods and events as new in TX Text Control .NET Server. They are grouped by class, and each name leads to its reference page. The list of the documentation also names members of Selection that existed before version 30.0, such as Bold, FontName and Text, and they are left out here. Some of the status bar members below are obsolete since version 33.0; Deprecated APIs names them and their replacements.

.NET API

• CommentCollection (new class): Add, CopyTo, Count, GetEnumerator, GetItem, IsSynchronized, Item, Remove, SyncRoot
• CommentedText (new class): Active, Comment, CreationTime, DefaultHighlightColor, EditComment, HighlightColor, HighlightMode, ID, Length, Number, RepliedComment, Replies, ReplyToComment, Save, ScrollTo, Select, Start, Text, UserName
• CommentEventArgs (new class): CommentedText
• DocumentServer.DataSources.MergeBlockSettings: AddResult
• DocumentServer.MailMerge: FormFieldMerged, FormFieldMergeType
• DocumentServer.MailMerge.FormFieldMergedEventArgs (new class): DataRow, FormField, MergeBlockName, Merged, NestingDepth, TableCell
• FormattingStyle: AutoBaseline, Capitals, CharacterScaling, CharacterSpacing, Culture
• HeaderFooter: Comments
• IFormattedText: Comments
• Selection: AutoBaseline, Capitals, ChangeCapitalization, CharacterScaling, CharacterSpacing
• ServerTextControl: CommentCreated, CommentDeleted, Comments, OnCommentCreated, OnCommentDeleted
• ServerVisualization.TextViewGenerator: CommentChanged, CommentedTextEntered, CommentedTextLeft, CommentHighlightMode, CommentStateChanged, EditableRegionHighlightMode, OnCommentChanged, OnCommentedTextEntered, OnCommentedTextLeft, OnCommentStateChanged
• TextFrame: BorderColor, BorderStyle, Comments

Document Editor JavaScript API

• CheckFormFieldEventArgs: formField
• CheckFormFieldInfo: checked
• CommentCallbackData: addResult, comment
• CommentCollection: add, addAtPosition, addReply, getItem, getNextItem, getPreviousItem, remove
• CommentedText: getActive, getComment, getCreationTime, getHighlightColor, getHighlightMode, getID, getLength, getNumber, getRepliedComment, getReplies, getStart, getText, getUserName, scrollTo, setActive, setComment, setHighlightColor, setHighlightMode, setID
• CommentedTextInfo: active, comment, creationTime, highlightColor, highlightMode, id, length, number, start, userName
• CommentEventArgs: commentedText
• DateFormFieldEventArgs: formField
• DateFormFieldInfo: date, dateFormat, emptyWidth
• FormattedText: comments, formFields
• FormattingStyle: getAutoBaseline, getCapitals, getCharacterScaling, getCharacterSpacing, getCulture, setAutoBaseline, setCapitals, setCharacterScaling, setCharacterSpacing, setCulture
• HeaderFooter: pageNumberFields
• PageNumberField: getNumberFormat, getShowNumberOfPages, getStartNumber, setNumberFormat, setShowNumberOfPages, setStartNumber
• PageNumberFieldCollection: add, getItem, remove
• RulerBarViewGenerator: displayColors, getBorderStyle, getEnablePageMargins, getFormulaMode, getReadOnly, getScaleUnit, resetDisplayColors, setBorderStyle, setEnablePageMargins, setFormulaMode, setReadOnly, setScaleUnit
• RulerBarViewGeneratorColors: getBackColor, getForeColor, getGradientBackColor, getRulerColor, getSeparatorColorDark, getSeparatorColorLight, resetBackColor, resetForeColor, resetGradientBackColor, resetRulerColor, resetSeparatorColorDark, resetSeparatorColorLight, setBackColor, setForeColor, setGradientBackColor, setRulerColor, setSeparatorColorDark, setSeparatorColorLight
• Selection: getAutoBaseline, getCapitals, getCharacterScaling, getCharacterSpacing, setAutoBaseline, setCapitals, setCharacterScaling, setCharacterSpacing
• SelectionFormFieldEventArgs: formField
• SideBarToggleButton: getAllowedSideBars, getCurrentSideBar, setAllowedSideBars, setCurrentSideBar
• StatusBarViewGenerator: displayColors, getBorderStyle, getColumnText, getLineText, getPageCounterText, getPageText, getSectionCounterText, getSectionText, getShowColumn, getShowLanguage, getShowLine, getShowPage, getShowPageCounter, getShowSection, getShowSectionCounter, getShowZoom, getShowZoomTrackBar, resetDisplayColors, setBorderStyle, setColumnText, setLineText, setPageCounterText, setPageText, setSectionCounterText, setSectionText, setShowColumn, setShowLanguage, setShowLine, setShowPage, setShowPageCounter, setShowSection, setShowSectionCounter, setShowZoom, setShowZoomTrackBar
• StatusBarViewGeneratorColors: getBackColor, getBackColorBottom, getBackColorMiddle, getBackColorTop, getForeColor, getFrameColor, getGradientBackColor, getSeparatorColorDark, getSeparatorColorLight, reset, resetBackColor, resetBackColorBottom, resetBackColorMiddle, resetBackColorTop, resetForeColor, resetFrameColor, resetGradientBackColor, resetSeparatorColor, resetSeparatorColorDark, resetSeparatorColorLight, setBackColor, setBackColorBottom, setBackColorMiddle, setBackColorTop, setForeColor, setFrameColor, setGradientBackColor, setSeparatorColorDark, setSeparatorColorLight
• TextFieldCollection: addWithText
• TextFormFieldEventArgs: formField
• TextFrame: getBorderColor, getBorderStyle, setBorderColor, setBorderStyle
• TXTextControl: beginUndoAction, endUndoAction, getCommentHighlightMode, getEditableRegionHighlightMode, rulerBar, setCommentHighlightMode, setEditableRegionHighlightMode, setInputPositionByLocation, setInputPositionByPage, setInputPositionByTextPosition, sideBarToggleButton, statusBar, verticalRulerBar

Document Viewer JavaScript API

• Signatures: cancelSigningProcess, clearSignaturePad, getCustomSigning, retrieveSignature, setBeforeSubmitCallback, setCustomSigning, setSubmitCallback, startSigningProcess, storeSignature, submit

Upgrade to Version 30.0

• Update notes. The update notes of version 30.0 list one entry: LoadSettings.PDFImportSettings was extended with the settings LoadEmbeddedFiles, LoadMetadata and GenerateXMLAsEmbeddedFile. The update notes of version 29.0 contain the same entry, and version 29.0 introduced the embedded files and the metadata of PDF documents, so the entry describes a change of 29.0 that the 30.0 notes repeat; see Older Versions. Of the three names, only LoadEmbeddedFiles is a value of the current PDFImportSettings enumeration; it provides the files embedded in the document. The metadata, the form fields and the text coordinates come from the value LoadEmbeddedData.
• Changes to plan for. Version 30.0 supports .NET Framework 4.8, .NET 5 and .NET 6, and its setup no longer registers the assemblies in the global assembly cache (GAC). As a result, every entry in licenses.licx needs the full version number of the assembly. Breaking Changes describes the details, and Migrating from Previous Versions the license files.

Next Steps

• Version 31.0: the features of the next version.
• Breaking Changes: the changes that can require work when you upgrade.
• Comments: work with comments in the Document Editor.