Merge "Tweak the print APIs." (dc990e7c) · Commits · e / os / android_frameworks_base

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