Click or drag to resize

Document Class

This class represents a PDF document in the PDF Creator framework. A Document object can be created from an existing PDF document or an empty document can be created using the default constructor of the Document class. When creating a Document object from an existing PDF document, the existing PDF document is passed to the Document class constructor as the path of the .pdf file on disk or as a stream containing the PDF document binary image. In either case the resulted Document object can be further modified using the PDF Creator API. There are also Document constructors accepting a password when creating a Document object form a password protected PDF document. Here are the Document class constructors:

public Document();
public Document(Stream pdfStream);
public Document(string pdfFileName);
public Document(Stream pdfStream, string pdfPassword);
public Document(string pdfFileName, string pdfPassword);

The Document class offers access to the PDF pages collection, PDF fonts collection, bookmarks, security features, templates and viewer preferences. For example you can add a new page to the document pages collection using the AddPage method, adding a new font to the fonts collection using the AddFont(Font) method or adding a new template using the AddTemplate(RectangleF) method.

Code Sample

Below is a sample code to show a typical usage scenario of the PDF Creator API to instantiate a Document object and set various properties of the Document object. The code is taken from the HTML to PDF converter sample and it creates a Document object, adds a PDF page to the document and then adds a HTML to PDF converter element to the page. Finally the page is sent as response to the client browser.

// a new PDF document with A4 pages and 20 point margins
Document document = new Document();
document.DocumentInformation.Title = "Report";
document.DocumentInformation.Author = "Example Inc.";

PdfPage page = document.AddPage(PageSize.A4, new Margins(20, 20, 20, 20), PageOrientation.Portrait);
PdfFont titleFont = document.AddFont(new Font("Arial", 18, FontStyle.Bold), true);

// a title, then HTML content right below it
AddElementResult titleResult = page.AddElement(new TextElement(0, 0, "Monthly report", titleFont));

HtmlToPdfElement html = new HtmlToPdfElement(0, titleResult.EndPageBounds.Bottom + 10, "https://www.example.com/report-body");
html.RenderingEngine = RenderingEngine.Chromium;
AddElementResult htmlResult = page.AddElement(html);

// the HTML can span several pages: continue on the page where it ended
PdfPage lastPage = document.Pages[htmlResult.EndPageIndex];
lastPage.AddElement(new TextElement(0, htmlResult.EndPageBounds.Bottom + 10, "End of the report", titleFont));

document.Save("report.pdf");
document.Close();
PDF standards (PDF/A, PDF/X)

By default the library creates standard PDF documents that every PDF reader opens. Create the document with a PdfStandardSubset to make it conform to an ISO subset of PDF - for long term archiving (PDF/A), printing (PDF/X) or electronic invoices (PDF/A-3):

PdfStandardSubset

Standard

Use

Full

PDF

The default: every PDF feature can be used.

Pdf_A_1b

PDF/A-1b (ISO 19005-1)

Long term archiving, for systems that require PDF/A-1. No transparency.

Pdf_A_2b

PDF/A-2b (ISO 19005-2)

Long term archiving; transparency and layers allowed. The usual choice for archiving.

Pdf_A_3b

PDF/A-3b (ISO 19005-3)

PDF/A-2b that can embed files of any type (associated files): electronic invoices, source data.

Pdf_A_3u

PDF/A-3u

PDF/A-3b with Unicode text that can be reliably extracted and searched.

Pdf_A_3a

PDF/A-3a

PDF/A-3u with a tagged, accessible structure. Needs a tagged document (Document.Tagged = true, see Tagged PDF).

Pdf_X_1a

PDF/X-1a:2003 (ISO 15930-4)

Graphics exchange for printing: CMYK colors, no transparency.

Pdf_SiqQ_a, Pdf_SiqQ_b

PDF/SigQ level A and B

Documents meant to be digitally signed.

Document document = new Document(PdfStandardSubset.Pdf_A_2b);
document.DocumentInformation.Title = "Annual report";
// ... add pages and content ...
document.Save("report-pdfa.pdf");
document.Close();

A PDF/A-3 document can carry other files - the data behind a report, the source document - added with AddAssociatedFile and an AttachmentRelationship. For electronic invoices see ZUGFeRD / Factur-X invoices; for accessible documents see Tagged PDF.

Document document = new Document(PdfStandardSubset.Pdf_A_3b);
// ... add pages and content ...
document.AddAssociatedFile("sales.csv", AttachmentRelationship.Data, "text/csv", "Sales figures");
document.Save("sales-report.pdf");
document.Close();
Page labels

Page labels are the page numbers a PDF viewer shows and accepts in its page box instead of the page positions - for example i, ii, iii for the front pages of a report and 1, 2, 3 for its body, or A-1, A-2 for an appendix. They do not change the pages. AddPageLabelRange starts a range at a page position: a PageLabelStyle (decimal, roman or letters, or no number), an optional prefix and the number of the first page of the range. A range ends where the next one starts; the pages before the first range are numbered 1, 2, 3. GetPageLabel(Int32) returns the label of a page and ClearPageLabels removes the ranges.

Document document = new Document();
PdfFont font = document.AddFont(new Font("Arial", 12), true);
for (int i = 0; i < 9; i++)
    document.AddPage().AddElement(new TextElement(0, 0, "Page " + (i + 1), font));

// i, ii, iii for the first three pages, then 1, 2, 3..., and A-1, A-2... for the appendix that starts on page 8
document.AddPageLabelRange(0, PageLabelStyle.LowercaseRoman);
document.AddPageLabelRange(3, PageLabelStyle.Decimal);
document.AddPageLabelRange(7, PageLabelStyle.Decimal, "A-", 1);

document.Save("labels.pdf");
document.Close();

The ranges refer to the page positions when the document is saved: add them after the pages are added or removed. Page labels can be used in PDF/A documents.

Named destinations

A named destination is a place in the document that a web page or another document can link to by name, with the name after # in the address of the document: report.pdf#summary. AddNamedDestination(String, ExplicitDestination) adds one for an ExplicitDestination (a page, a point on the page and how the page is displayed). The name has up to 127 characters: ASCII letters, digits and the characters - _ . :

// the summary starts 200 points down the second page
document.AddNamedDestination("summary", new ExplicitDestination(document.Pages[1], new PointF(0, 200)));
Table of contents

A TableOfContents lists headings with the numbers of the pages they are on, each entry a link to its heading. InsertTableOfContents(TableOfContents, Int32) inserts it at a page position, on as many pages as the entries need, and returns the number of pages inserted. Add the entries after the content: AddEntries(Document, HtmlElementMappingsCollection) takes the headings an HTML conversion mapped (HtmlElementsMappingOptions with the "h1", "h2"... selectors; h1 is level 1, h2 level 2), and AddEntry(String, Int32, PdfPage, Single) adds an entry of your own.

The page numbers are the page labels when the document has page label ranges. Ranges that start at or after the position where the table is inserted move with their pages, so the content can be numbered first and the table inserted before it. The title, fonts, colors, indent and dotted leaders are properties of the table of contents. In a tagged document the table is tagged as a TOC element.

Document document = new Document();
PdfPage page = document.AddPage();

// a long HTML document; the converter maps where its headings are
HtmlToPdfElement html = new HtmlToPdfElement("https://www.example.com/manual");
html.RenderingEngine = RenderingEngine.Chromium;
html.HtmlElementsMappingOptions.HtmlElementSelectors = new string[] { "h1", "h2", "h3" };
page.AddElement(html);

TableOfContents toc = new TableOfContents();
toc.Title = "Contents";
toc.AddEntries(document, html.HtmlElementsMappingOptions.HtmlElementsMappingResult);

// the content pages are numbered 1, 2, 3...; the table pages before them i, ii...
document.AddPageLabelRange(0, PageLabelStyle.Decimal);
int tocPages = document.InsertTableOfContents(toc, 0);
document.AddPageLabelRange(0, PageLabelStyle.LowercaseRoman);

document.Save("manual.pdf");
document.Close();
Select Color Space (RGB, CMYK, Grayscale)

By default, the converter uses the RGB color space to draw graphics and images. Using the Document class constructor with a parameter of ColorSpace type, it is possible to instruct the converter to use the CMYK or Grayscale color space when the PDF document is rendered.