Document Class |
The Document class represents a PDF document in the ExpertPdf Anywhere document model. An empty document is created with the default constructor, and a document is created from an existing PDF document with the constructors that take the path of a .pdf file or a stream containing the PDF document. Either document can then be changed with the document model. The constructors with a password open a password protected PDF document; the password can be the user or the owner password. 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); public Document(PdfStandardSubset pdfSubset); public Document(ColorSpace colorSpace); public Document(PdfStandardSubset pdfSubset, ColorSpace colorSpace);
The Document class gives access to the pages, the fonts, the bookmarks, the security settings, the templates, the document information and the viewer preferences. For example, a new page is added to the document with the AddPage method, a new font with the AddFont(Font) method and a new template with the AddTemplate(RectangleF) method. The document is saved with the Save methods: to a file, to a stream, or to a byte array.
The class implements IDisposable: create the document in a using block, or call Close when you no longer need it. A document created from a stream closes that stream when it is closed, unless DetachStream was called first.
The code below shows a typical use of the Document class: it creates a document, sets its properties, adds a page with a title, adds an HTML to PDF element below the title, and adds a text after the HTML content, on the page where that content ended.
// a new PDF document with A4 pages and 20 point margins using (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), PDFPageOrientation.Portrait); PdfFont titleFont = document.AddFont(new Font("Arial", 18, FontStyle.Bold)); // a title, then HTML content right below it AddElementResult titleResult = page.AddElement(new TextElement(0, 0, "Monthly report", titleFont)); float htmlTop = titleResult.EndPageBounds.Bottom + 10; HtmlToPdfElement html = new HtmlToPdfElement(0, htmlTop, "https://www.example.com/report-body"); 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"); }
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_1a | PDF/A-1a | PDF/A-1b with a tagged, accessible structure; the PDF/A-1 level that combines with PDF/UA-1. Needs a tagged document. |
Pdf_A_2b | PDF/A-2b (ISO 19005-2) | Long term archiving; transparency and layers allowed. The usual choice for archiving. |
Pdf_A_2u | PDF/A-2u | PDF/A-2b with Unicode text that can be reliably extracted and searched. |
Pdf_A_2a | PDF/A-2a | PDF/A-2u with a tagged, accessible structure. Needs a tagged document. |
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. |
Pdf_A_4 | PDF/A-4 (ISO 19005-4) | Long term archiving on PDF 2.0; the level that combines with PDF/UA-2. |
Pdf_A_4e, Pdf_A_4f | PDF/A-4e, PDF/A-4f | The PDF/A-4 variants for engineering documents (3D, rich media) and for embedded files of any kind. |
Pdf_X_1a | PDF/X-1a (ISO 15930) | Graphics exchange for printing: CMYK colors, no transparency. |
A document created with a level A standard must be tagged: set Tagged to true and tag its content (see Tagged PDF). The accessibility standard, PDF/UA-1 or PDF/UA-2, is declared separately with AccessibilityStandard. A PDF/A or PDF/X document cannot be encrypted. An existing document is converted to PDF/A with ConvertToPdfA(PdfStandardSubset). See PDF Standards for more about the standards.
using (Document document = new Document(PdfStandardSubset.Pdf_A_2b)) { document.DocumentInformation.Title = "Annual report"; // ... add pages and content ... document.Save("report-pdfa.pdf"); }
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.
using (Document document = new Document()) { PdfFont font = document.AddFont(new Font("Arial", 12)); for (int i = 0; i < 9; i++) { PdfPage page = document.AddPage(); page.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"); }
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.
using (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.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"); }
By default, the document model uses the RGB color space to draw graphics and images. The Document class constructors with a parameter of ColorSpace type create a document that draws its graphics in the CMYK or Grayscale color space instead.