Using ServerTextControl in Desktop Applications

The TextControl on a form is the document the user works on. Everything else your application does with documents, such as merging letters, converting a folder to PDF or preparing a document before the user sees it, belongs in a ServerTextControl: the same document engine and programming interface, without a window. Used this way, the editor keeps its document and its undo history, and long work can run on a background thread while the form stays responsive.

ServerTextControl in the Overview introduces the component. The examples below are handlers in Form1.cs with the TextControl named textControl1, and Form1.cs needs these using directives:

using System.IO;
using TXTextControl;

When to Use ServerTextControl

A ServerTextControl is a component without a window that has the document members of the TextControl; What ServerTextControl Is describes the class and why it is faster and smaller for the same work.

Create and Dispose Each Instance

Every use of a ServerTextControl follows the same pattern:

private void createDocumentButton_Click(object sender, EventArgs e)
{
    using (ServerTextControl tx = new ServerTextControl())
    {
        // Initialize the new instance before using any other member
        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);
    }
}

• Create initializes the resources of the instance and must be called first. It returns false if the instance couldn't be initialized.
• The using block disposes the instance at its end, which releases its resources. Memory Usage and Resource Disposal describes what happens to instances that are never disposed.

Create one instance for each piece of work, and don't keep instances in fields of the form for later use.

Move Documents Between the Editor and ServerTextControl

Both classes load and save byte arrays, so a document moves between them without a file. BinaryStreamType InternalUnicodeFormat, the TX Text Control format, keeps everything the document contains. The following handler builds a letter in a ServerTextControl and shows it in the editor:

private void showLetterButton_Click(object sender, EventArgs e)
{
    byte[] document;

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

        tx.Selection.FontSize = 280; // 14 points, in twips
        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);
    }

    // Replace the document of the editor
    textControl1.Load(document, BinaryStreamType.InternalUnicodeFormat);
}

The other direction works the same way: textControl1.Save(out byte[] data, BinaryStreamType.InternalUnicodeFormat) hands the editor's document to a ServerTextControl, for example to convert or print it in the background. TextControl.Load replaces the document of the editor; TextControl.Append adds a document at its end instead. Selection.FontSize is set in twips, 20 per point.

Work in the Background

Load, Save and the merge methods have no asynchronous versions: they occupy the thread that calls them until they return, so called in a button handler, they block the form. A ServerTextControl can run on another thread: run long work with Task.Run, give each thread its own instance, and keep the TextControl, which belongs to the UI thread, out of it. To process the editor's document in the background, save it to a byte array on the UI thread, as shown above, and pass the array to the task.

UI Threading and Background Operations shows these rules in code: it exports the editor's document in the background, brings a result back to the editor, converts a folder of files with progress and cancel, and explains why more threads don't make document processing proportionally faster. Printing prints in the background the same way.

Merge Templates Without the Editor

A MailMerge works with the text component it is connected through TextComponent. Connected to a ServerTextControl, it creates documents while the editor shows something else; the result can then be saved, printed or loaded into the editor:

private void mergeButton_Click(object sender, EventArgs e)
{
    string jsonData = File.ReadAllText("customers.json");
    byte[] result;

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

        TXTextControl.DocumentServer.MailMerge mailMerge = new TXTextControl.DocumentServer.MailMerge();
        mailMerge.TextComponent = tx;
        mailMerge.LoadTemplate("letter-template.docx", TXTextControl.DocumentServer.FileFormat.WordprocessingML);
        mailMerge.MergeJsonData(jsonData);

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

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

Mail Merge and Reporting describes templates, data and merge settings.

License ServerTextControl in a Class Library

ServerTextControl is covered by the license of TX Text Control .NET for Windows Forms and needs no server license. When it is used in a class library rather than in the executable of the application, the static property ServerTextControl.EntryAssembly names the assembly that holds the license. Class Libraries and User Controls shows a class library that sets it and lists the versions that support it.

Next Steps

• Creating Documents: build documents in code.
• Saving and Converting Documents: the formats Save writes.
• UI Threading and Background Operations: threads in a Windows Forms application.
• Mail Merge and Reporting: create documents from templates and data.