Documents for PDF, .NET Edition Documentation
In This Topic
    Product Architecture
    In This Topic

    Packaging

    GcPdf is a collection of .NET Standard 2.0 class libraries written in C#, providing an API that allows to create PDF files from scratch and to load, analyze and modify existing documents.

    GcPdf works on all platforms supported by .NET Standard, including .NET Core, ASP.NET Core, .NET Framework and so on.

    GcPdf and supporting packages are available on nuget.org:

    To use GcPdf in an application, you need to reference just the Grapecity.Documents.Pdf package. It pulls in the required infrastructure packages.

    To render barcodes, install the GrapeCity.Documents.Barcode package (GcBarcode for short). It provides extension methods allowing to draw barcodes when using GcPdf.

    On a Windows system, you can optionally install Grapecity.Documents.Common.Windows. It provides support for font linking specified in the Windows registry. This library can be referenced on a non-Windows system, but does nothing.

    GrapeCity.Documents.Common is an infrastructure package used by GcPdf and GcBarcode. GrapeCity.Documents.DX.Windows provides access to the native imaging APIs to GcPdf if it runs on a Windows system.

    GcPdf API Overview

    Classes and other types in the GcPdf and related libraries expose a PDF object model that closely follows the Adobe PDF specification version 1.7 published by Adobe. GcPdf is designed to provide, whenever feasible, direct access to all features of the PDF format, including the low-level features. In addition, GcPdf provides a powerful and platform-independent text layout engine and some other high-level features that make document creation using GcPdf easy and convenient.

    Namespaces

    Namespaces Description
    GrapeCity.Documents.Common  Infrastructure and utility types (including fonts support).
    GrapeCity.Documents.Drawing Framework for drawing on the abstract GcGraphics surface.
    GrapeCity.Documents.Pdf Types used to create, process and modify PDF documents includes GcPdfGraphics). Nested namespaces contain types supporting specific PDF spec areas:
    GrapeCity.Documents.Text Text processing sub-system.

    GcPdfDocument

    A PDF document in GcPdf is represented by an instance of the GrapeCity.Documents.Pdf.GcPdfDocument class. To create a new PDF, create an instance of GcPdfDocument, add content to it and then call one of the GcPdfDocument.Save() overloads to write the document to a file. Save() method can be called multiple times on an instance of GcPdfDocument, so that many (possibly different) PDF documents can be created.

    GcPdfDocument also provides a Load() method, allowing to analyze and/or modify an existing PDF. When Load() method is called on an instance of GcPdfDocument, the instance is cleared first. It is important to note that the Load() method accepts a Stream that is opened by the caller on the PDF which is loaded, and the stream must be readable and must be kept open for the duration of working with the loaded document. This is because Load() method does not actually load the whole document into memory, rather it loads the required parts on demand, which keeps the memory footprint to a minimum and improves performance. Note that Load() is a "read-only" method. GcPdfDocument does not try to write back to the loaded stream - In order to save any changes made to the document, Save() method must be called, specifying the output file or stream as a newly created document.

    A number of properties and collections on the GcPdfDocument provide access to the content and properties of the document. The most important collection is Pages (see The Pages Collection), others include Outlines, AcroForm, Security and so on.

    The Pages Collection

    The Pages collection represents the collection of a document's pages. When a new GcPdfDocument is created, this collection is initially empty. The usual collection modifying methods are available and can be used to fetch, add, insert, remove or move pages around. When an existing PDF is loaded into a GcPdfDocument, the Pages collection is filled with the pages loaded from that document. It can then be modified in the same way as in a document created from scratch.

    Modifying Existing Documents

    Using the GcPdfDocument.Load() method, existing documents can be inspected and modified. The possible modifications include:

    No other modifications are supported at this time. For example, it is currently not possible to replace existing text or graphics, except by removing existing and adding new content streams.

    It should be noted again that when an existing document is loaded into a GcPdfDocument instance, the connection with the original document is read-only, i.e. content is fetched as needed from the underlying stream, but no attempt is made to write back the changes. The GcPdfDocument.Save() method should be called if preserving the changes is required.

    Sequential (StartDoc/EndDoc) Mode

    In addition to the Save() method mentioned above, GcPdfDocument provides a sequential mode for creating a PDF. To use this mode, start by calling the StartDoc() method on the document, specifying a writable Stream as the method's only parameter. After that content can be added to the document as usual, but with following limitations. When done, call the EndDoc() method which completes writing the document.

    The limitations of the sequential method are as follows:

    The advantage of the sequential mode is that the pages of the document are written to the underlying stream as soon as they are completed, so especially if creating a very large PDF the memory footprint can be much smaller.

    Text

    Text measuring and layout is supported by a specialized set of classes in the GrapeCity.Documents.Text namespace. These classes provide a rich object model that includes, and allows access to text elements from high-level (paragraphs) all the way down to the lowest levels, such as individual font and glyph features. Text processing is completely platform-independent and does not rely on any operating system-provided APIs.

    The most important class in the GrapeCity.Documents.Text namespace is TextLayout, it represents one or more paragraphs of text, and supports the following features:

    All features are fully supported for vertical (Chinese or Japanese) and RTL/bidirectional text.

    After a text has been added to, and processed by, an instance of the TextLayout class, a representation of the text is generated using the glyphs from the specified fonts, and coordinates of any fragment of the original text in the generated layout can be fetched, if necessary.

    A TextLayout instance can also be directly rendered onto GcGraphics (see Graphics) using the DrawTextLayout method. Simple MeasureString/DrawString methods on GcGraphics are also provided for convenience.

    Graphics

    GcPdf provides a graphics surface to draw on, represented by a GcPdfGraphics class, which is an implementation of the abstract GcGraphics base class. GcPdfGraphics provides a flexible and rich object model for measuring, stroking, and filling the usual graphic primitives such as lines, rectangles, polygons, ellipses and so on. Drawing (Stroking) can be done with solid or dashed lines, shapes can be filled with solid, or gradient brushes. For an example of shape rendering methods, see GcPdfGraphics.DrawEllipse() or GcPdfGraphics.FillEllipse() method. Complex shapes can be created and rendered using graphic paths. For example, see GcPdfGraphics.DrawPath() method.

    Graphics transformations using 3x2 matrices are fully supported (including text). For more information, see GcPdfGraphics.Transform() method.

    Units of Measurement

    The default units of measurement used by GcPdfGraphics and TextLayout are printer points (1/72 of an inch). If desired, these can be changed to an arbitrary resolution using the Resolution property available on both GcPdfGraphics and TextLayout classes.

    Coordinates

    Coordinates of all graphic objects are measured from the top left corner of the graphics surface (which in GcPdfGraphics is usually a page). GcPdfGraphics.Transform can be used to change that.

    Page Graphics

    To draw on a page in a PDF document, an instance of GcPdfGraphics for that page must be used. Each page in the GcPdfDocument.Pages collection has the Graphics property that fetches the graphics for that page. You can simply get that property and draw on the returned graphics instance. Initially each page has just one graphics associated with it. But if the page contains multiple context streams, each context stream will have its own graphics, and the Page.Graphics property will return the graphics of the last (top-most) content stream. (All content streams of the page can be accessed via its ContentStreams collection.)

    GcHtml API Overview

    GcHtml is a utility library that renders HTML to PDF file or an image in PNG or JPEG format. It is based on the industry standard Chrome web browser engine working in headless mode, offering the benefit of rendering HTML to PDF or image on any platform - Windows, Linux and macOS. Currently, GcHtml works only on Intel-based 64-bit processor architecture. Also, it doesn’t matter whether your .NET application is built for x64, x86 or AnyCPU platform target. The browser is continuously working in a separate process.

    The GcHtml library consists of a platform-independent main package that exposes the HTML rendering functionality, and three platform-dependent packages that implement it on Windows, Linux and macOS. The main package must always be added to a project to use GcHtml. One or more platform-dependent packages should be added depending on the target platform(s) (all three can be added). GcHtml will select and use the correct package at runtime automatically.

    GcHtml NuGet Packages

    Description

    GrapeCity.Documents.Html

    The GrapeCity.Documents.Html package contains the following namespaces:

    • GrapeCity.Documents.Html namespace provides GcHtmlRenderer, PdfSettings, ImageSettings, PngSettings classes etc.
    • GrapeCity.Documents.Pdf namespace provides the GcPdfGraphicsExt and HtmltoPdfFormat classes.
    • GrapeCity.Documents.Drawing namespace provides GcGraphicsExt and HtmlToImageFormat class.
    GrapeCity.Documents.Html.Windows.X64 It is the interface unit and Chromium browser engine for 64-bit Windows platform.

    GrapeCity.Documents.Html.Mac.X64

    It is the interface unit and Chromium browser engine for macOS platform.

    GrapeCity.Documents.Html.Linux.X64

    It is the interface unit and Chromium browser engine for 64-bit Linux platform.

    Note that to use GcHtml on Linux, Chromium dependencies must be installed. The following command installs the necessary packages on Ubuntu:

    Copy Code
    sudo apt-get update
    sudo apt-get install libxss1 libappindicator1 libindicator7 libnss3-dev
    

    Namespaces

    Namespaces Description

    GrapeCity.Documents.Pdf

    It provides the extension methods for rendering HTML to PDF file and represents the formatting attributes for rendering HTML to PDF file.

    The namespace comprises the following classes:

     

    GrapeCity.Documents.Html

    It provides methods for converting HTML to PDF or images and defines parameters for the PDF or image.

    The namespace comprises the following classes:

    GrapeCity.Documents.Drawing

    It provides the extension methods and formatting attributes for rendering HTML to image.

    The namespace comprises the following classes:

    GrapeCity.Documents.Html.GcHtmlRenderer

    The GcHtmlRenderer class provides methods for converting HTML to PDF and images. An instance of this class is created for each HTML page/string to be rendered. Also, it must be disposed after using to delete temporary files. GcHtmlRenderer class has two constructors, the one that accepts Uri to the source HTML page and the other that accepts HTML as string. GcHtmlRenderer can convert the source HTML to the following formats: PDF, JPEG, PNG. The corresponding methods are RenderToPdfRenderToJpegRenderToPng. All these methods accept the output file path as the first parameter. GcHtmlRenderer always saves the result to file.

    GrapeCity.Documents.Html.PdfSettings

    The PdfSettings class represents output settings for rendering HTML to PDF and defines parameters for the Chromium PDF exporter. You could specify the default background color with the DefaultBackgroundColor property. In case of PDF it doesn’t support any transparency. Also, setting the DisplayBackgroundGraphics property to false prevents drawing any background graphics.

    PageWidth and PageHeight properties specify the page width and height in inches. If not set, the Letter paper size (8.5 by 11 inches) is used by default. If the page size is specified in the source HTML/CSS it has the priority but can be overridden by settings the IgnoreCSSPageSize property to true. The Landscape property indicates the corresponding paper orientation. All these properties can be helpful for some HTML pages and useless for others. Sometimes the markup splits pages at the fixed positions and there are no ways to improve pagination in the Chromium engine.

    The Margins property specifies page margins, in inches. In GcHtml all margins are equal to 0 by default.

    The Scale property effectively scales the content (the scale factor is between 0.1 and 2.0). You might also need to provide the scaled values for PageWidth and PageHeight properties to keep the relative size of the resulting pages unchanged.

    The PageRanges property allows to limit the number of pages in the output PDF file. You could specify the desired page numbers as a string, such the following: "1-5, 8, 11-13". Invalid page ranges (e.g. "9-5") are ignored.

    Setting the FullPage property to true allows to export the whole HTML as single PDF page. All other layout settings (except WindowSize and Scale) are ignored in that case.

    The WindowSize property specifies the size of hypothetical browser window, in pixels.

    GrapeCity.Documents.Pdf.HtmlToPdfFormat

    The HtmlToPdfFormat class contains the formatting attributes for rendering HTML to PDF file on a GcPdfGraphicsExt class using DrawHtml extension methods. The HTML is firstly drawn to a temporary PDF as single page (if FullPage is true) or with the specified page size (MaxPageWidth, MaxPageHeight), Scale and DefaultBackgroundColor. It is then loaded into a GcPdfDocument and trimmed to actual size of the HTML content. The result is rendered on a GcPdfGraphics as PDF Form XObject.

    If MaxPageWidth or MaxPageHeight properties are not set explicitly they are assumed to be equal to 200 inches. DefaultBackgroundColor is equal to Color.White by default.

    GcPdfGraphics Extension Methods

    GcHtml provides 4 methods that extend GcPdfGraphics and allow to render or measure an HTML text or page: