Export Labels to PDF

PrintJob.ExportToPdf() renders a ThermalLabel to an Adobe PDF document, in a file or in a Stream. The PDF always has one page per generated label (or per row of labels / per sheet, see below) and the page has the size of the label, not a paper size such as A4.

How Export to PDF works

The object in charge of the exportation is PrintJob. These are the overloads:

Method	Output
`ExportToPdf(string pathFile, double dpi)`	File. Exports `PrintJob.ThermalLabel`.
`ExportToPdf(string pathFile, double dpi, PdfMetadata metadata)`	File, with metadata.
`ExportToPdf(ThermalLabel thermalLabel, string pathFile, double dpi)`	File.
`ExportToPdf(ThermalLabel thermalLabel, string pathFile, double dpi, PdfMetadata metadata)`	File, with metadata.
`ExportToPdf(Stream stream, double dpi)`	Stream. Exports `PrintJob.ThermalLabel`.
`ExportToPdf(Stream stream, double dpi, PdfMetadata metadata)`	Stream, with metadata.
`ExportToPdf(ThermalLabel thermalLabel, Stream stream, double dpi)`	Stream.
`ExportToPdf(ThermalLabel thermalLabel, Stream stream, double dpi, PdfMetadata metadata)`	Stream, with metadata.

pathFile / stream can't be null (ArgumentNullException). The destination folder must already exist and an existing file is overwritten.
There is always a single PDF, whatever the number of labels.
dpi is the output resolution. Values lower than 96 are raised to 96. See Raster or vector.

Raster or vector

	Raster (default)	Vector
How to select it	Any overload without metadata, or `PdfMetadata.UseVectorDrawing = False`.	`PdfMetadata.UseVectorDrawing = True`.
What the PDF contains	One bitmap per page, rendered at the `dpi` you specify.	The items are drawn as PDF graphics.
Effect of `dpi`	Defines the pixel resolution (and the file size) of each page bitmap.	None on the result: the page is not rasterized.
Compression	`PdfMetadata.RasterEncodingQuality` (0-100, default 100). Values outside the range are clamped.	Not applicable.
Typical use	Exact look of what the printer would print, any item type.	Sharp text and shapes at any zoom and smaller files for text and barcode labels.

Important

To get a vector PDF you have to call an overload that receives a PdfMetadata object and set UseVectorDrawing = True. You can leave the other metadata properties empty.

Notes:

The page size does not depend on the dpi: a 4 x 3 inch label is always a 288 x 216 point page (1 inch = 72 points). Page sizes are rounded to whole points.
In raster mode the page bitmap always has a white background and uses anti-aliasing for all the items. Item images are always raster, also in vector mode.
PrintJob.PrintOrientation rotates the content (Landscape90, Portrait180, Landscape270) and ThermalLabel.Margin moves the items.

PDF Metadata

PdfMetadata has these properties:

Property	Type	Default when empty	Description
`Author`	`String`	`Neodynamic (www.neodynamic.com)`	Name of the person who created the document.
`Title`	`String`	empty	Document title.
`Subject`	`String`	empty	Document subject.
`Creator`	`String`	`ThermalLabel SDK <version>`	Product that created the original document.
`Producer`	`String`	`ThermalLabel SDK <version>`	Product that converts the document to PDF.
`UseVectorDrawing`	`Boolean`	`False`	`True` for vector output.
`RasterEncodingQuality`	`Integer`	`100`	Compression quality (0-100) of the page bitmaps in raster mode. Requires SkiaSharp 1.68.3 or later.

Note

Setting Author, Title, Subject, Creator and Producer is only available for licensed users. In the trial version those five values are ignored and the defaults above are used. UseVectorDrawing and RasterEncodingQuality do work in trial. The trial version also stamps a trial mark on every page.

One page per label

Scenario	Pages
Single label (no DataSource, no Counters, no Mask)	1. `PrintJob.Copies` is ignored.
Counters, Data Masking and/or Data Binding	One per generated label (see Counters, Data Masking and Data Binding).
Multi-column labels (`LabelsPerRow > 1`)	One page per row of labels; the page is as wide as the whole row.
Sheet of labels (`IsSheetOfLabels`)	One page per sheet, with the size of the sheet. This is the way to get a normal paper-size PDF.

PrintJob.Replicates (data-bound jobs) repeats every generated page that many times.
The PrintJob.LabelProgress event is raised for every label also when exporting to PDF, but LabelImage is always Nothing/null. Setting Cancel = True stops the remaining labels and a PrintJobCanceledException is thrown; the PDF already contains a complete, valid document with the pages generated until then.
Expressions are evaluated for every page, and PAGE_NUMBER and TOTAL_PAGES are available.
PrintJob.RenderCacheEnabled (default True) reuses the rendering of repeated items between pages (see Items Caching).

Labels to PDF samples

Example #1: The following code exports a single ThermalLabel object to PDF format at 300 dpi.

VB

'Define a ThermalLabel object and set unit to inch and label size
Dim tLabel As New ThermalLabel(UnitType.Inch, 4, 3)
tLabel.GapLength = 0.2

'Define a TextItem object
Dim txtItem As New TextItem(0.2, 0.2, 1, 0.5, "Thermal Label Test")

'Define a BarcodeItem object
Dim bcItem As New BarcodeItem(0.2, 1, 2, 1, BarcodeSymbology.Code128, "ABC 12345")
'Set bars height to .75inch
bcItem.BarHeight = 0.75
'Set bars width to 0.0104inch
bcItem.BarWidth = 0.0104

'Add items to ThermalLabel object...
tLabel.Items.Add(txtItem)
tLabel.Items.Add(bcItem)

'Create a PrintJob object
Using pj As New PrintJob()
    'Save output to PDF...
    pj.ExportToPdf(tLabel, "c:\temp\myLabel.pdf", 300)
End Using

CS

//Define a ThermalLabel object and set unit to inch and label size
ThermalLabel tLabel = new ThermalLabel(UnitType.Inch, 4, 3);
tLabel.GapLength = 0.2;

//Define a TextItem object
TextItem txtItem = new TextItem(0.2, 0.2, 1, 0.5, "Thermal Label Test");

//Define a BarcodeItem object
BarcodeItem bcItem = new BarcodeItem(0.2, 1, 2, 1, BarcodeSymbology.Code128, "ABC 12345");
//Set bars height to .75inch
bcItem.BarHeight = 0.75;
//Set bars width to 0.0104inch
bcItem.BarWidth = 0.0104;

//Add items to ThermalLabel object...
tLabel.Items.Add(txtItem);
tLabel.Items.Add(bcItem);

//Create a PrintJob object
using (PrintJob pj = new PrintJob())
{
    //Save output to PDF...
    pj.ExportToPdf(tLabel, @"c:\temp\myLabel.pdf", 300);
}

Example #2: The following code exports a ThermalLabel object that uses Counters to a 5-page PDF file at 300 dpi. The text goes from This is a Counter: 0 to This is a Counter: 4 and the barcode from ABC 12345 to ABC 12349.

VB

'Define a ThermalLabel object and set unit to inch and label size
Dim tLabel As New ThermalLabel(UnitType.Inch, 4, 3)
tLabel.GapLength = 0.2

'Define a TextItem object
Dim txtItem As New TextItem(0.2, 0.2, 2, 0.5, "This is a Counter: 0")
'Set counter
txtItem.CounterStep = 1

'Define a BarcodeItem object
Dim bcItem As New BarcodeItem(0.2, 1, 2, 1, BarcodeSymbology.Code128, "ABC 12345")
'Set counter
bcItem.CounterStep = 1
'Set bars height to .75inch
bcItem.BarHeight = 0.75
'Set bars width to 0.0104inch
bcItem.BarWidth = 0.0104

'Add items to ThermalLabel object...
tLabel.Items.Add(txtItem)
tLabel.Items.Add(bcItem)

'Create a PrintJob object
Using pj As New PrintJob()
    'Set number of labels to generate
    pj.Copies = 5
    'Save output to PDF...
    pj.ExportToPdf(tLabel, "c:\temp\myLabels.pdf", 300)
End Using

CS

//Define a ThermalLabel object and set unit to inch and label size
ThermalLabel tLabel = new ThermalLabel(UnitType.Inch, 4, 3);
tLabel.GapLength = 0.2;

//Define a TextItem object
TextItem txtItem = new TextItem(0.2, 0.2, 2, 0.5, "This is a Counter: 0");
//Set counter
txtItem.CounterStep = 1;

//Define a BarcodeItem object
BarcodeItem bcItem = new BarcodeItem(0.2, 1, 2, 1, BarcodeSymbology.Code128, "ABC 12345");
//Set counter
bcItem.CounterStep = 1;
//Set bars height to .75inch
bcItem.BarHeight = 0.75;
//Set bars width to 0.0104inch
bcItem.BarWidth = 0.0104;

//Add items to ThermalLabel object...
tLabel.Items.Add(txtItem);
tLabel.Items.Add(bcItem);

//Create a PrintJob object
using (PrintJob pj = new PrintJob())
{
    //Set number of labels to generate
    pj.Copies = 5;
    //Save output to PDF...
    pj.ExportToPdf(tLabel, @"c:\temp\myLabels.pdf", 300);
}

Example #3: Vector PDF with metadata, saved to a MemoryStream (for example, to send it in a web response). It uses the label of Example #2.

VB

Dim meta As New PdfMetadata()
meta.Author = "ACME Inc."
meta.Title = "Product labels"
meta.Subject = "Batch 42"
meta.UseVectorDrawing = True

Using pj As New PrintJob()
    pj.Copies = 5

    Using ms As New MemoryStream()
        pj.ExportToPdf(tLabel, ms, 300, meta)

        'the PDF bytes
        Dim pdfBytes As Byte() = ms.ToArray()
        File.WriteAllBytes("c:\temp\myLabels_vector.pdf", pdfBytes)
    End Using
End Using

CS

var meta = new PdfMetadata
{
    Author = "ACME Inc.",
    Title = "Product labels",
    Subject = "Batch 42",
    UseVectorDrawing = true
};

using (PrintJob pj = new PrintJob())
{
    pj.Copies = 5;

    using (var ms = new MemoryStream())
    {
        pj.ExportToPdf(tLabel, ms, 300, meta);

        // the PDF bytes
        byte[] pdfBytes = ms.ToArray();
        File.WriteAllBytes(@"c:\temp\myLabels_vector.pdf", pdfBytes);
    }
}

Example #4: Raster PDF with a lower compression quality (smaller file).

var meta = new PdfMetadata { RasterEncodingQuality = 70 };   // UseVectorDrawing is False by default
pj.ExportToPdf(tLabel, @"c:\temp\myLabels_small.pdf", 203, meta);

Common mistakes

Expecting a vector PDF by default. The default is raster; use PdfMetadata.UseVectorDrawing = True.
Using Copies to repeat a plain single label. Copies is ignored for a plain single label; the PDF has one page. Use Counters, a DataSource or Replicates.
Expecting an A4 or Letter page. The page has the label size.
Expecting a ZIP or several files. There is always one PDF.
Setting the metadata with the trial version. Author, Title, Subject, Creator and Producer are ignored until a license is applied.
Using a high dpi and expecting a bigger page. The page size is the label size; a higher dpi only makes the raster page bitmap sharper (and the file larger).
Exporting to a folder that doesn't exist. Create the folder first.