Click or drag to resize

Fine Control of HTML to PDF Conversion

The HTML to PDF Converter allows a very fine control of the PDF rendering process. The default settings of the converter should be acceptable for majority of the situations but sometimes more control and customizations is necessary.

This section offers a summary of the main properties of the converter that can be set to control the rendering of the PDF document:

PDF Document Page Orientation

You can set the PDF document page orientation to Portrait or Landscape. By default the document page is A4 size, Portrait orientation. To change the page orientation to Landscape you have to set the PdfPageOrientation property in HTML to PDF Converter or you can set the PDF page orientation when you create a new PDF page.

With the HTML to PDF Converter for .NET library, you can set the Landscape orientation of the PDF document pages with the following line of code:

Copy
// set the PDF page orientation
pdfConverter.PdfDocumentOptions.PdfPageOrientation = PDFPageOrientation.Landscape;
PDF Document Page Size

You can set the PDF page size to a standard size like A4, A3, Letter, etc or you can set the PDF page size to a custom value. The custom page size width and height are specified in points (1 point is 1/72 inches).

With the HTML to PDF Converter for .NET library you can set the PDF page size to a standard or custom value with the following code:

Copy
// set the PDF page size to standard A4
pdfConverter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4;

// set the PDF page size to a custom value
pdfConverter.PdfDocumentOptions.PdfPageSize = PdfPageSize.Custom;
pdfConverter.PdfDocumentOptions.CustomPdfPageSize = new SizeF(widthInPoints, heightInPoints);
HTML to PDF Converter Virtual Display

The converter internally uses a virtual display where it renders the HTML page very similar to what a regular web browser does on the screen. This virtual display is different from the display of your computer and it has a resolution of 96 dpi given by the Windows DPI scaling. The web page elements dimensions are usually measured in pixels and this is the reason why the virtual display of the converter is also specified in pixels. These are the only dimensions used by the converter which are expressed in pixels. All the other dimensions are specified in points (1 point is 1/72 inches). However, given the resolution of the virtual display, the dimensions in pixels of your web page can be easily converted to dimensions expressed in points. The converter API offers the UnitsConverter class which can be used to convert dimensions from pixels to points and from points to pixels.

You can specify the virtual display width and height in pixels using the PageWidth and PageHeight properties or you can specify the same values as parameters when you construct the PdfConverter object.

By default the virtual display width is set to 1024 pixels which should be sufficient to display the majority of the web pages. If the web page you are converting cannot be completely displayed in this width then you can increase this value or you can set the PageWidth property to 0 to allow the converter to automatically determine your web page width from the HTML elements width. The PageHeight property is 0 by default which means the virtual display will be automatically resized to display the whole HTML page. There are situations when the converter cannot automatically determine the web page height for example when the web page is a frame set. In this case, you can manually set the PageHeight to a certain value in pixels so that the page is displayed in the way you expect.

This is how the properties described above can be set:

Copy
PdfConverter pdfConverter = new PdfConverter();
pdfConverter.PageWidth = 793; // size of A4 page in pixels
pdfConverter.PageHeight = 0; // auto determine height
HTML Content Resizing in PDF Page

After the HTML content is displayed in the virtual display the virtual display content will be transfered into PDF as you would take a picture of the virtual display and put that picture into a PDF document. The PDF documents pages have a fixed size in points. For example, the A4 page with portrait orientation is 595 points in width and 842 points in height. If the virtual display width is more than 595 points then the rendered HTML content would be shrinked to fit the PDF page width and display the whole HTML content in the PDF document. If the virtual display width is less than 595 points then the rendered HTML content will not be resized and will be rendered in the top left corner of the PDF page at real size.

The dimension of the A4 portrait page in virtual device pixels is 793 x 1122 pixels. This means that at a default virtual display width of 1024 pixels, the HTML content will be shrunk to fit the PDF page. This is the reason why you can see smaller fonts and images in PDF than they are in the source HTML document.

The FitWidth property in PdfDocumentOptions can be used to specify if the HTML content is resized to fit the PDF page width. The default value is True which makes the HTML content to be resized if necessary to fit the PDF page width. When False, the HTML content will not be resized and it will be rendered at the real size in PDF (the size it has in the virtual display at the current virtual display resolution).

The FitHeight property in PdfDocumentOptions is similar to FitWidth and can be used to force the converter to fit all the HTML content into the height of the PDF page. If both FitWidth and FitHeight are True, then the HTML content will fit both the width and height of the PDF page.

When the FitHeight property is False, the HTML content could be wider than the PDF page width and the therefore the HTML content will be cut off to the right in PDF. In this case, in order to get the whole content in PDF, you have to set a wider page for the PDF document. You can first try to set Landscape orientation for the PDF page by setting PdfConverter.PdfDocumentOptions.PdfPageOrientation = PDFPageOrientation.Landscape. If this not enough you can choose a wider standard page like A3 or A2. You can even set a custom size for the PDF page as described in a section above. You can set the PdfConvert.PdfDocumentOptions.PdfPageSize = PdfPageSize.Custom and in this case the custom size of the PDF page will be taken from PdfConverter.PdfDocumentOptions.CustomPdfPageSize property.

The AutoSizePdfPage property was added to control the PDF page width. It has effect only when the FitWidth property is False. When FitWidth is False and AutoSizePdfPage is True, the PDF page width will be automatically resized to a custom value such that all the HTML content is displayed in PDF at real size.

If you don't want to resize the PDF page but you want to keep it A4 portrait for example, then you have to decrease the virtual display width. If your page can be correctly and entirely displayed in 793 pixels (which is the width of the A4 portrait page in pixels) you can set this value for PdfConverter.PageWidth property and you should get the whole HTML rendered at real size in PDF.

The HTML content can appear as not centered in the PDF page when the HTML content can be normally displayed at a width less than 1024 pixels. In this case there will normally be an empty space in the right side of the virtual display. When the virtual display content is transfered to PDF the content will appear as not centered in PDF. You can also solve this if you set the PdfConverter.PageWidth to a value of 793 pixels or less.

Single PDF Page Conversion

The HTML to PDF Converter offers also the possibility to produce the whole HTML content into a single PDF page automatically resized to display the whole content. To get this behavior you have to set the SinglePage property to True. When FitWidth is also true, the PDF page width will be preserved, otherwise the PDF page width will be automatically resized to display the whole HTML content.