Table of Contents

PDF export

The PDF export produces a fully formatted .pdf document that mirrors the rendered report. It is the recommended format for printable document exchange and archival workflows. PDF export is included in the core combit.ListLabel32.CrossPlatform package and selected with LlExportTarget.Pdf.

The resulting file preserves layout, fonts, colors, and vector graphics from the report project. Multi-page reports are exported as multi-page PDFs with the page sizes defined in the project.


Two PDF engines

Three export targets produce a .pdf document. They differ in the engine that writes it, not in the report that is rendered.

Target Engine Use it for
Pdf Enhanced where available, standard otherwise The default. Everything the deployment can offer. Where only the standard engine is available, a PDF/A level other than PDF/A-2b, an e-invoice or encryption fails the export instead of being dropped.
PdfStandard Standard SkiaSharp backend, chosen explicitly Pinning the engine, so the output does not depend on what is deployed on the machine.
PdfEnhanced Enhanced native PDF engine, chosen explicitly PDF/A levels other than PDF/A-2b, encryption and permissions, embedded ZUGFeRD/Factur-X e-invoices, interactive form fields including signature fields.

PdfEnhanced needs its own native library. On Windows it ships with combit.ListLabel32.CrossPlatform, so the enhanced engine is always available on x64 and x86. On Linux and macOS, reference the package for the platform, which also brings the native SkiaSharp assets:

Platform Package
Linux combit.ListLabel32.CrossPlatform.NativeAssets.Linux
macOS combit.ListLabel32.CrossPlatform.NativeAssets.macOS

The library is found next to the application, in the runtimes/<rid>/native folder a NuGet package places it in, or on the system's library search path.

Runtime identifier File
win-x64 combit.ListLabel32.ConversionToolsExt.x64.dll
win-x86 combit.ListLabel32.ConversionToolsExt.x86.dll
linux-x64, linux-musl-x64 libcombit-listlabel32-conversiontoolsext.so
osx-x64, osx-arm64 libcombit-listlabel32-conversiontoolsext.dylib

On Linux, the enhanced engine is available for x64 only, on glibc-based distributions such as Debian or Ubuntu (linux-x64) and on musl-based ones such as Alpine (linux-musl-x64). Linux on ARM64 (linux-arm64, linux-musl-arm64), including ARM64 container images, has the standard engine only. There, as on every other platform not listed, Pdf always uses the standard engine and PdfEnhanced fails.

  • With Pdf, that library is used when it can be loaded and the standard engine is used when it cannot. The choice is written to the log at debug level, naming the engine and, where the native one was taken, its version.
  • With PdfEnhanced, a library that cannot be loaded fails the export with a ListLabelException naming the expected file and the runtime identifier it looked for. The export is refused before the report is rendered.
  • PdfStandard never touches that library.
Important

The two engines are not interchangeable in their output. Text measurement differs - the enhanced engine applies kerning, the standard one does not - so the same report can break lines differently under each. With Pdf that means output depends on what is deployed on the machine that runs the export. Where documents have to match each other, or a stored reference, name PdfStandard or PdfEnhanced explicitly instead of leaving the choice open.

Note

Fonts resolve differently, too. The enhanced engine looks an installed font up by its family and style name, which does not reach the named instances of a variable font: Windows lists Bahnschrift Light, Cascadia Code SemiBold, Segoe UI Variable Text and the Sitka optical sizes as families of their own, but a variable font carries one family name and defines its instances separately. A report set in one of those comes out of PdfEnhanced in the platform's default sans-serif instead, while PdfStandard renders it as designed. Everything a business document is normally set in - Arial, Calibri, Segoe UI, Times New Roman, Verdana, Tahoma, Georgia, Courier New - resolves in both. The substitution is logged at debug level, and layout is unaffected because the substituted font's own metrics are used for measuring.

Note

"No additional native library" is not the same as "no native dependency". The standard backend has native components of its own - the native SkiaSharp assets, plus the system font and image libraries on Linux - which every export target needs, PDF or not. See Deployment. On Windows and macOS the SkiaSharp assets ship with combit.ListLabel32.CrossPlatform, on Linux with the package listed above. What PdfEnhanced adds is one further library on top of those.


Supported export options

All options are set on ExportConfiguration.ExportOptions using the LlExportOption members listed below, for example exportConfiguration.ExportOptions[LlExportOption.PdfTitle] = "Invoice". Values are always strings, except for the e-invoice stream described below.

Options for both engines

Document metadata

The following options populate the corresponding fields in the PDF document properties.

Option Purpose
PdfTitle Title shown in the PDF properties.
PdfSubject Subject shown in the PDF properties.
PdfKeywords Comma- or semicolon-separated list of keywords.
PdfAuthor Author shown in the PDF properties.
PdfCreator Creator/application name shown in the PDF properties.

If a metadata option is not set, the corresponding PDF property is left empty.

Resolution

Sets the resolution in DPI at which content is rasterized when it cannot be written as PDF vector graphics:

  • PDF objects and PDF table fields, on both engines.
  • Charts and SVG drawings, on the enhanced engine only. The standard engine writes them as vector graphics.

Images are embedded at their own resolution and are not affected.

  • Value: a positive integer DPI value up to "2400", for example "300". A higher value is reduced to "2400"; any other value is ignored and the default applies.
  • Default: "400".
  • Increasing the resolution improves the quality of rasterized elements at the cost of file size. A single rasterized element is limited to 64 million pixels; beyond that its resolution is reduced.

Options for the standard engine

Beyond the options above, PdfStandard - and Pdf where the native library cannot be loaded - reads one more:

Option Purpose
PdfConformance PDF/A level. This engine writes one of them.
Name Meaning PDF version written
pdfa2b PDF/A-2b (ISO 19005-2, Level B) 1.4

Level U is not offered by this engine. It requires every glyph to map back to Unicode, and the standard engine cannot guarantee that for shaped text such as Indic conjuncts or typographic ligatures. Use the enhanced engine where text has to be reliably extractable.

Any other pdfa* level fails the export with a ListLabelException before the report is rendered, rather than quietly producing a plain PDF - use PdfEnhanced for those, or Pdf to take the enhanced engine wherever its library is deployed. The pdf1x values have no effect here; this engine always writes PDF 1.4, which PDF/A-2 allows. Spelling is as forgiving as below, so "PDF/A-2b" selects the same thing as "pdfa2b".

An e-invoice - PdfZUGFeRDXmlPath or PdfZUGFeRDXmlStream - fails the export the same way: this engine cannot embed one, and an invoice PDF without its XML would look finished without being one. So does encryption - PdfEncryptionEncryptFile set to "1", or an owner or user password without PdfEncryptionEncryptFile being set to "0" - because the alternative is an unprotected document that was meant to be protected. The permission options on their own ask for no encryption and are ignored.

Options for the enhanced engine

The following options are honored by the enhanced engine only. PdfStandard, and Pdf on a machine where the native library cannot be loaded and the standard engine is used instead, read PdfConformance as described above and fail the export where the other options ask for encryption or an e-invoice.

Option Purpose
PdfConformance PDF version and PDF/A level, as one of the names listed below. Unrecognized values mean PDF 1.7 without PDF/A; a value that names PDF/A without a level, such as "PDF/A-2", fails the export.
PdfEncryptionEncryptFile "1" encrypts the document, "0" leaves it unencrypted even when a password is set. Unset, a password implies encryption.
PdfOwnerPassword, PdfUserPassword Owner and user password. Either may be omitted. Without an owner password, a random one is used, so the permissions also apply to whoever opens the document with the user password, and nobody can lift them.
PdfEncryptionEnablePrinting, PdfEncryptionEnableChanging, PdfEncryptionEnableCopying, PdfEncryptionEnableFillingForms, PdfEncryptionEnableAnnotating Permissions of the encrypted document. Each is denied unless explicitly set to "1".
PdfZUGFeRDXmlPath Path to the e-invoice XML to embed. Selects pdfa3b unless a PDF/A-3 level is already set, an embedded attachment requiring PDF/A-3. To pass the XML in memory instead, see below.
PdfZUGFeRDConformanceLevel, PdfZUGFeRDVersion Profile and version of the embedded e-invoice. Auto-detected from the XML when unset.

PdfConformance takes the same names as the classic export, and this engine writes all of them:

Name Meaning PDF version written
pdf14 PDF 1.4, and explicitly no PDF/A 1.4
pdf15 PDF 1.5 1.5
pdf16 PDF 1.6 1.6
pdf17 PDF 1.7 1.7
pdf20 PDF 2.0 2.0
pdfa2b PDF/A-2b (ISO 19005-2, Level B) 1.7
pdfa2u PDF/A-2u (ISO 19005-2, Level U) 1.7
pdfa3b PDF/A-3b (ISO 19005-3, Level B) 1.7
pdfa3u PDF/A-3u (ISO 19005-3, Level U) 1.7

Spelling is forgiving - anything that reduces to the same letters and digits works, so "PDF/A-2b" and "pdfa2b" are the same value, and so are "PDF 2.0" and "pdf20".

Level A is not offered: it requires a tagged, structurally described document, which this exporter does not produce. Use Level U where text has to be reliably extractable, or Level B where it does not.

Note

PDF/A forbids encryption. Do not combine a pdfa* value with the encryption options.

The e-invoice XML can also be supplied in memory, through the one option that takes a stream:

exportConfiguration.ExportOptions.Add(LlExportOption.PdfZUGFeRDXmlStream, invoiceXmlStream);

The stream and PdfZUGFeRDXmlPath are the same option seen two ways, so set one or the other, not both.

An archivable document:

ExportConfiguration exportConfiguration = new ExportConfiguration(
    LlExportTarget.PdfEnhanced,
    "output/archive.pdf",
    projectFile);

// "PDF/A-3b" selects the same thing.
exportConfiguration.ExportOptions[LlExportOption.PdfConformance] = "pdfa3b";

listLabel.Export(exportConfiguration);

A protected document, which opens with the user password and can be neither printed nor copied from:

ExportConfiguration exportConfiguration = new ExportConfiguration(
    LlExportTarget.PdfEnhanced,
    "output/protected.pdf",
    projectFile);

exportConfiguration.ExportOptions[LlExportOption.PdfUserPassword] = userPassword;
exportConfiguration.ExportOptions[LlExportOption.PdfOwnerPassword] = ownerPassword;
exportConfiguration.ExportOptions[LlExportOption.PdfEncryptionEnablePrinting] = "0";
exportConfiguration.ExportOptions[LlExportOption.PdfEncryptionEnableCopying] = "0";

listLabel.Export(exportConfiguration);

Interactive input objects

The report designer's input objects - edit, checkbox, combo box and buttons with the action PDF signature - are exported as interactive PDF form fields, and only by the enhanced engine - so by PdfEnhanced, or by Pdf where the native library is available. A reader can fill the resulting document in and sign it, and the values can be extracted from it or submitted.

Object Becomes Carried over
Edit Text field, multi-line when the object is Name, default value, tooltip, alignment, multiline, read-only, required, filling, frame
Checkbox Checkbox, checked when its default value evaluates to true Name, default state, tooltip, read-only, filling, frame
Combo box Choice field carrying its options, editable when the object is Name, default value, the choice list, tooltip, alignment, editable, read-only, required, filling, frame
Button with the action PDF signature Empty signature field, signed in the PDF reader Name, tooltip, read-only
Button with any other action not exported -

The same applies to the input fields of a table. A signature button in a table becomes one signature field per row in which it is printed.

Signature fields

  • The field is unsigned. The export places the field only; signing it is left to the reader, with the signer's own certificate.
  • Each signature field gets a name of its own. Text fields that share a name share a value, but a signature cannot be shared - a reader would show every such field as signed by the first signature. Where the name is already taken, the field is numbered: Signature, Signature_2, Signature_3, and so on. A button without a name, and every signature button in a table, is named Signature.
  • A read-only button gives a locked field that cannot be signed.
  • The field draws neither frame nor filling. A button has neither in the report; how the field is shown before and after signing is up to the reader.
Important

Every other export target ignores these objects entirely - they are not drawn, and they take up no space. A report that relies on them looks incomplete in the PdfStandard, image, XLSX, DOCX, HTML, JSON and CSV exports - and in Pdf wherever the native library is missing.

Restrictions of the form fields

  • Only signature buttons are exported. Every other button is only useful with an action behind it - submit, save, send - and the PDF engine offers no way to attach one, so such a button would be an inert rectangle. It is left out rather than exported as decoration. A signature field needs no action, since the reader signs it.
  • The field font is one of four. PDF form fields use the standard form fonts, so a field's text is rendered in Helvetica, Courier, Times or ZapfDingbats - whichever is closest to the requested face - and not in the report's font. Size and colour are kept.
  • Field validation is not exported. The designer's verification rules need a script action in the PDF, which the engine does not offer.
  • The frame's style is not carried over, only its colour and width; and a checkbox's visual type is left to the reader, which draws the mark itself.

Restrictions

  • PDF encryption, owner/user passwords and ZUGFeRD/Factur-X attachments need the enhanced engine: they work with PdfEnhanced, and with Pdf only where the native library can be loaded. PdfStandard does not support them and fails the export when either is requested.
  • PDF/UA is not supported: it requires a tagged PDF, which neither engine writes. The classic PdfAccessibilityStandard option therefore does not exist in the cross-platform build.
  • The cross-platform exporter is designed for headless, server-side use; interactive PDF features (form actions, JavaScript) are not authored by the exporter.