diff options
Diffstat (limited to 'core/java/android/print/PrintDocumentAdapter.java')
| -rw-r--r-- | core/java/android/print/PrintDocumentAdapter.java | 130 |
1 files changed, 111 insertions, 19 deletions
diff --git a/core/java/android/print/PrintDocumentAdapter.java b/core/java/android/print/PrintDocumentAdapter.java index 4113ac737c1a..1f59bef853a3 100644 --- a/core/java/android/print/PrintDocumentAdapter.java +++ b/core/java/android/print/PrintDocumentAdapter.java @@ -38,15 +38,46 @@ import android.os.ParcelFileDescriptor; * </li> * <li> * After every call to {@link #onLayout(PrintAttributes, PrintAttributes, - * CancellationSignal, LayoutResultCallback, Bundle)}, you may get a call to - * {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback)} - * asking you to write a PDF file with the content for specific pages. + * CancellationSignal, LayoutResultCallback, Bundle)}, you <strong>may</strong> get + * a call to {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, + * WriteResultCallback)} asking you to write a PDF file with the content for + * specific pages. * </li> * <li> * Finally, you will receive a call to {@link #onFinish()}. You can use this * callback to release resources allocated in {@link #onStart()}. * </li> * </ul> + * <p> + * The {@link #onStart()} callback is always the first call you will receive and + * is useful for doing one time setup or resource allocation before printing. You + * will not receive a subsequent call here. + * </p> + * <p> + * The {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, + * LayoutResultCallback, Bundle)} callback requires that you layout the content + * based on the current {@link PrintAttributes}. The execution of this method is + * not considered completed until you invoke one of the methods on the passed in + * callback instance. Hence, you will not receive a subsequent call to any other + * method of this class until the execution of this method is complete by invoking + * one of the callback methods. + * </p> + * <p> + * The {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, + * WriteResultCallback)} requires that you render and write the content of some + * pages to the provided destination. The execution of this method is not + * considered complete until you invoke one of the methods on the passed in + * callback instance. Hence, you will not receive a subsequent call to any other + * method of this class until the execution of this method is complete by invoking + * one of the callback methods. You will never receive a sequence of one or more + * calls to this method without a previous call to {@link #onLayout(PrintAttributes, + * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)}. + * </p> + * <p> + * The {@link #onFinish()} callback is always the last call you will receive and + * is useful for doing one time cleanup or resource deallocation after printing. + * You will not receive a subsequent call here. + * </p> * </p> * <h3>Implementation</h3> * <p> @@ -54,7 +85,11 @@ import android.os.ParcelFileDescriptor; * of the work on an arbitrary thread. For example, if the printed content * does not depend on the UI state, i.e. on what is shown on the screen, then * you can offload the entire work on a dedicated thread, thus making your - * application interactive while the print work is being performed. + * application interactive while the print work is being performed. Note that + * while your activity is covered by the system print UI and a user cannot + * interact with it, doing the printing work on the main application thread + * may affect the performance of your other application components as they + * are also executed on that thread. * </p> * <p> * You can also do work on different threads, for example if you print UI @@ -64,7 +99,7 @@ import android.os.ParcelFileDescriptor; * This will ensure that the UI does not change while you are laying out the * printed content. Then you can handle {@link #onWrite(PageRange[], ParcelFileDescriptor, * CancellationSignal, WriteResultCallback)} and {@link #onFinish()} on another - * thread. This will ensure that the UI is frozen for the minimal amount of + * thread. This will ensure that the main thread is busy for a minimal amount of * time. Also this assumes that you will generate the printed content in * {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, * LayoutResultCallback, Bundle)} which is not mandatory. If you use multiple @@ -76,6 +111,12 @@ public abstract class PrintDocumentAdapter { /** * Extra: mapped to a boolean value that is <code>true</code> if * the current layout is for a print preview, <code>false</code> otherwise. + * This extra is provided in the {@link Bundle} argument of the {@link + * #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, + * LayoutResultCallback, Bundle)} callback. + * + * @see #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, + * LayoutResultCallback, Bundle) */ public static final String EXTRA_PRINT_PREVIEW = "EXTRA_PRINT_PREVIEW"; @@ -95,17 +136,41 @@ public abstract class PrintDocumentAdapter { * After you are done laying out, you <strong>must</strong> invoke: {@link * LayoutResultCallback#onLayoutFinished(PrintDocumentInfo, boolean)} with * the last argument <code>true</code> or <code>false</code> depending on - * whether the layout changed the content or not, respectively; and {@link - * LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred. - * Note that you must call one of the methods of the given callback. + * whether the layout changed the content or not, respectively; or {@link + * LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred; + * or {@link LayoutResultCallback#onLayoutCancelled()} if layout was + * cancelled in a response to a cancellation request via the passed in + * {@link CancellationSignal}. Note that you <strong>must</strong> 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. + * </p> + * <p> + * One of the arguments passed to this method is a {@link 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 <strong>will not</strong> be made on the + * main thread and can be registered as follows: * </p> + * <pre> + * cancellationSignal.setOnCancelListener(new OnCancelListener() { + * @Override + * public void onCancel() { + * // Cancel layout + * } + * }); + * </pre> * <p> * <strong>Note:</strong> 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 {@link * CancellationSignal} upon invocation of which you should stop the - * layout. The cancellation callback will not be made on the main - * thread. + * layout. * </p> * * @param oldAttributes The old print attributes. @@ -128,17 +193,41 @@ public abstract class PrintDocumentAdapter { * on the main thread. *<p> * After you are done writing, you should close the file descriptor and - * invoke {@link WriteResultCallback #onWriteFinished(PageRange[]), if writing + * invoke {@link WriteResultCallback#onWriteFinished(PageRange[])}, if writing * completed successfully; or {@link WriteResultCallback#onWriteFailed( - * CharSequence)}, if an error occurred. Note that you must call one of - * the methods of the given callback. + * CharSequence)}, if an error occurred; or {@link WriteResultCallback#onWriteCancelled()}, + * if writing was cancelled in a response to a cancellation request via the passed + * in {@link CancellationSignal}. Note that you <strong>must</strong> 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. + * </p> + * <p> + * One of the arguments passed to this method is a {@link 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 + * <strong>will not</strong> be made on the main thread and can be registered + * as follows: * </p> + * <pre> + * cancellationSignal.setOnCancelListener(new OnCancelListener() { + * @Override + * public void onCancel() { + * // Cancel write + * } + * }); + * </pre> * <p> * <strong>Note:</strong> 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 {@link CancellationSignal} upon invocation of - * which you should stop writing. The cancellation callback will not be - * made on the main thread. + * which you should stop writing. * </p> * * @param pages The pages whose content to print - non-overlapping in ascending order. @@ -178,7 +267,8 @@ public abstract class PrintDocumentAdapter { /** * Notifies that all the data was written. * - * @param pages The pages that were written. Cannot be null or empty. + * @param pages The pages that were written. Cannot be <code>null</code> + * or empty. */ public void onWriteFinished(PageRange[] pages) { /* do nothing - stub */ @@ -187,7 +277,8 @@ public abstract class PrintDocumentAdapter { /** * Notifies that an error occurred while writing the data. * - * @param error Error message. May be null if error is unknown. + * @param error The <strong>localized</strong> error message. + * shown to the user. May be <code>null</code> if error is unknown. */ public void onWriteFailed(CharSequence error) { /* do nothing - stub */ @@ -218,7 +309,7 @@ public abstract class PrintDocumentAdapter { /** * Notifies that the layout finished and whether the content changed. * - * @param info An info object describing the document. Cannot be null. + * @param info An info object describing the document. Cannot be <code>null</code>. * @param changed Whether the layout changed. * * @see PrintDocumentInfo @@ -230,7 +321,8 @@ public abstract class PrintDocumentAdapter { /** * Notifies that an error occurred while laying out the document. * - * @param error Error message. May be null if error is unknown. + * @param error The <strong>localized</strong> error message. + * shown to the user. May be <code>null</code> if error is unknown. */ public void onLayoutFailed(CharSequence error) { /* do nothing - stub */ |