TX Text Control .NET for WPF

Using ServerTextControl in Desktop Applications

Topic

Not every document in a WPF application needs a window. ServerTextControl is TX Text Control's document engine without a user interface: it creates, loads, merges, converts and prints documents with the same members as the WPF TextControl, but no XAML, no rendering and no undo history. Keep the TextControl for the document the user edits, and give everything else to a ServerTextControl, on a background thread when the work takes time, so that the window never freezes.

The component is introduced in ServerTextControl in the Overview. The code-behind examples use the TextControl named textControl1 in MainWindow.xaml, and MainWindow.xaml.cs needs these using directives:

using System.Windows;
using TXTextControl;

Which Class Does What

The WPF TextControl shows the document and belongs to the UI thread of the window. ServerTextControl has no user interface, can be used on any thread and shares the document members of the editor, such as Load, Save, Selection and Tables, so code that builds a document works with either. What ServerTextControl Is in the Overview describes the class and its key members.

Create and Dispose Each Instance

A ServerTextControl isn't declared in XAML. Your code creates it, initializes it with Create before anything else, and disposes it when the work is done:

private void CreateDocument_Click(object sender, RoutedEventArgs e)
{
    using (ServerTextControl tx = new ServerTextControl())
    {
        // false if the instance couldn't be initialized
        if (!tx.Create())
        {
            MessageBox.Show("TX Text Control could not be initialized.");
            return;
        }

        tx.Text = "Thank you for your order.";
        tx.Save("confirmation.docx", StreamType.WordprocessingML);
    }
}

The using block disposes the instance and releases its resources, even when an exception occurs. Create an instance for each task rather than keeping one in a field of the window. Memory Usage and Resource Disposal explains why disposal matters.

Show a Document Built in Code

The WPF TextControl and ServerTextControl both load and save byte arrays. With BinaryStreamType InternalUnicodeFormat, the TX Text Control format, a document moves between them completely:

private void ShowLetter_Click(object sender, RoutedEventArgs e)
{
    byte[] document;

    using (ServerTextControl tx = new ServerTextControl())
    {
        tx.Create();

        // Font sizes in twips: 280 = 14 points
        tx.Selection.FontSize = 280;
        tx.Selection.Text = "Order Confirmation\r\n";
        tx.Selection.FontSize = 220;
        tx.Selection.Text = "Thank you for your order.";

        tx.Save(out document, BinaryStreamType.InternalUnicodeFormat);
    }

    textControl1.Load(document, BinaryStreamType.InternalUnicodeFormat);
}

WPF.TextControl.Load replaces the document in the editor, and WPF.TextControl.Append adds one at its end. In the other direction, textControl1.Save(out byte[] data, BinaryStreamType.InternalUnicodeFormat) gives the editor's document to a ServerTextControl. Selection.FontSize is measured in twips, 20 per point.

Keep the Window Responsive

Load, Save and the merge methods run synchronously and block the window while they run on the UI thread. Long work therefore goes to a thread of the thread pool with Task.Run, following three rules: the WPF TextControl stays on the UI thread and hands over its document as a byte array, every thread creates, uses and disposes its own ServerTextControl, and more threads don't make document processing proportionally faster. The Performance section explains each rule with code:

Printing prints in the background the same way.

Merge Templates Without the Editor

A MailMerge connected to a ServerTextControl through TextComponent creates documents from templates and data without changing the editor, and the finished document goes to the editor as a byte array, as shown above. Merge the Data in Getting Started shows the code. Templates, data sources and merge settings are the subject of Mail Merge and Reporting.

License ServerTextControl in a Class Library

ServerTextControl is part of TX Text Control .NET for WPF and needs no server license. If it runs in a class library instead of the application's executable, set the static property ServerTextControl.EntryAssembly to the assembly that holds the license before the first instance is created, as Application Licensing shows.

Next Steps