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.
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();
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 | 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.
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.
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 - _ . :
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();
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.