Merge "Update the documentaton of the android.print package." into klp-dev (2a40da55) · Commits · e / os / android_frameworks_base

core/java/android/print/PageRange.java

+2 −3

Original line number	Diff line number	Diff line
		@@ -39,9 +39,8 @@ public final class PageRange implements Parcelable {
		* @param start The start page index (zero based and inclusive).
		* @param end The end page index (zero based and inclusive).
		*
		* @throws IllegalArgumentException If start is less than zero.
		* @throws IllegalArgumentException If end is less than zero.
		* @throws IllegalArgumentException If start greater than end.
		* @throws IllegalArgumentException If start is less than zero or end
		* is less than zero or start greater than end.
		*/
		public PageRange(int start, int end) {
		if (start < 0) {

core/java/android/print/PrintAttributes.java

+33 −26

Original line number	Diff line number	Diff line
		@@ -30,7 +30,11 @@ import com.android.internal.R;
		import java.util.Map;

		/**
		* This class represents the attributes of a print job.
		* This class represents the attributes of a print job. These attributes
		* describe how the printed content should be laid out. For example, the
		* print attributes may state that the content should be laid out on a
		* letter size with 300 DPI (dots per inch) resolution, have a margin of
		* 10 mills (thousand of an inch) on all sides, and be black and white.
		*/
		public final class PrintAttributes implements Parcelable {
		/** Color mode: Monochrome color scheme, for example one color is used. */
		@@ -277,7 +281,7 @@ public final class PrintAttributes implements Parcelable {
		* Unknown media size in portrait mode.
		* <p>
		* <strong>Note: </strong>This is for specifying orientation without media
		* size. You should not use the dimensions reported by this class.
		* size. You should not use the dimensions reported by this instance.
		* </p>
		*/
		public static final MediaSize UNKNOWN_PORTRAIT =
		@@ -288,7 +292,7 @@ public final class PrintAttributes implements Parcelable {
		* Unknown media size in landscape mode.
		* <p>
		* <strong>Note: </strong>This is for specifying orientation without media
		* size. You should not use the dimensions reported by this class.
		* size. You should not use the dimensions reported by this instance.
		* </p>
		*/
		public static final MediaSize UNKNOWN_LANDSCAPE =
		@@ -615,9 +619,7 @@ public final class PrintAttributes implements Parcelable {
		private final int mHeightMils;

		/**
		* Creates a new instance. This is the preferred constructor since
		* it enables the media size label to be shown in a localized fashion
		* on a locale change.
		* Creates a new instance.
		*
		* @param id The unique media size id.
		* @param packageName The name of the creating package.
		@@ -625,10 +627,9 @@ public final class PrintAttributes implements Parcelable {
		* @param widthMils The width in mils (thousands of an inch).
		* @param heightMils The height in mils (thousands of an inch).
		*
		* @throws IllegalArgumentException If the id is empty.
		* @throws IllegalArgumentException If the label is empty.
		* @throws IllegalArgumentException If the widthMils is less than or equal to zero.
		* @throws IllegalArgumentException If the heightMils is less than or equal to zero.
		* @throws IllegalArgumentException If the id is empty or the label
		* is empty or the widthMils is less than or equal to zero or the
		* heightMils is less than or equal to zero.
		*
		* @hide
		*/
		@@ -667,14 +668,13 @@ public final class PrintAttributes implements Parcelable {
		*
		* @param id The unique media size id. It is unique amongst other media sizes
		* supported by the printer.
		* @param label The <strong>internationalized</strong> human readable label.
		* @param label The <strong>localized</strong> human readable label.
		* @param widthMils The width in mils (thousands of an inch).
		* @param heightMils The height in mils (thousands of an inch).
		*
		* @throws IllegalArgumentException If the id is empty.
		* @throws IllegalArgumentException If the label is empty.
		* @throws IllegalArgumentException If the widthMils is less than or equal to zero.
		* @throws IllegalArgumentException If the heightMils is less than or equal to zero.
		* @throws IllegalArgumentException If the id is empty or the label is empty
		* or the widthMils is less than or equal to zero or the heightMils is less
		* than or equal to zero.
		*/
		public MediaSize(String id, String label, int widthMils, int heightMils) {
		if (TextUtils.isEmpty(id)) {
		@@ -776,12 +776,16 @@ public final class PrintAttributes implements Parcelable {
		}

		/**
		* Returns a new media size in a portrait orientation
		* Returns a new media size instance in a portrait orientation,
		* which is the height is the greater dimension.
		*
		* @return New instance in landscape orientation.
		* @return New instance in landscape orientation if this one
		* is in landscape, otherwise this instance.
		*/
		public MediaSize asPortrait() {
		if (isPortrait()) {
		return this;
		}
		return new MediaSize(mId, mLabel, mPackageName,
		Math.min(mWidthMils, mHeightMils),
		Math.max(mWidthMils, mHeightMils),
		@@ -789,12 +793,16 @@ public final class PrintAttributes implements Parcelable {
		}

		/**
		* Returns a new media size in a landscape orientation
		* Returns a new media size instance in a landscape orientation,
		* which is the height is the lesser dimension.
		*
		* @return New instance in landscape orientation.
		* @return New instance in landscape orientation if this one
		* is in portrait, otherwise this instance.
		*/
		public MediaSize asLandscape() {
		if (!isPortrait()) {
		return this;
		}
		return new MediaSize(mId, mLabel, mPackageName,
		Math.max(mWidthMils, mHeightMils),
		Math.min(mWidthMils, mHeightMils),
		@@ -881,7 +889,7 @@ public final class PrintAttributes implements Parcelable {
		* This class specifies a supported resolution in DPI (dots per inch).
		* Resolution defines how many points with different color can be placed
		* on one inch in horizontal or vertical direction of the target media.
		* For example, a printer with 600DIP can produce higher quality images
		* For example, a printer with 600 DPI can produce higher quality images
		* the one with 300 DPI resolution.
		*/
		public static final class Resolution {
		@@ -895,14 +903,13 @@ public final class PrintAttributes implements Parcelable {
		*
		* @param id The unique resolution id. It is unique amongst other resolutions
		* supported by the printer.
		* @param label The <strong>internationalized</strong> human readable label.
		* @param label The <strong>localized</strong> human readable label.
		* @param horizontalDpi The horizontal resolution in DPI (dots per inch).
		* @param verticalDpi The vertical resolution in DPI (dots per inch).
		*
		* @throws IllegalArgumentException If the id is empty.
		* @throws IllegalArgumentException If the label is empty.
		* @throws IllegalArgumentException If the horizontalDpi is less than or equal to zero.
		* @throws IllegalArgumentException If the verticalDpi is less than or equal to zero.
		* @throws IllegalArgumentException If the id is empty or the label is empty
		* or the horizontalDpi is less than or equal to zero or the verticalDpi is
		* less than or equal to zero.
		*/
		public Resolution(String id, String label, int horizontalDpi, int verticalDpi) {
		if (TextUtils.isEmpty(id)) {

core/java/android/print/PrintDocumentAdapter.java

+66 −17

Original line number	Diff line number	Diff line
		@@ -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,20 @@ 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.
		* </p>
		* <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. The cancellation callback <strong>will not</strong> be made on
		* the main thread.
		* </p>
		*
		* @param oldAttributes The old print attributes.
		@@ -128,10 +172,12 @@ 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.
		* </p>
		* <p>
		* <strong>Note:</strong> If the printed content is large, it is a good
		@@ -178,7 +224,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 +234,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 +266,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 +278,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 */

core/java/android/print/PrintDocumentInfo.java

+68 −8

Original line number	Diff line number	Diff line
		@@ -21,12 +21,56 @@ import android.os.Parcelable;
		import android.text.TextUtils;

		/**
		* This class encapsulates information about a printed document.
		* This class encapsulates information about a document for printing
		* purposes. This meta-data is used by the platform and print services,
		* components that interact with printers. For example, this class
		* contains the number of pages contained in the document it describes and
		* this number of pages is shown to the user allowing him/her to select
		* the range to print. Also a print service may optimize the printing
		* process based on the content type, such as document or photo.
		* <p>
		* Instances of this class are created by the printing application and
		* passed to the {@link PrintDocumentAdapter.LayoutResultCallback#onLayoutFinished(
		* PrintDocumentInfo, boolean) PrintDocumentAdapter.LayoutResultCallback.onLayoutFinished(
		* PrintDocumentInfo, boolean)} callback after successfully laying out the
		* content which is performed in {@link PrintDocumentAdapter#onLayout(PrintAttributes,
		* PrintAttributes, android.os.CancellationSignal, PrintDocumentAdapter.LayoutResultCallback,
		* android.os.Bundle) PrintDocumentAdapter.onLayout(PrintAttributes,
		* PrintAttributes, android.os.CancellationSignal,
		* PrintDocumentAdapter.LayoutResultCallback, android.os.Bundle)}.
		* </p>
		* <p>
		* An example usage looks like this:
		* <pre>
		*
		* . . .
		*
		* public void onLayout(PrintAttributes oldAttributes, PrintAttributes newAttributes,
		* CancellationSignal cancellationSignal, LayoutResultCallback callback,
		* Bundle metadata) {
		*
		* // Assume the app defined a LayoutResult class which contains
		* // the layout result data and that the content is a document.
		* LayoutResult result = doSomeLayoutWork();
		*
		* PrintDocumentInfo info = new PrintDocumentInfo
		* .Builder("printed_file.pdf")
		* .setContentType(PrintDocumentInfo.CONTENT_TYPE_DOCUMENT)
		* .setPageCount(result.getPageCount())
		* .build();
		*
		* callback.onLayoutFinished(info, result.getContentChanged());
		* }
		*
		* . . .
		*
		* </pre>
		* </p>
		*/
		public final class PrintDocumentInfo implements Parcelable {

		/**
		* Constant for unknown page count..
		* Constant for unknown page count.
		*/
		public static final int PAGE_COUNT_UNKNOWN = -1;

		@@ -37,11 +81,23 @@ public final class PrintDocumentInfo implements Parcelable {

		/**
		* Content type: document.
		* <p>
		* A print service may use normal paper to print the content instead
		* of dedicated photo paper. Also it may use a lower quality printing
		* process as the content is not as sensitive to print quality variation
		* as a photo is.
		* </p>
		*/
		public static final int CONTENT_TYPE_DOCUMENT = 0;

		/**
		* Content type: photo.
		* <p>
		* A print service may use dedicated photo paper to print the content
		* instead of normal paper. Also it may use a higher quality printing
		* process as the content is more sensitive to print quality variation
		* than a document.
		* </p>
		*/
		public static final int CONTENT_TYPE_PHOTO = 1;

		@@ -82,7 +138,8 @@ public final class PrintDocumentInfo implements Parcelable {
		}

		/**
		* Gets the document name.
		* Gets the document name. This name may be shown to
		* the user.
		*
		* @return The document name.
		*/
		@@ -213,20 +270,23 @@ public final class PrintDocumentInfo implements Parcelable {
		}

		/**
		* Builder for creating an {@link PrintDocumentInfo}.
		* Builder for creating a {@link PrintDocumentInfo}.
		*/
		public static final class Builder {
		private final PrintDocumentInfo mPrototype;

		/**
		* Constructor.
		*
		* <p>
		* The values of the relevant properties are initialized with default
		* values. Please refer to the documentation of the individual setters
		* for information about the default values.
		* The values of the relevant properties are initialized with defaults.
		* Please refer to the documentation of the individual setters for
		* information about the default values.
		* </p>
		*
		* @param name The document name. Cannot be empty.
		* @param name The document name which may be shown to the user and
		* is the file name if the content it describes is saved as a PDF.
		* Cannot be empty.
		*/
		public Builder(String name) {
		if (TextUtils.isEmpty(name)) {

core/java/android/print/PrintJob.java

+9 −3

Original line number	Diff line number	Diff line
		@@ -17,8 +17,13 @@
		package android.print;

		/**
		* This class represents a print job from the perspective of
		* an application.
		* This class represents a print job from the perspective of an
		* application. It contains behavior methods for performing operations
		* on it as well as methods for querying its state. A snapshot of the
		* print job state is represented by the {@link PrintJobInfo} class.
		* The state of a print job may change over time. An application receives
		* instances of this class when creating a print job or querying for
		* its print jobs.
		*/
		public final class PrintJob {

		@@ -145,11 +150,12 @@ public final class PrintJob {
		/**
		* Gets whether this print job is failed. Such a print job is
		* not successfully printed due to an error. You can request
		* a restart via {@link #restart()}.
		* a restart via {@link #restart()} or cancel via {@link #cancel()}.
		*
		* @return Whether the print job is failed.
		*
		* @see #restart()
		* @see #cancel()
		*/
		public boolean isFailed() {
		return getInfo().getState() == PrintJobInfo.STATE_FAILED;