Document Conversion

Loading a document into the TextControl or saving it can fail with a FilterException, or it succeeds and the result isn't what you expected. Both kinds of problem follow, starting with the exception and its reason. Text that looks different because a font is missing is covered on Fonts and Document Layout, and a feature that your edition doesn't include on Licensing.

Read the Reason of a FilterException

When a text filter can't convert a document to or from a format, TextControl.Load and Save throw a FilterException. Its message contains an error number in parentheses, and its Reason property names the cause as a value of FilterException.FilterError. The following code in Form1.cs loads a document into textControl1 and shows both when loading fails:

using System.Windows.Forms;
using TXTextControl;

private void openButton_Click(object sender, EventArgs e)
{
    try
    {
        textControl1.Load("contract.docx", StreamType.WordprocessingML);
    }
    catch (FilterException exception)
    {
        // The message contains the error number, Reason the cause
        MessageBox.Show($"{exception.Reason}: {exception.Message}");
    }
}

The reasons have these meanings:

The error number gives more detail than the reason. Text Control's Error Navigator looks it up; the blog article Text Control Error Navigator Launched explains how to search it.

The File Type Is Not Supported Through the Filter

Loading fails with a message such as:

Text filter error: The file type is not supported through the filter.
(1-1D01)

The reason is WrongFileType: the data doesn't have the format that the format value of Load names, for example a string of plain text loaded as RTF.

1. Pass the value that matches the data: a value of StreamType for a file, of BinaryStreamType for a byte array and of StringStreamType for a string.
2. BinaryStreamType has no value for HTML or RTF. Load these formats from a string or a file.
3. StreamType.AdobePDFA and StreamType.CascadingStylesheet are for saving only. To load a PDF document, use StreamType.AdobePDF.

Load and Save Documents shows which value belongs to which format.

A Password-Protected PDF Doesn't Load

Loading a PDF document throws a FilterException whose Reason is InvalidPassword.

The PDF document is protected with a user password, which has to be passed when it's loaded. The TX Words Ribbon sample handles this case: when loading fails with this reason, it asks for the password and loads the document again.

1. Ask the user for the password.
2. Load the document again with the password in LoadSettings.UserPassword.
3. Apply the permissions of the document to the editor, as Respect the Permissions of a PDF shows. With the correct MasterPassword, no restrictions apply.

If the Reason is Encrypted, the document uses an encryption that TX Text Control can't import, such as 256-bit AES or certificates. Encrypted PDF Documents lists the algorithms it imports.

A Loaded PDF Contains No Text

A PDF document loads without an error, but the editor shows no text, or the text can't be selected.

A PDF document describes what each character looks like and where it is, but not always which character it is. Most PDF documents contain a mapping to the characters, and without it no text can be extracted. A scanned page is an image and contains no text at all.

1. Check the text after loading, for example with ServerTextControl.Text when you convert without the editor, and skip or report documents without text.
2. Run scanned documents through OCR software before you import them.
3. To read text together with its position on the page, use PDF.Contents.Lines, as Text Extraction describes.

The TXTextControl Object Must Have Been Completely Loaded

A member of a ServerTextControl throws this message:

The TXTextControl object must have been completely loaded to use this method.

The instance isn't initialized: ServerTextControl.Create wasn't called before the member, or it returned false. Create Returns False gives the causes and the fix.

Images Are Missing After Loading

Where an image should be, the document shows a rectangle of the image's size with the file name of the image.

An image inserted from a file can be saved as a reference to the file, with its absolute path. When the document is loaded on a machine where this path doesn't exist, the image can't be found. LoadSettings.LoadImages set to false shows the same rectangles.

1. Set LoadSettings.ImageSearchPath to the folder that holds the images. It replaces the absolute paths in the document. Relative paths are resolved with DocumentBasePath.
2. Make sure LoadImages isn't false.
3. To find the paths a template uses, read Image.FileName of its images.

Word Fields Are Missing After Loading

A DOCX, DOC or RTF document from Microsoft Word loads, but its merge fields or other fields aren't in TextControl.ApplicationFields, or its merge blocks aren't recognized.

By default, fields of other applications are not imported as application fields: LoadSettings.ApplicationFieldFormat is None. Bookmarks that span several characters, which mark merge blocks in Word documents, become document targets unless you load them as subtext parts.

1. Set ApplicationFieldFormat to MSWord to import the fields of Word as application fields, or to MSWordTXFormFields to import its form fields as form fields of TX Text Control.
2. Set LoadSettings.LoadSubTextParts to true to load bookmarks that span several characters as subtext parts. It applies to DOCX, DOC and RTF.
3. Pass the LoadSettings to Load.

Mail Merge covers fields and blocks that don't merge.

The Converted Document Looks Different

A document converted to another format, such as DOCX to PDF, has other line breaks, page breaks or fonts than the original.

TX Text Control lays out a document with the fonts available on the machine and the text dimensions of the formatting printer. When a font of the document is missing, another one replaces it, and the layout changes.

1. Find out which fonts are replaced, as Fonts and Document Layout describes.
2. Check that the format you save to supports what the document contains. Supported File Formats lists the formats and their features.
3. Check that your edition includes the format: the Express edition has no DOCX, DOC or PDF, and the Professional edition no PDF/A. See Editions and Feature Availability.

Saving as PDF Fails in an Earlier Service Pack

Saving a document as PDF or PDF/A fails with a FilterException whose message contains an error number such as 01-1D09, or the saved PDF lacks content, while other documents save without problems.

The PDF export of version 34.0 writes tagged PDF, and the service packs of 34.0 fixed several documents that it couldn't save. The Known Issues page of version 34.0 lists, among others, these fixes:

1. Read the service pack your application runs with from VersionInfo.ServicePack, as Service Packs shows.
2. Install the latest service pack, update TXTextControl.TextControl.WinForms.SDK to 34.0.5 and rebuild the application.
3. If the error remains, look up the error number as described in Read the Reason of a FilterException, and check the open issues on the Known Issues page. An error 1-1D09 when loading some PDF documents is listed there as open.

Related Pages

• Load and Save Documents: load and save documents in the editor.
• Exceptions and Error Handling: the exceptions of TX Text Control in detail.
• Supported File Formats: what each format supports.