Prints the document set in the viewer with the provided options.
DocumentViewer.prototype.print = function(
A PrintDocumentOptions object containing the options for the print action, which may not be null.
Print prints the Document with the provided PrintDocumentOptions.
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
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.
Check that printing is supported, the document has pages, and that options is not null.
Check that PrintDocumentOptions.Parent is a valid HTMLElement, if PrintDocumentOptions.AutoOpenBrowserPrint is true.
Add the necessary (potentially browser-specific) styles to DocumentPrintData.PrintStyles.
Loop through each page, creating a DocumentPrintPageData instance and adding it to DocumentPrintData.Pages.
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.
Assigned the current on-screen annotations to DocumentPrintPageData.AnnotationsElement for each page if PrintDocumentOptions.ShowAnnotations is true.
Call DocumentPrintData.BuildPrintRoot to construct the elements from DocumentPrintData.Pages into an HTML structure.
Send the post-operation DocumentViewerOperationEventArgs for DocumentViewerOperation.PrintPages and DocumentViewerOperationEventArgs.PageNumber as
0, indicating the end of the operation.
Call OpenBrowserPrint if PrintDocumentOptions.AutoOpenBrowserPrint is true.
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:
|Property||PrintPages Pre-Operation||PrintPages Post-Operation||GetPage Pre-Operation||GetPage Post-Operation|
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
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.
As of version 184.108.40.206, the Print API has been changed to reflect large internal changes that should allow users greater control over the printing process.
Prior to version
220.127.116.11, Print took two parameters:
iframe element OR
div element passed by the user to add the temp printing data to it. Must not be null.
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.
As of version 18.104.22.168, 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.