Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 6283608e authored by Svetoslav's avatar Svetoslav
Browse files

Tweak the print APIs. 

1. Adding bundle with metadata to PrintDocumentAdapter#onLayout
   with one key for now to specify whether this is for a preview.

2. Cleaned up docs.

Change-Id: I89380781bf3ae41aa89f8a0347d74516a210394c
parent 17b7f6e6

api/current.txt

+2 −1
Original line number Diff line number Diff line
@@ -18562,9 +18562,10 @@ package android.print { 
  public abstract class PrintDocumentAdapter {

    ctor public PrintDocumentAdapter();

    method public void onFinish();

    method public abstract void onLayout(android.print.PrintAttributes, android.print.PrintAttributes, android.os.CancellationSignal, android.print.PrintDocumentAdapter.LayoutResultCallback);

    method public abstract void onLayout(android.print.PrintAttributes, android.print.PrintAttributes, android.os.CancellationSignal, android.print.PrintDocumentAdapter.LayoutResultCallback, android.os.Bundle);

    method public void onStart();

    method public abstract void onWrite(java.util.List<android.print.PageRange>, java.io.FileDescriptor, android.os.CancellationSignal, android.print.PrintDocumentAdapter.WriteResultCallback);

    field public static final java.lang.String METADATA_KEY_PRINT_PREVIEW = "KEY_METADATA_PRINT_PREVIEW";

  }















  public static abstract class PrintDocumentAdapter.LayoutResultCallback {

























core/java/android/print/FileDocumentAdapter.java



+3
−1




























Original line number
Diff line number
Diff line








@@ -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();

































core/java/android/print/IPrintDocumentAdapter.aidl



+2
−1




























Original line number
Diff line number
Diff line








@@ -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();

































core/java/android/print/PrintDocumentAdapter.java



+45
−13




























Original line number
Diff line number
Diff line








@@ -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,9 +50,37 @@ 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 {

















































core/java/android/print/PrintManager.java



+6
−3




























Original line number
Diff line number
Diff line








@@ -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);















                        }