PdfDocumentOptions Object

Summary

Provides extra options to use when saving a document using the Adobe Portable Document Format (PDF).

Syntax

JavaScript Syntax

function lt.Documents.Writers.PdfDocumentOptions 
	extends lt.Documents.Writers.DocumentOptions

TypeScript Syntax

class lt.Documents.Writers.PdfDocumentOptions() 
	extends lt.Documents.Writers.DocumentOptions

Remarks

The options set in the PdfDocumentOptions class will be used when the user saves a document using the DocumentFormat.Pdf format.

The PdfDocumentOptions class contains the following features:

Feature

Description

Set the PDF document type to PDF or PDF/A.

Use the PdfDocumentOptions.DocumentType property to set the document type to either PDF or PDF/A.

Control the font embedding mode

Use the PdfDocumentOptions.FontEmbedMode property to control how the fonts are embedded in the resulting PDF document. Note that PdfDocumentOptions.FontEmbedMode is not used when saving PDF/A files; all fonts are always embedded in the file.

Add an image as an overlay on top of the PDF content.

Use the PdfDocumentOptions.ImageOverText property to add the original raster image as an overlay on top of the PDF content. The resulting document will look exactly like the original document. Use the ImageOverTextSize and ImageOverTextMode properties to control the quality of this image.

Create linearized PDF documents optimized for fast web viewing.

A linearized PDF file is a file that has been organized in a special way to enable efficient incremental access in a network environment. This allows the first page of the PDF file to be displayed in a user Web browser before the entire file is downloaded from the Web server. To enable the creation of linearized PDF documents, use the PdfDocumentOptions.Linearized property. PDF linearization is supported in both PDF and PDF/A formats.

Set the PDF document metadata

The resulting PDF can contain optional metadata associated with the document. This metadata can be used by external search and indexing engines to search and classify PDF documents. Use the PdfDocumentOptions.Title, PdfDocumentOptions.Subject, PdfDocumentOptions.Author and PdfDocumentOptions.Keywords to set the document metadata.

Set the PDF initial view properties

The user can control the intial view properties of the generated PDF file as follows:

Property	Description
PageModeType	Page mode such page only, page with bookmarks, page with thumbnails, etc.
PageLayoutType	Page layout such single page, one column, two pages, etc.
PageFitType	Page fit such as none, fit width, height, etc.
InitialPageNumber	Initial page number to go to.
XCoordinate and YCoordinate	Position of the page to use go to initially.
ZoomPercent	Zoom percentage to use when the document is opened.
HideToolbar, HideMenubar and HideWindowUI	Show or hide various user interface elements.
FitWindow and CenterWindow	How the document is viewed in the window.
DisplayDocTitle	Display the document title in the viewer.

Security, access rights and Encryption

PDF documents can be protected (secured) using two methods:

Protected against viewing. PDF viewers will request a password from the user when the document is opened for viewing. This password is called the user password. The created PDF document can be protected by setting the PdfDocumentOptions.IsProtected property to true and the PdfDocumentOptions.UserPassword property to the password value.
Protected against editing. PDF editor will request a password from the user when the document is opened for editing. This password is called the owner password. The created PDF document can be protected by setting the PdfDocumentOptions.IsProtected property to true and the PdfDocumentOptions.OwnerPassword property to the password value.

When a PDF document is protected against editing (through the use of an owner password), an encryption level and owner access rights can be granted or denied in the resulting document. The following table lists the PDF access rights supported by the LEADTOOLS Document Writers:

Encryption	Owner Access Right
Low (PdfDocumentOptions.EncryptionMode set to PdfDocumentEncryptionMode.RC40Bit)	Printing (PdfDocumentOptions.PrintEnabled), Copying text (PdfDocumentOptions.CopyEnabled), Editing (PdfDocumentOptions.EditEnabled) and Annotations and comments (PdfDocumentOptions.AnnotationsEnabled).
High (PdfDocumentOptions.EncryptionMode set to PdfDocumentEncryptionMode.RC128Bit)	Adds the following to owner access rights supported by low level encryption: High quality printing (PdfDocumentOptions.HighQualityPrintEnabled) and adding/removing pages PdfDocumentOptions.AssemblyEnabled.

Saving PDF files with minimum file size

The following table shows the suggested PDF document options to use to achieve the smallest output PDF file size while maintaining an acceptable quality.

Property	Value	Remarks
OneBitImageCompression	OneBitImageCompressionType.Jbig2	JBIG2 format offers the best 1-bit image compression.
ColoredImageCompression	ColoredImageCompressionType.FlateJpx	JPX offers the best colored image compression (8 or 24 bits per pixel). Revert to flate compression if the image has bits per pixel value other than 8 or 24.
ImageOverTextSize	DocumentImageOverTextSize.Half	Only used when using the image over text option (ImageOverText is true). The overlay image is sized by half and stretched over the page. This will save up to 75% of the size while maintaining the image quality.
ImageOverTextMode	DocumentImageOverTextMode.Relaxed	Only used when using the image over text option (ImageOverText is true). Any grayscale overlay image is converted to black and white while ignoring noise and shadows.
QualityFactor	50 or 100	Use 50 when using the image over text option (ImageOverText is true). Use 100 when image over text is not used (ImageOverText is false).
PdfDocumentOptions.FontEmbedMode	DocumentFontEmbedMode.None	Do not embed the fonts in the PDF file. Warning: The result PDF is not guaranteed to have the same fonts used to create it. Use this option only if font substituting is acceptable in your particular scenario. Otherwise, leave this to the default value of DocumentFontEmbedMode.Auto.

The following code snippet shows how to set the PDF options to produce minimum file size with acceptable quality:

function createPDFOptions(useImageOverText) { 
// Create options 
var pdfOptions = new lt.Documents.Writers.PdfDocumentOptions(); 
 
// Use JBIG2 for B/W images 
pdfOptions.oneBitImageCompression = lt.Documents.Writers.OneBitImageCompressionType.jbig2;; 
 
// Use JPEG2000 or Flate for colored images 
pdfOptions.coloredImageCompression = lt.Documents.Writers.ColoredImageCompressionType.flateJpx; 
 
// Embed fonts automatically 
pdfOptions.fontEmbedMode = lt.Documents.Writers.DocumentFontEmbedMode.auto; 
 
if (useImageOverText) { 
// Use image over text 
pdfOptions.imageOverText = true; 
 
// Re-size the overlay image by 2 
pdfOptions.imageOverTextSize = lt.Documents.Writers.DocumentImageOverTextSize.half; 
 
// Convert grayscale to black and white if possible 
pdfOptions.imageOverTextMode = lt.Documents.Writers.DocumentImageOverTextMode.relaxed; 
 
// Use quality factor of 50 
pdfOptions.qualityFactor = 50; 
} else { 
// Will not use image over text 
pdfOptions.imageOverText = false; 
 
// Use quality factor of 100 
pdfOptions.qualityFactor = 100; 
} 
 
// Use this 
return pdfOptions; 
}

Example

This example will create a new encrypted Adobe Portable Document Format document (PDF) file using the various supported options.

JavaScript Example

function convertToPDFExample(doc) { 
   // Create a new PDF document with: PDF and no image/text 
   var pdfOptions = new lt.Documents.Writers.PdfDocumentOptions(); 
   pdfOptions.documentType = lt.Documents.Writers.PdfDocumentType.pdf; 
   pdfOptions.fontEmbedMode = lt.Documents.Writers.DocumentFontEmbedMode.none; 
   pdfOptions.imageOverText = false; 
   pdfOptions.linearized = false; 
   pdfOptions.title = "Add your title here"; 
   pdfOptions.subject = "Add your subject here"; 
   pdfOptions.keywords = "Add your keywords here"; 
   pdfOptions.author = "Add author name here"; 
   pdfOptions.isProtected = true; 
   pdfOptions.userPassword = "password"; 
   pdfOptions.ownerPassword = "Owner password"; 
   pdfOptions.encryptionMode = lt.Documents.Writers.PdfDocumentEncryptionMode.rc128Bit; 
   pdfOptions.printEnabled = false; 
   pdfOptions.highQualityPrintEnabled = true; 
   pdfOptions.copyEnabled = false; 
   pdfOptions.editEnabled = true; 
   pdfOptions.annotationsEnabled = true; 
   pdfOptions.assemblyEnabled = false; 
   pdfOptions.oneBitImageCompression = lt.Documents.Writers.OneBitImageCompressionType.flate; 
   pdfOptions.coloredImageCompression = lt.Documents.Writers.ColoredImageCompressionType.flateJpeg; 
   pdfOptions.qualityFactor = 2; 
   var jobData = new lt.Documents.DocumentConverterJobData(); 
   jobData.documentFormat = lt.Documents.Writers.DocumentFormat.pdf; 
   jobData.rasterImageFormat = lt.Documents.RasterImageFormat.unknown; 
   // Set document options 
   jobData.documentOptions = pdfOptions; 
   doc.convert(jobData) 
       .done(function (result) { 
          console.log("Converted..."); 
          // Show it in a new tab 
          // This is generic code, we know the result is in "document" since PDF supports that 
          // But this code checks if the results have been archived into a ZIP file if this 
          // example was converting to, say SVG 
          var resultDocument = result.document != null ? result.document.url : result.archive.url; 
          window.open(resultDocument); 
       }) 
       .fail(function (jqXHR, statusText, errorThrown) { 
          showServiceError(jqXHR, statusText, errorThrown); 
       }); 
}