PrintDocumentAdapter

EXTRA_PRINT_PREVIEW

String EXTRA_PRINT_PREVIEW

Extra: mapped to a boolean value that is true if the current layout is for a print preview, false otherwise. This extra is provided in the Bundle argument of the onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle) callback.

Constant Value: "EXTRA_PRINT_PREVIEW"

PrintDocumentAdapter

PrintDocumentAdapter ()

onFinish

void onFinish ()

Called when printing finishes. You can use this callback to release resources acquired in onStart(). This method is invoked on the main thread.

onLayout

void onLayout (PrintAttributes oldAttributes, 
                PrintAttributes newAttributes, 
                CancellationSignal cancellationSignal, 
                PrintDocumentAdapter.LayoutResultCallback callback, 
                Bundle extras)

Called when the print attributes (page size, density, etc) changed giving you a chance to layout the content such that it matches the new constraints. This method is invoked on the main thread.

After you are done laying out, you must invoke: onLayoutFinished(PrintDocumentInfo, boolean) with the last argument true or false depending on whether the layout changed the content or not, respectively; or onLayoutFailed(CharSequence), if an error occurred; or onLayoutCancelled() if layout was cancelled in a response to a cancellation request via the passed in CancellationSignal. Note that you must call one of the methods of the given callback for this method to be considered complete which is you will not receive any calls to this adapter until the current layout operation is complete by invoking a method on the callback instance. The callback methods can be invoked from an arbitrary thread.

One of the arguments passed to this method is a CancellationSignal which is used to propagate requests from the system to your application for canceling the current layout operation. For example, a cancellation may be requested if the user changes a print option that may affect layout while you are performing a layout operation. In such a case the system will make an attempt to cancel the current layout as another one will have to be performed. Typically, you should register a cancellation callback in the cancellation signal. The cancellation callback will not be made on the main thread and can be registered as follows:

 cancellationSignal.setOnCancelListener(new OnCancelListener() {
     @Override
     public void onCancel() {
         // Cancel layout
     }
 });
 

Note: If the content is large and a layout will be performed, it is a good practice to schedule the work on a dedicated thread and register an observer in the provided CancellationSignal upon invocation of which you should stop the layout.

onStart

void onStart ()

Called when printing starts. You can use this callback to allocate resources. This method is invoked on the main thread.

onWrite

void onWrite (PageRange[] pages, 
                ParcelFileDescriptor destination, 
                CancellationSignal cancellationSignal, 
                PrintDocumentAdapter.WriteResultCallback callback)

Called when specific pages of the content should be written in the form of a PDF file to the given file descriptor. This method is invoked on the main thread.

After you are done writing, you should close the file descriptor and invoke onWriteFinished(PageRange[]), if writing completed successfully; or onWriteFailed(CharSequence), if an error occurred; or onWriteCancelled(), if writing was cancelled in a response to a cancellation request via the passed in CancellationSignal. Note that you must call one of the methods of the given callback for this method to be considered complete which is you will not receive any calls to this adapter until the current write operation is complete by invoking a method on the callback instance. The callback methods can be invoked from an arbitrary thread.

One of the arguments passed to this method is a CancellationSignal which is used to propagate requests from the system to your application for canceling the current write operation. For example, a cancellation may be requested if the user changes a print option that may affect layout while you are performing a write operation. In such a case the system will make an attempt to cancel the current write as a layout will have to be performed which then may be followed by a write. Typically, you should register a cancellation callback in the cancellation signal. The cancellation callback will not be made on the main thread and can be registered as follows:

 cancellationSignal.setOnCancelListener(new OnCancelListener() {
     @Override
     public void onCancel() {
         // Cancel write
     }
 });
 

Note: If the printed content is large, it is a good practice to schedule writing it on a dedicated thread and register an observer in the provided CancellationSignal upon invocation of which you should stop writing.