PDF Creation and Conversion

Everything a Windows Forms application can show in a TextControl or build in a ServerTextControl becomes a PDF when it is saved with StreamType.AdobePDF: a letter typed by the user, a DOCX file loaded from disk or a merged invoice. TX Text Control writes the PDF with its own filter, so Adobe Acrobat isn't needed on the user's machine. The sections below show what a PDF takes over from the document, which options the save offers, how to make the PDF accessible and how to convert documents in another page format.

The first PDF, document properties, the Save As dialog box, PDF/A and passwords are covered step by step in Create a PDF in Getting Started. PDF is part of the Professional and Enterprise editions; PDF/A and PDF/UA are part of the Enterprise edition, as Editions and Feature Availability lists.

What a PDF Keeps From the Document

TX Text Control lays out the pages before it writes the PDF, so the PDF shows the same page breaks, headers, footers and table header rows as the document in the editor. Some elements of the document become interactive parts of the PDF:

AdobePDF saves complete documents only: a PDF can't be created from a selection or a single paragraph.

Choose What the PDF Contains

The options of a save are properties of SaveSettings, which you pass to Save. These are the ones that matter for PDF:

OmittedContent, which leaves comments or tracked changes out of other formats, can't be used with PDF and PDF/A.

Run JavaScript When the PDF Opens

DocumentLevelJavaScriptActions takes an array of scripts, which the PDF reader runs when it opens the document. The following handler in Form1.cs saves the document of textControl1 with a script that shows a notice:

private void pdfWithScriptButton_Click(object sender, EventArgs e)
{
    SaveSettings saveSettings = new SaveSettings()
    {
        DocumentTitle = "Quarterly Report",

        // Runs in the PDF reader when the document is opened
        DocumentLevelJavaScriptActions = new string[]
        {
            "app.alert('This report is confidential. Do not forward it.');"
        }
    };

    textControl1.Save("report-with-script.pdf", StreamType.AdobePDF, saveSettings);
}

The code works as follows:

• app.alert belongs to the JavaScript API of PDF readers such as Adobe Acrobat Reader, which Adobe documents.
• The scripts are embedded at document level. When the document is saved as PDF/A, they are left out, because PDF/A doesn't allow scripts.

The blog article Add JavaScript to PDFs with TX Text Control in C# .NET: Time-Based Alerts Made Easy shows expiration notices with such scripts.

Create an Accessible PDF (PDF/UA)

PDF/UA (ISO 14289) is the standard for PDF documents that people with disabilities can use with screen readers and other assistive technologies. Since version 34.0, every PDF that TX Text Control writes contains a logical structure in addition to its visible content: chapters, headings, paragraphs and sections, and marked text frames, tables, tables of contents and footnotes. Your document supplies what only its author knows:

The following handler gives the document a title, makes its first paragraph a heading and saves the PDF only when every image, table and form field has a description:

private void accessiblePdfButton_Click(object sender, EventArgs e)
{
    // The title that screen readers announce
    textControl1.DocumentSettings.DocumentTitle = "Quarterly Report";

    // The first paragraph becomes a level 1 heading
    textControl1.Select(0, 0);
    textControl1.Selection.ParagraphFormat.StructureLevel = 1;

    // Collect the elements that have no description yet
    List<string> missing = new List<string>();

    foreach (TXTextControl.Image image in textControl1.Images)
    {
        if (string.IsNullOrEmpty(image.DescriptiveText))
        {
            missing.Add("Image " + image.ID);
        }
    }

    foreach (Table table in textControl1.Tables)
    {
        if (string.IsNullOrEmpty(table.DescriptiveText))
        {
            missing.Add("Table " + table.ID);
        }
    }

    foreach (FormField formField in textControl1.FormFields)
    {
        if (string.IsNullOrEmpty(formField.DescriptiveText))
        {
            missing.Add("Form field " + formField.Name);
        }
    }

    if (missing.Count > 0)
    {
        MessageBox.Show("Add a description to:\n" + string.Join("\n", missing));
        return;
    }

    textControl1.Save("report-accessible.pdf", StreamType.AdobePDF);
}

The code works as follows:

• Image is written in full as TXTextControl.Image, because Form1.cs also sees System.Drawing.Image.
• StructureLevel 1 marks a first-level heading; 0 is body text. In a real document, set it in the paragraph styles of the headings.
• Images and Tables contain the images and tables of the text part with the input focus, here the main text, while FormFields contains the form fields of the whole document. Images and tables in headers, footers and text frames belong to other text parts, which Find the Fields of All Text Parts shows how to reach.

Saved with StreamType.AdobePDFA instead, the same document is a PDF/A-3a document and can conform to PDF/UA at the same time, as PDF/A describes.

Validate the Accessible PDF

The check above covers what the document knows before it's saved. Whether the PDF itself meets PDF/UA is checked by TXTextControl.PDF.Validation, a .NET library of Text Control that reads the PDF file or its bytes and returns a report of findings. It's published on nuget.org, not on the Text Control Private NuGet Feed, and it doesn't need a TextControl or ServerTextControl:

• .NET 10. Version 34.1.0 targets .NET 10, so your Windows Forms project must target .NET 10 (net10.0-windows) to reference it. .NET Framework projects can't use it.
• License. Individuals and organizations with a valid TX Text Control license may use it free of charge. Its license must be accepted when the package is installed.

Install it with Project > Manage NuGet Packages... and the source nuget.org, or from the folder of the project:

dotnet add package TXTextControl.PDF.Validation --version 34.1.0

The following handler saves the document of textControl1 as PDF into memory, validates it and writes the file only when no blocking error was found. Form1.cs needs using TXTextControl.PDF.Validation; and using TXTextControl.PDF.Validation.Model;:

private void validatePdfButton_Click(object sender, EventArgs e)
{
    // Save the PDF into memory, so it can be checked before it's written
    textControl1.Save(out byte[] pdf, BinaryStreamType.AdobePDF);

    Report report = PdfUaValidator.Validate(pdf);

    if (report.Status == ValidationStatus.Failed || report.Status == ValidationStatus.Blocked)
    {
        // The findings that didn't pass, with their rule and message
        IEnumerable<string> problems = report.Findings
            .Where(finding => !finding.Passed)
            .Select(finding => $"{finding.Severity} {finding.RuleId}: {finding.Message}");

        MessageBox.Show(this, "The PDF isn't accessible yet:\n" + string.Join("\n", problems), "PDF/UA");
        return;
    }

    File.WriteAllBytes("report-accessible.pdf", pdf);
    MessageBox.Show(this, "Saved with the result " + report.Status + ".", "PDF/UA");
}

The code works as follows:

• PdfUaValidator.Validate takes the path of a PDF file or the PDF as a byte array and returns a Report of the TXTextControl.PDF.Validation.Model namespace.
• Status is Passed, CompletedWithWarnings, Failed or Blocked. Only failed findings of the severity Error make a report Failed; Blocked means the validation couldn't run completely, for example because the PDF is encrypted, so validate before you protect a PDF with a password.
• Each Finding has a RuleId such as UA-TITLE (the document title) or UA-FIG-ALT (the descriptions of images), a Severity of Info, Warning or Error, Passed and a Message.

PdfUaValidator.ToJson(report, true) turns the report into indented JSON, which you can store with the document or compare between two versions of a template. The validator confirms that a description exists, not that it describes the image well, so a review by people remains necessary. The package doesn't check PDF/A conformance: its PDFA-CONFORMANCE finding only reports whether the file declares it. The blog article Validating PDF/UA Documents in .NET C#: A Practical Guide goes further, and the same package checks digital signatures, as Verify the Signatures in Code shows.

Convert a Document to Another Page Format

A document keeps its page format when it is saved as PDF. To create a PDF with other pages without changing what the user sees, save a copy of the editor's document, load it into a ServerTextControl and change the sections there:

private void letterPdfButton_Click(object sender, EventArgs e)
{
    // A copy of the document in the editor
    byte[] document;
    textControl1.Save(out document, BinaryStreamType.InternalUnicodeFormat);

    using (ServerTextControl tx = new ServerTextControl())
    {
        // Initialize the new instance before using it
        tx.Create();
        tx.Load(document, BinaryStreamType.InternalUnicodeFormat);

        // Page sizes and margins in 1/100 inch
        tx.PageUnit = MeasuringUnit.CentiInch;

        // US letter pages with margins of 0.75 inch in every section
        foreach (Section section in tx.Sections)
        {
            section.Format.PageSize = new PageSize();
            section.Format.PageMargins = new PageMargins(75, 75, 75, 75);
        }

        tx.Save("report-letter.pdf", StreamType.AdobePDF);
    }
}

The code works as follows:

• BinaryStreamType.InternalUnicodeFormat is the format of TX Text Control itself, so the copy keeps everything the document contains.
• ServerTextControl is the document engine without a user interface. Create must be called before any other member.
• PageUnit sets the unit of page sizes and margins. The reference names its type PageUnit; in code, the enumeration is MeasuringUnit.
• Every Section has its own format. The PageSize constructor without parameters creates a US letter page, 8.5 x 11 inches, and SectionFormat.PageMargins takes the margins.

Text and images flow onto the new pages, so the number of pages can change. The same ServerTextControl converts files that aren't open in the editor: Convert a Folder of Documents turns every DOCX, DOC, RTF and HTML file of a folder into a PDF. The other direction, from PDF to an editable format, is described in PDF Import and Its Limitations.

Add a Watermark to Every Page

A "DRAFT" or "CONFIDENTIAL" behind the text of every page marks the status of a PDF. A watermark is an image in the header of each section, fixed on the page and placed below the text; Add a Watermark to Every Page in Images, Text Frames, and Shapes explains the method AddWatermark and how it centers the image. To mark only the PDF and leave the document in the editor as it is, run the method on a copy:

private void draftPdfButton_Click(object sender, EventArgs e)
{
    // A copy of the document in the editor
    byte[] document;
    textControl1.Save(out document, BinaryStreamType.InternalUnicodeFormat);

    using (ServerTextControl tx = new ServerTextControl())
    {
        // Initialize the new instance before using it
        tx.Create();
        tx.Load(document, BinaryStreamType.InternalUnicodeFormat);

        // Page sizes, margins and image locations in twips
        tx.PageUnit = MeasuringUnit.Twips;

        AddWatermark(tx.Sections, "draft.svg");

        tx.Save("report-draft.pdf", StreamType.AdobePDF);
    }
}

As in Convert a Document to Another Page Format, a ServerTextControl holds the copy, and PageUnit gives its page sizes and margins the unit of the image. ServerTextControl.Sections is the same kind of collection as the sections of the TextControl, so AddWatermark takes it unchanged. In Adobe Acrobat, the watermark appears in the middle of every page:

The blog article Adding Watermarks to PDF Documents in .NET C# adds the watermark the same way before it saves the PDF.

Next Steps

• PDF/A: save documents for long-term archiving.
• Font Embedding and Substitution: control which fonts end up in the PDF.
• PDF Forms: create PDF documents that users fill in.
• Passwords and Access Permissions: protect the PDF.