Skip to main content
All docs
V24.1

Printing in PDF Document API

  • 7 minutes to read

This document outlines the techniques used to print from the PDF Document API. This topic also describes how to identify issues that can occur when you print PDF files.

Important

You need a license for the DevExpress Office File API Subscription or DevExpress Universal Subscription to use these examples in production code.

Call the PdfDocumentProcessor.Print method to print PDF files. Use the PdfPrinterSettings class options to change printer settings.

The code example below prints a document with custom printer settings.

View Example: PDF Document API - Specify the PDF Printer Settings

using DevExpress.Pdf;

// Create a Pdf Document Processor instance
// and load a PDF file
PdfDocumentProcessor documentProcessor = new PdfDocumentProcessor();
documentProcessor.LoadDocument(@"..\..\Demo.pdf");

// Declare printer settings.
PdfPrinterSettings pdfPrinterSettings = new PdfPrinterSettings();

// Specify printer settings.
pdfPrinterSettings.PageOrientation = PdfPrintPageOrientation.Portrait;
pdfPrinterSettings.PageNumbers = new int[] { 1, 3, 4, 5 };

// Specify the custom scale number
pdfPrinterSettings.ScaleMode = PdfPrintScaleMode.CustomScale;
pdfPrinterSettings.Scale = 90;

// Specify .NET printer settings
PrinterSettings settings = pdfPrinterSettings.Settings;
settings.Duplex = Duplex.Vertical;
settings.Copies = 3;


// Print the document
documentProcessor.Print(pdfPrinterSettings);

Use the PdfPrinterSettings.DXSettings property to obtain printing settings that can be used to print PDF files in non-Windows environments (macOS and Unix-based systems that support printing through Common UNIX Printing System (CUPS)).

Note

Install the libcups2 package separately to enable printing.

The following code sample specifies cross-platform printing settings and prints the PDF file:

using DevExpress.Drawing.Printing;
using DevExpress.Pdf;

// Load a PDF file
PdfDocumentProcessor documentProcessor = new PdfDocumentProcessor();
documentProcessor.LoadDocument(@"..\..\Demo.pdf");

// Declare printer settings
PdfPrinterSettings pdfPrinterSettings = new PdfPrinterSettings();

// Specify printer settings
pdfPrinterSettings.PageNumbers = new int[] { 1, 3, 4, 5 };

// Specify CUPS printer settings
DXPrinterSettings dxPrinterSettings = pdfPrinterSettings.DXSettings;
dxPrinterSettings.Duplex = DXDuplexMode.DuplexLongEdge;
dxPrinterSettings.Copies = 3;

// Print the document
documentProcessor.Print(pdfPrinterSettings);

Specify Print Settings for a Specific Page

The PDF Document API ships with the following events that allow you to customize the print output:

PdfDocumentProcessor.QueryPageSettings
Occurs before the page is printed and allows you to specify print settings for a specific page.
PdfDocumentProcessor.PrintPage
Occurs when the page is printed.

The code snippet below handles the QueryPageSettings and PrintPage events to specify the landscape orientation for a second page and add an image on each printed page.

View Example: PDF Document API - Customize PDF Print Output

using DevExpress.Pdf;
using System.Drawing;

// Create a PDF Document Processor instance and load a PDF file
using (PdfDocumentProcessor documentProcessor = new PdfDocumentProcessor()) {
    documentProcessor.LoadDocument(@"..\..\Demo.pdf");

    // Declare PDF printer settings.
    PdfPrinterSettings settings = new PdfPrinterSettings();

    // Specify the page numbers to be printed.
    settings.PageNumbers = new int[] { 1, 2, 3, 4, 5, 6 };

    // Handle the PrintPage event to specify print output.
    documentProcessor.PrintPage += OnPrintPage;

    // Handle the QueryPageSettings event to customize settings for a page to be printed.
    documentProcessor.QueryPageSettings += OnQueryPageSettings;

    // Print the document using the specified printer settings.
    documentProcessor.Print(settings);

    // Unsubscribe from PrintPage and QueryPageSettings events. 
    documentProcessor.PrintPage -= OnPrintPage;
    documentProcessor.QueryPageSettings -= OnQueryPageSettings;
}

private static void OnQueryPageSettings(object sender, PdfQueryPageSettingsEventArgs e) {

    // Print the second page in landscape size.
    if (e.PageNumber == 2) {
        e.PageSettings.Landscape = true;
    }
    else e.PageSettings.Landscape = false;
}

// Specify what happens when the PrintPage event is raised.
private static void OnPrintPage(object sender, PdfPrintPageEventArgs e) {

    // Draw a picture on each printed page.
    using (Bitmap image = new Bitmap(@"..\..\DevExpress.png"))
        e.Graphics.DrawImage(image, new RectangleF(10, 30, image.Width / 2, image.Height / 2));
}

Troubleshooting: Optimize the Printing Process

The PDF Document API uses DirectX to render PDF files and the XPS API to print them. If your printer uses a PCL6 or PostScript driver, the DirectX engine converts the print job from XPS to the format used in the printer, which may reduce the printing performance. We recommend that you use the XPS printer driver to optimize the printing process.

Important

Make sure that the printer driver and OS on your machine are updated to the latest version.

Common Issues

Try one of the following solutions if issues occur with the print output or an exception is thrown:

  • Set the PdfDocumentProcessor.RenderingEngine property Gdi to disable the DirectX printing engine and use GDI+ instead. Please note that the GDI+ engine has limitations and some content may be lost (that is, stroke and clip text rendering, transparency, and blend modes).

  • Use the legacy printing engine (the PdfPrinterSettings.EnableLegacyPrinting option). In this case, PDF pages are printed as images. The legacy printing engine uses the GDI Print API to print files, and the rendering engine specified by the RenderingEngine property to render pages as images. Note that the printing performance may be reduced due to the size of printed images.

Font Embedding Issues

The PDF printing engine sends the font program with glyph codes to the printer to speed up the printing process and reduce the print job size. Set the PdfPrinterSettings.PrintTextAsOutlines property to true to convert text to character outlines. This step may help to resolve issues with incorrect font embedding for some printers. When you use this property, take into account the following:

  1. The PrintTextAsOutlines property works only with the DirectX printing engine (the RenderingEngine property is set to DirectX).

  2. The PrintTextAsOutlines property has no effect if the EnableLegacyPrinting property is set to true.

Get More Help

If these steps did not resolve issues with your document, please contact our DevExpress Support Team and provide the following information in your ticket so we can find a solution as fast as possible:

  • The document you want to print
  • The code snippet you utilize to print a file
  • The printer name and driver version
  • Operating system
  • DevExpress products version
  • Call stack (if available)