diff options
Diffstat (limited to 'core/java/android/print')
| -rw-r--r-- | core/java/android/print/FileDocumentAdapter.java | 4 | ||||
| -rw-r--r-- | core/java/android/print/IPrintDocumentAdapter.aidl | 3 | ||||
| -rw-r--r-- | core/java/android/print/PrintDocumentAdapter.java | 58 | ||||
| -rw-r--r-- | core/java/android/print/PrintManager.java | 9 | ||||
| -rw-r--r-- | core/java/android/print/pdf/PdfDocument.java | 2 |
5 files changed, 57 insertions, 19 deletions
diff --git a/core/java/android/print/FileDocumentAdapter.java b/core/java/android/print/FileDocumentAdapter.java index 2871d45..c7011f4 100644 --- a/core/java/android/print/FileDocumentAdapter.java +++ b/core/java/android/print/FileDocumentAdapter.java @@ -18,6 +18,7 @@ package android.print; import android.content.Context; import android.os.AsyncTask; +import android.os.Bundle; import android.os.CancellationSignal; import android.os.CancellationSignal.OnCancelListener; import android.util.Log; @@ -59,7 +60,8 @@ final class FileDocumentAdapter extends PrintDocumentAdapter { @Override public void onLayout(PrintAttributes oldAttributes, PrintAttributes newAttributes, - CancellationSignal cancellationSignal, LayoutResultCallback callback) { + CancellationSignal cancellationSignal, LayoutResultCallback callback, + Bundle metadata) { // TODO: When we have a PDF rendering library we should query the page count. PrintDocumentInfo info = new PrintDocumentInfo.Builder() .setPageCount(PrintDocumentInfo.PAGE_COUNT_UNKNOWN).create(); diff --git a/core/java/android/print/IPrintDocumentAdapter.aidl b/core/java/android/print/IPrintDocumentAdapter.aidl index 36938e3..04da157 100644 --- a/core/java/android/print/IPrintDocumentAdapter.aidl +++ b/core/java/android/print/IPrintDocumentAdapter.aidl @@ -16,6 +16,7 @@ package android.print; +import android.os.Bundle; import android.os.ParcelFileDescriptor; import android.print.ILayoutResultCallback; import android.print.IWriteResultCallback; @@ -30,7 +31,7 @@ import android.print.PrintAttributes; oneway interface IPrintDocumentAdapter { void start(); void layout(in PrintAttributes oldAttributes, in PrintAttributes newAttributes, - ILayoutResultCallback callback); + ILayoutResultCallback callback, in Bundle metadata); void write(in List<PageRange> pages, in ParcelFileDescriptor fd, IWriteResultCallback callback); void finish(); diff --git a/core/java/android/print/PrintDocumentAdapter.java b/core/java/android/print/PrintDocumentAdapter.java index ef69400..1f83a45 100644 --- a/core/java/android/print/PrintDocumentAdapter.java +++ b/core/java/android/print/PrintDocumentAdapter.java @@ -16,6 +16,7 @@ package android.print; +import android.os.Bundle; import android.os.CancellationSignal; import java.io.FileDescriptor; @@ -33,14 +34,14 @@ import java.util.List; * </li> * <li> * Next, you will get one or more calls to {@link #onLayout(PrintAttributes, - * PrintAttributes, CancellationSignal, LayoutResultCallback)} to inform you - * that the print attributes (page size, density, etc) changed giving you an - * opportunity to layout the content to match the new constraints. + * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)} to + * inform you that the print attributes (page size, density, etc) changed + * giving you an opportunity to layout the content to match the new constraints. * </li> * <li> * After every call to {@link #onLayout(PrintAttributes, PrintAttributes, - * CancellationSignal, LayoutResultCallback)}, you may get a call to {@link - * #onWrite(List, FileDescriptor, CancellationSignal, WriteResultCallback)} + * CancellationSignal, LayoutResultCallback, Bundle)}, you may get a call to + * {@link #onWrite(List, FileDescriptor, CancellationSignal, WriteResultCallback)} * asking you to write a PDF file with the content for specific pages. * </li> * <li> @@ -49,10 +50,38 @@ import java.util.List; * </li> * </ul> * </p> + * <h3>Implementation</h3> + * <p> + * The APIs defined in this class are designed to enable doing part or all + * 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 off load the entire work on a dedicated thread, thus making your + * application interactive while the print work is being performed. + * </p> + * <p> + * You can also do work on different threads, for example if you print UI + * content, you can handle {@link #onStart()} and {@link #onLayout(PrintAttributes, + * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)} on + * the UI thread (assuming onStart initializes resources needed for layout). + * This will ensure that the UI does not change while you are laying out the + * printed content. Then you can handle {@link #onWrite(List, FileDescriptor, + * CancellationSignal, WriteResultCallback)} and {@link #onFinish()} on another + * thread. This will ensure that the UI is frozen for the 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 + * threads, you are responsible for proper synchronization. + * </p> */ public abstract class PrintDocumentAdapter { /** + * Meta-data key: mapped to a boolean value that is <code>true</code> if + * the current layout is for a print preview, <code>false</code> otherwise. + */ + public static final String METADATA_KEY_PRINT_PREVIEW = "KEY_METADATA_PRINT_PREVIEW"; + + /** * Called when printing starts. You can use this callback to allocate * resources. This method is invoked on the main thread. */ @@ -65,11 +94,11 @@ public abstract class PrintDocumentAdapter { * giving you a chance to layout the content such that it matches the * new constraints. This method is invoked on the main thread. * <p> - * After you are done laying out, you must 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. + * 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. * </p> * <p> * <strong>Note:</strong> If the content is large and a layout will be @@ -84,12 +113,15 @@ public abstract class PrintDocumentAdapter { * @param newAttributes The new print attributes. * @param cancellationSignal Signal for observing cancel layout requests. * @param callback Callback to inform the system for the layout result. + * @param metadata Additional information about how layout the content. * * @see LayoutResultCallback * @see CancellationSignal + * @see #METADATA_KEY_PRINT_PREVIEW */ public abstract void onLayout(PrintAttributes oldAttributes, PrintAttributes newAttributes, - CancellationSignal cancellationSignal, LayoutResultCallback callback); + CancellationSignal cancellationSignal, LayoutResultCallback callback, + Bundle metadata); /** * Called when specific pages of the content should be written in the @@ -98,7 +130,7 @@ public abstract class PrintDocumentAdapter { *<p> * After you are done writing, you should <strong>not</strong> close the * file descriptor, rather you must invoke: {@link WriteResultCallback - * #onWriteFinished()}, if writing completed successfully; or {@link + * #onWriteFinished(List)}, if writing completed successfully; or {@link * WriteResultCallback#onWriteFailed(CharSequence)}, if an error occurred. * </p> * <p> @@ -165,7 +197,7 @@ public abstract class PrintDocumentAdapter { /** * Base class for implementing a callback for the result of {@link * PrintDocumentAdapter#onLayout(PrintAttributes, PrintAttributes, - * CancellationSignal, LayoutResultCallback)}. + * CancellationSignal, LayoutResultCallback, Bundle)}. */ public static abstract class LayoutResultCallback { diff --git a/core/java/android/print/PrintManager.java b/core/java/android/print/PrintManager.java index 5ca19d4..58f45fa 100644 --- a/core/java/android/print/PrintManager.java +++ b/core/java/android/print/PrintManager.java @@ -19,6 +19,7 @@ package android.print; import android.content.Context; import android.content.IntentSender; import android.content.IntentSender.SendIntentException; +import android.os.Bundle; import android.os.CancellationSignal; import android.os.Handler; import android.os.ICancellationSignal; @@ -233,12 +234,13 @@ public final class PrintManager { } @Override - public void layout(PrintAttributes oldAttributes, - PrintAttributes newAttributes, ILayoutResultCallback callback) { + public void layout(PrintAttributes oldAttributes, PrintAttributes newAttributes, + ILayoutResultCallback callback, Bundle metadata) { SomeArgs args = SomeArgs.obtain(); args.arg1 = oldAttributes; args.arg2 = newAttributes; args.arg3 = callback; + args.arg4 = metadata; mHandler.obtainMessage(MyHandler.MSG_LAYOUT, args).sendToTarget(); } @@ -292,6 +294,7 @@ public final class PrintManager { PrintAttributes oldAttributes = (PrintAttributes) args.arg1; PrintAttributes newAttributes = (PrintAttributes) args.arg2; ILayoutResultCallback callback = (ILayoutResultCallback) args.arg3; + Bundle metadata = (Bundle) args.arg4; args.recycle(); try { @@ -300,7 +303,7 @@ public final class PrintManager { mDocumentAdapter.onLayout(oldAttributes, newAttributes, CancellationSignal.fromTransport(remoteSignal), - new LayoutResultCallbackWrapper(callback)); + new LayoutResultCallbackWrapper(callback), metadata); } catch (RemoteException re) { Log.e(LOG_TAG, "Error printing", re); } diff --git a/core/java/android/print/pdf/PdfDocument.java b/core/java/android/print/pdf/PdfDocument.java index 7ce036d..cfeb975 100644 --- a/core/java/android/print/pdf/PdfDocument.java +++ b/core/java/android/print/pdf/PdfDocument.java @@ -56,7 +56,7 @@ import java.util.List; * // finish the page * document.finishPage(page); * . . . - * add more pages + * // add more pages * . . . * // write the document content * document.writeTo(getOutputStream()); |