print Method

Prints the document set in the viewer with the provided options.

DocumentViewer.prototype.print = function( 
   options 
) 

print( 
   options: PrintDocumentOptions 
): JQueryPromise<any>; 

Parameters

Print prints the Document with the provided PrintDocumentOptions.

Print and the rest of the DocumentViewer HTML5 Printing API do not communicate directly with any printing devices. Printing on the web is performed by constructing HTML content containing the pages of the document to be printed along with styles to control size and position, followed by a call to the JavaScript window.print method. After window.print is called, the browser takes control of the screen and no changes can be made to the printed content. The native browser print dialog allows the user to send the HTML content to the printer or export it as PDF, if the browser has this support.

Print is a DocumentViewerOperation, and thus a user can receive page-by-page updates by attaching a listener to DocumentViewer.Operation. When a page is being prepared for printing, Print will send out DocumentViewerOperationEventArgs before and after it attempts to prepare the page. If the page will be loaded by URL from a service, another set of DocumentViewerOperationEventArgs will be sent for DocumentViewerOperation.GetPage. Since Print is an asynchronous method, it returns a JQuery promise object that the application may attach a done or fail callback to. If the operation is a success, the promise will be resolved with DocumentPrintData as the argument to the callback.

If the operation fails or is aborted (through DocumentViewerOperationEventArgs.Abort), the fail callback will run with the exception or null, respectively. DocumentViewerOperationEventArgs will be sent indicating the end of the DocumentViewerOperation.PrintPages operation and any exception.

In greater detail, Print will: 1. Create the result DocumentPrintData and send the pre-operation DocumentViewerOperationEventArgs with DocumentViewerOperation.PrintPages and DocumentViewerOperationEventArgs.PageNumber as 0, indicating the start of the operation.

1. Check that printing is supported, the document has pages, and that options is not null.

2. Check that PrintDocumentOptions.Parent is a valid HTMLElement, if PrintDocumentOptions.AutoOpenBrowserPrint is true.

3. Add the necessary (potentially browser-specific) styles to DocumentPrintData.PrintStyles.

4. Loop through each page, creating a DocumentPrintPageData instance and adding it to DocumentPrintData.Pages.

5. Load the pages for printing, setting the result to DocumentPrintPageData.PageElement:

a. Send the pre-operation DocumentViewerOperationEventArgs for DocumentViewerOperation.PrintPages with the page number.

b. Send the pre-operation DocumentViewerOperationEventArgs for DocumentViewerOperation.GetPage with the page number, if the page must be loaded from the service.

c. Load the page using PDF Client Rendering or a call from ImageLoader to the service.

d. Send the post-operation DocumentViewerOperationEventArgs for DocumentViewerOperation.GetPage with the page number, if the page was loaded from the service.

e. Send the post-operation DocumentViewerOperationEventArgs for DocumentViewerOperation.PrintPages with the page number.

1. Assigned the current on-screen annotations to DocumentPrintPageData.AnnotationsElement for each page if PrintDocumentOptions.ShowAnnotations is true.

2. Call DocumentPrintData.BuildPrintRoot to construct the elements from DocumentPrintData.Pages into an HTML structure.

3. Send the post-operation DocumentViewerOperationEventArgs for DocumentViewerOperation.PrintPages and DocumentViewerOperationEventArgs.PageNumber as 0, indicating the end of the operation.

4. Call OpenBrowserPrint if PrintDocumentOptions.AutoOpenBrowserPrint is true.

5. Resolve the promise with the DocumentPrintData.

Print will attempt to get the print pages either by using PDF Client Rendering (if enabled – see IsUsingPDFRendering) or accessing the service. You can force loading by URL from the service with PrintDocumentOptions.UsePDFClientRendering as false.

The DocumentViewerOperationEventArgs object indicates whether the operation is pre- or post-, the page number, and relevant data. See the table below for exact values about the event arguments:

Usually, DocumentViewerOperation.GetPage will set DocumentViewerOperationEventArgs.Data2 to the ImageLoader for the back image of the page, or null if the operation is not for the back image. You can use the existence and type checking for DocumentViewerOperationEventArgs.Data2 to determine if the DocumentViewerOperationEventArgs from DocumentViewerOperation.GetPage are for printing.

DocumentViewerOperationEventArgs.Abort will abort the operation if DocumentViewerOperationEventArgs.IsPostOperation is true or DocumentViewerOperationEventArgs.PageNumber is 0.

The DocumentPrintPageData is an object containing the data for the document page to be printed. By changing DocumentPrintPageData.Action to DocumentPrintPageAction.Manual when DocumentViewerOperationEventArgs.IsPostOperation is false, you can prevent Print from attempting to load the page - and insert your own content instead.

Instead of printing each page of the document on its own page without regard to zoom, position, or rotation, Print can also create "screenshot" prints that capture these attributes of the viewport. PrintDocumentOptions.UseViewportLayout will print the document pages as one composed image that maintains the positions and rotations of the images, while PrintDocumentOptions.ViewportClip will clip out parts of the pages that are not on screen and apply zooming.

To understand the full functionality of Print, see PrintDocumentOptions.

For an example, refer to the doPrint function in the document viewer demo source code.

Printing is supported by all major browsers and devices. However, it be limited or even not supported with some combination. The Document toolkit code is continuously being updated to match the latest "evergreen" browsers. It is recommended to try the printing functionality from using the live Document Viewer demo at https://demo.leadtools.com/JavaScript/DocumentViewer/ to determine the latest level of support for printing using a particular browser and device combination.

History

19.0.0.48

As of version 19.0.0.48, the Print API has been changed to reflect large internal changes that should allow users greater control over the printing process.

Prior to version 19.0.0.48, Print took two parameters:

element

iframe element OR div element passed by the user to add the temp printing data to it. Must not be null.

options

Document printing options (Page Size, orientation ...etc), can be null.

The element argument is now PrintDocumentOptions.Parent.

Print also had no return value; the browser's native print dialog (or an error) would appear on screen indicating the results of printing. The user had no way to modify the printed page data once Print was called, and was only updated on the progress of the print via DocumentViewerPrintProgress and DocumentViewer.Operation with DocumentViewerOperation.PrintPages.

19.0.0.53

As of version 19.0.0.53, PrintDocumentOptions.Dpi can be used to set a DPI value that will change the resolution of the final printed page image to DocumentPrintPageData.PrintSizeDpi and fit it into the parent of size DocumentPrintPageData.PrintSize.

19.0.0.54

As of version 19.0.0.54, Print can now create "screenshot" printing areas with the PrintDocumentOptions.ViewportClip and PrintDocumentOptions.UseViewportLayout options.

Target Platforms

Reference

DocumentViewer Class

DocumentViewer Members

Leadtools.Documents.UI Namespace