Loading core/java/android/print/PageRange.java +2 −3 Original line number Original line Diff line number Diff line Loading @@ -39,9 +39,8 @@ public final class PageRange implements Parcelable { * @param start The start page index (zero based and inclusive). * @param start The start page index (zero based and inclusive). * @param end The end 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 start is less than zero or end * @throws IllegalArgumentException If end is less than zero. * is less than zero or start greater than end. * @throws IllegalArgumentException If start greater than end. */ */ public PageRange(int start, int end) { public PageRange(int start, int end) { if (start < 0) { if (start < 0) { Loading core/java/android/print/PrintAttributes.java +33 −26 Original line number Original line Diff line number Diff line Loading @@ -30,7 +30,11 @@ import com.android.internal.R; import java.util.Map; 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 { public final class PrintAttributes implements Parcelable { /** Color mode: Monochrome color scheme, for example one color is used. */ /** Color mode: Monochrome color scheme, for example one color is used. */ Loading Loading @@ -277,7 +281,7 @@ public final class PrintAttributes implements Parcelable { * Unknown media size in portrait mode. * Unknown media size in portrait mode. * <p> * <p> * <strong>Note: </strong>This is for specifying orientation without media * <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> * </p> */ */ public static final MediaSize UNKNOWN_PORTRAIT = public static final MediaSize UNKNOWN_PORTRAIT = Loading @@ -288,7 +292,7 @@ public final class PrintAttributes implements Parcelable { * Unknown media size in landscape mode. * Unknown media size in landscape mode. * <p> * <p> * <strong>Note: </strong>This is for specifying orientation without media * <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> * </p> */ */ public static final MediaSize UNKNOWN_LANDSCAPE = public static final MediaSize UNKNOWN_LANDSCAPE = Loading Loading @@ -615,9 +619,7 @@ public final class PrintAttributes implements Parcelable { private final int mHeightMils; private final int mHeightMils; /** /** * Creates a new instance. This is the preferred constructor since * Creates a new instance. * it enables the media size label to be shown in a localized fashion * on a locale change. * * * @param id The unique media size id. * @param id The unique media size id. * @param packageName The name of the creating package. * @param packageName The name of the creating package. Loading @@ -625,10 +627,9 @@ public final class PrintAttributes implements Parcelable { * @param widthMils The width in mils (thousands of an inch). * @param widthMils The width in mils (thousands of an inch). * @param heightMils The height 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 id is empty or the label * @throws IllegalArgumentException If the label is empty. * is empty or the widthMils is less than or equal to zero or the * @throws IllegalArgumentException If the widthMils is less than or equal to zero. * heightMils is less than or equal to zero. * @throws IllegalArgumentException If the heightMils is less than or equal to zero. * * * @hide * @hide */ */ Loading Loading @@ -667,14 +668,13 @@ public final class PrintAttributes implements Parcelable { * * * @param id The unique media size id. It is unique amongst other media sizes * @param id The unique media size id. It is unique amongst other media sizes * supported by the printer. * 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 widthMils The width in mils (thousands of an inch). * @param heightMils The height 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 id is empty or the label is empty * @throws IllegalArgumentException If the label is empty. * or the widthMils is less than or equal to zero or the heightMils is less * @throws IllegalArgumentException If the widthMils is less than or equal to zero. * than or equal to zero. * @throws IllegalArgumentException If the heightMils is less than or equal to zero. */ */ public MediaSize(String id, String label, int widthMils, int heightMils) { public MediaSize(String id, String label, int widthMils, int heightMils) { if (TextUtils.isEmpty(id)) { if (TextUtils.isEmpty(id)) { Loading Loading @@ -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. * 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() { public MediaSize asPortrait() { if (isPortrait()) { return this; } return new MediaSize(mId, mLabel, mPackageName, return new MediaSize(mId, mLabel, mPackageName, Math.min(mWidthMils, mHeightMils), Math.min(mWidthMils, mHeightMils), Math.max(mWidthMils, mHeightMils), Math.max(mWidthMils, mHeightMils), Loading @@ -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. * 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() { public MediaSize asLandscape() { if (!isPortrait()) { return this; } return new MediaSize(mId, mLabel, mPackageName, return new MediaSize(mId, mLabel, mPackageName, Math.max(mWidthMils, mHeightMils), Math.max(mWidthMils, mHeightMils), Math.min(mWidthMils, mHeightMils), Math.min(mWidthMils, mHeightMils), Loading Loading @@ -881,7 +889,7 @@ public final class PrintAttributes implements Parcelable { * This class specifies a supported resolution in DPI (dots per inch). * This class specifies a supported resolution in DPI (dots per inch). * Resolution defines how many points with different color can be placed * Resolution defines how many points with different color can be placed * on one inch in horizontal or vertical direction of the target media. * 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. * the one with 300 DPI resolution. */ */ public static final class Resolution { public static final class Resolution { Loading @@ -895,14 +903,13 @@ public final class PrintAttributes implements Parcelable { * * * @param id The unique resolution id. It is unique amongst other resolutions * @param id The unique resolution id. It is unique amongst other resolutions * supported by the printer. * 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 horizontalDpi The horizontal resolution in DPI (dots per inch). * @param verticalDpi The vertical 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 id is empty or the label is empty * @throws IllegalArgumentException If the label is empty. * or the horizontalDpi is less than or equal to zero or the verticalDpi is * @throws IllegalArgumentException If the horizontalDpi is less than or equal to zero. * less than or equal to zero. * @throws IllegalArgumentException If the verticalDpi is less than or equal to zero. */ */ public Resolution(String id, String label, int horizontalDpi, int verticalDpi) { public Resolution(String id, String label, int horizontalDpi, int verticalDpi) { if (TextUtils.isEmpty(id)) { if (TextUtils.isEmpty(id)) { Loading core/java/android/print/PrintDocumentAdapter.java +66 −17 Original line number Original line Diff line number Diff line Loading @@ -38,15 +38,46 @@ import android.os.ParcelFileDescriptor; * </li> * </li> * <li> * <li> * After every call to {@link #onLayout(PrintAttributes, PrintAttributes, * After every call to {@link #onLayout(PrintAttributes, PrintAttributes, * CancellationSignal, LayoutResultCallback, Bundle)}, you may get a call to * CancellationSignal, LayoutResultCallback, Bundle)}, you <strong>may</strong> get * {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback)} * a call to {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, * asking you to write a PDF file with the content for specific pages. * WriteResultCallback)} asking you to write a PDF file with the content for * specific pages. * </li> * </li> * <li> * <li> * Finally, you will receive a call to {@link #onFinish()}. You can use this * Finally, you will receive a call to {@link #onFinish()}. You can use this * callback to release resources allocated in {@link #onStart()}. * callback to release resources allocated in {@link #onStart()}. * </li> * </li> * </ul> * </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> * </p> * <h3>Implementation</h3> * <h3>Implementation</h3> * <p> * <p> Loading @@ -54,7 +85,11 @@ import android.os.ParcelFileDescriptor; * of the work on an arbitrary thread. For example, if the printed content * 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 * 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 * 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> * <p> * <p> * You can also do work on different threads, for example if you print UI * You can also do work on different threads, for example if you print UI Loading @@ -64,7 +99,7 @@ import android.os.ParcelFileDescriptor; * This will ensure that the UI does not change while you are laying out the * 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, * printed content. Then you can handle {@link #onWrite(PageRange[], ParcelFileDescriptor, * CancellationSignal, WriteResultCallback)} and {@link #onFinish()} on another * 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 * time. Also this assumes that you will generate the printed content in * {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, * {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, * LayoutResultCallback, Bundle)} which is not mandatory. If you use multiple * LayoutResultCallback, Bundle)} which is not mandatory. If you use multiple Loading @@ -76,6 +111,12 @@ public abstract class PrintDocumentAdapter { /** /** * Extra: mapped to a boolean value that is <code>true</code> if * Extra: mapped to a boolean value that is <code>true</code> if * the current layout is for a print preview, <code>false</code> otherwise. * 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"; public static final String EXTRA_PRINT_PREVIEW = "EXTRA_PRINT_PREVIEW"; Loading @@ -95,17 +136,20 @@ public abstract class PrintDocumentAdapter { * After you are done laying out, you <strong>must</strong> invoke: {@link * After you are done laying out, you <strong>must</strong> invoke: {@link * LayoutResultCallback#onLayoutFinished(PrintDocumentInfo, boolean)} with * LayoutResultCallback#onLayoutFinished(PrintDocumentInfo, boolean)} with * the last argument <code>true</code> or <code>false</code> depending on * the last argument <code>true</code> or <code>false</code> depending on * whether the layout changed the content or not, respectively; and {@link * whether the layout changed the content or not, respectively; or {@link * LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred. * LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred; * Note that you must call one of the methods of the given callback. * 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> * <p> * <p> * <strong>Note:</strong> If the content is large and a layout will be * <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 * performed, it is a good practice to schedule the work on a dedicated * thread and register an observer in the provided {@link * thread and register an observer in the provided {@link * CancellationSignal} upon invocation of which you should stop the * CancellationSignal} upon invocation of which you should stop the * layout. The cancellation callback will not be made on the main * layout. The cancellation callback <strong>will not</strong> be made on * thread. * the main thread. * </p> * </p> * * * @param oldAttributes The old print attributes. * @param oldAttributes The old print attributes. Loading @@ -128,10 +172,12 @@ public abstract class PrintDocumentAdapter { * on the main thread. * on the main thread. *<p> *<p> * After you are done writing, you should close the file descriptor and * 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( * completed successfully; or {@link WriteResultCallback#onWriteFailed( * CharSequence)}, if an error occurred. Note that you must call one of * CharSequence)}, if an error occurred; or {@link WriteResultCallback#onWriteCancelled()}, * the methods of the given callback. * 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> * <p> * <p> * <strong>Note:</strong> If the printed content is large, it is a good * <strong>Note:</strong> If the printed content is large, it is a good Loading Loading @@ -178,7 +224,8 @@ public abstract class PrintDocumentAdapter { /** /** * Notifies that all the data was written. * 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) { public void onWriteFinished(PageRange[] pages) { /* do nothing - stub */ /* do nothing - stub */ Loading @@ -187,7 +234,8 @@ public abstract class PrintDocumentAdapter { /** /** * Notifies that an error occurred while writing the data. * 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) { public void onWriteFailed(CharSequence error) { /* do nothing - stub */ /* do nothing - stub */ Loading Loading @@ -218,7 +266,7 @@ public abstract class PrintDocumentAdapter { /** /** * Notifies that the layout finished and whether the content changed. * 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. * @param changed Whether the layout changed. * * * @see PrintDocumentInfo * @see PrintDocumentInfo Loading @@ -230,7 +278,8 @@ public abstract class PrintDocumentAdapter { /** /** * Notifies that an error occurred while laying out the document. * 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) { public void onLayoutFailed(CharSequence error) { /* do nothing - stub */ /* do nothing - stub */ Loading core/java/android/print/PrintDocumentInfo.java +68 −8 Original line number Original line Diff line number Diff line Loading @@ -21,12 +21,56 @@ import android.os.Parcelable; import android.text.TextUtils; 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 { public final class PrintDocumentInfo implements Parcelable { /** /** * Constant for unknown page count.. * Constant for unknown page count. */ */ public static final int PAGE_COUNT_UNKNOWN = -1; public static final int PAGE_COUNT_UNKNOWN = -1; Loading @@ -37,11 +81,23 @@ public final class PrintDocumentInfo implements Parcelable { /** /** * Content type: document. * 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; public static final int CONTENT_TYPE_DOCUMENT = 0; /** /** * Content type: photo. * 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; public static final int CONTENT_TYPE_PHOTO = 1; Loading Loading @@ -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. * @return The document name. */ */ Loading Loading @@ -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 { public static final class Builder { private final PrintDocumentInfo mPrototype; private final PrintDocumentInfo mPrototype; /** /** * Constructor. * Constructor. * * <p> * <p> * The values of the relevant properties are initialized with default * The values of the relevant properties are initialized with defaults. * values. Please refer to the documentation of the individual setters * Please refer to the documentation of the individual setters for * for information about the default values. * information about the default values. * </p> * </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) { public Builder(String name) { if (TextUtils.isEmpty(name)) { if (TextUtils.isEmpty(name)) { Loading core/java/android/print/PrintJob.java +9 −3 Original line number Original line Diff line number Diff line Loading @@ -17,8 +17,13 @@ package android.print; package android.print; /** /** * This class represents a print job from the perspective of * This class represents a print job from the perspective of an * an application. * 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 { public final class PrintJob { Loading Loading @@ -145,11 +150,12 @@ public final class PrintJob { /** /** * Gets whether this print job is failed. Such a print job is * Gets whether this print job is failed. Such a print job is * not successfully printed due to an error. You can request * 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. * @return Whether the print job is failed. * * * @see #restart() * @see #restart() * @see #cancel() */ */ public boolean isFailed() { public boolean isFailed() { return getInfo().getState() == PrintJobInfo.STATE_FAILED; return getInfo().getState() == PrintJobInfo.STATE_FAILED; Loading Loading
core/java/android/print/PageRange.java +2 −3 Original line number Original line Diff line number Diff line Loading @@ -39,9 +39,8 @@ public final class PageRange implements Parcelable { * @param start The start page index (zero based and inclusive). * @param start The start page index (zero based and inclusive). * @param end The end 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 start is less than zero or end * @throws IllegalArgumentException If end is less than zero. * is less than zero or start greater than end. * @throws IllegalArgumentException If start greater than end. */ */ public PageRange(int start, int end) { public PageRange(int start, int end) { if (start < 0) { if (start < 0) { Loading
core/java/android/print/PrintAttributes.java +33 −26 Original line number Original line Diff line number Diff line Loading @@ -30,7 +30,11 @@ import com.android.internal.R; import java.util.Map; 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 { public final class PrintAttributes implements Parcelable { /** Color mode: Monochrome color scheme, for example one color is used. */ /** Color mode: Monochrome color scheme, for example one color is used. */ Loading Loading @@ -277,7 +281,7 @@ public final class PrintAttributes implements Parcelable { * Unknown media size in portrait mode. * Unknown media size in portrait mode. * <p> * <p> * <strong>Note: </strong>This is for specifying orientation without media * <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> * </p> */ */ public static final MediaSize UNKNOWN_PORTRAIT = public static final MediaSize UNKNOWN_PORTRAIT = Loading @@ -288,7 +292,7 @@ public final class PrintAttributes implements Parcelable { * Unknown media size in landscape mode. * Unknown media size in landscape mode. * <p> * <p> * <strong>Note: </strong>This is for specifying orientation without media * <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> * </p> */ */ public static final MediaSize UNKNOWN_LANDSCAPE = public static final MediaSize UNKNOWN_LANDSCAPE = Loading Loading @@ -615,9 +619,7 @@ public final class PrintAttributes implements Parcelable { private final int mHeightMils; private final int mHeightMils; /** /** * Creates a new instance. This is the preferred constructor since * Creates a new instance. * it enables the media size label to be shown in a localized fashion * on a locale change. * * * @param id The unique media size id. * @param id The unique media size id. * @param packageName The name of the creating package. * @param packageName The name of the creating package. Loading @@ -625,10 +627,9 @@ public final class PrintAttributes implements Parcelable { * @param widthMils The width in mils (thousands of an inch). * @param widthMils The width in mils (thousands of an inch). * @param heightMils The height 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 id is empty or the label * @throws IllegalArgumentException If the label is empty. * is empty or the widthMils is less than or equal to zero or the * @throws IllegalArgumentException If the widthMils is less than or equal to zero. * heightMils is less than or equal to zero. * @throws IllegalArgumentException If the heightMils is less than or equal to zero. * * * @hide * @hide */ */ Loading Loading @@ -667,14 +668,13 @@ public final class PrintAttributes implements Parcelable { * * * @param id The unique media size id. It is unique amongst other media sizes * @param id The unique media size id. It is unique amongst other media sizes * supported by the printer. * 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 widthMils The width in mils (thousands of an inch). * @param heightMils The height 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 id is empty or the label is empty * @throws IllegalArgumentException If the label is empty. * or the widthMils is less than or equal to zero or the heightMils is less * @throws IllegalArgumentException If the widthMils is less than or equal to zero. * than or equal to zero. * @throws IllegalArgumentException If the heightMils is less than or equal to zero. */ */ public MediaSize(String id, String label, int widthMils, int heightMils) { public MediaSize(String id, String label, int widthMils, int heightMils) { if (TextUtils.isEmpty(id)) { if (TextUtils.isEmpty(id)) { Loading Loading @@ -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. * 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() { public MediaSize asPortrait() { if (isPortrait()) { return this; } return new MediaSize(mId, mLabel, mPackageName, return new MediaSize(mId, mLabel, mPackageName, Math.min(mWidthMils, mHeightMils), Math.min(mWidthMils, mHeightMils), Math.max(mWidthMils, mHeightMils), Math.max(mWidthMils, mHeightMils), Loading @@ -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. * 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() { public MediaSize asLandscape() { if (!isPortrait()) { return this; } return new MediaSize(mId, mLabel, mPackageName, return new MediaSize(mId, mLabel, mPackageName, Math.max(mWidthMils, mHeightMils), Math.max(mWidthMils, mHeightMils), Math.min(mWidthMils, mHeightMils), Math.min(mWidthMils, mHeightMils), Loading Loading @@ -881,7 +889,7 @@ public final class PrintAttributes implements Parcelable { * This class specifies a supported resolution in DPI (dots per inch). * This class specifies a supported resolution in DPI (dots per inch). * Resolution defines how many points with different color can be placed * Resolution defines how many points with different color can be placed * on one inch in horizontal or vertical direction of the target media. * 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. * the one with 300 DPI resolution. */ */ public static final class Resolution { public static final class Resolution { Loading @@ -895,14 +903,13 @@ public final class PrintAttributes implements Parcelable { * * * @param id The unique resolution id. It is unique amongst other resolutions * @param id The unique resolution id. It is unique amongst other resolutions * supported by the printer. * 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 horizontalDpi The horizontal resolution in DPI (dots per inch). * @param verticalDpi The vertical 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 id is empty or the label is empty * @throws IllegalArgumentException If the label is empty. * or the horizontalDpi is less than or equal to zero or the verticalDpi is * @throws IllegalArgumentException If the horizontalDpi is less than or equal to zero. * less than or equal to zero. * @throws IllegalArgumentException If the verticalDpi is less than or equal to zero. */ */ public Resolution(String id, String label, int horizontalDpi, int verticalDpi) { public Resolution(String id, String label, int horizontalDpi, int verticalDpi) { if (TextUtils.isEmpty(id)) { if (TextUtils.isEmpty(id)) { Loading
core/java/android/print/PrintDocumentAdapter.java +66 −17 Original line number Original line Diff line number Diff line Loading @@ -38,15 +38,46 @@ import android.os.ParcelFileDescriptor; * </li> * </li> * <li> * <li> * After every call to {@link #onLayout(PrintAttributes, PrintAttributes, * After every call to {@link #onLayout(PrintAttributes, PrintAttributes, * CancellationSignal, LayoutResultCallback, Bundle)}, you may get a call to * CancellationSignal, LayoutResultCallback, Bundle)}, you <strong>may</strong> get * {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback)} * a call to {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, * asking you to write a PDF file with the content for specific pages. * WriteResultCallback)} asking you to write a PDF file with the content for * specific pages. * </li> * </li> * <li> * <li> * Finally, you will receive a call to {@link #onFinish()}. You can use this * Finally, you will receive a call to {@link #onFinish()}. You can use this * callback to release resources allocated in {@link #onStart()}. * callback to release resources allocated in {@link #onStart()}. * </li> * </li> * </ul> * </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> * </p> * <h3>Implementation</h3> * <h3>Implementation</h3> * <p> * <p> Loading @@ -54,7 +85,11 @@ import android.os.ParcelFileDescriptor; * of the work on an arbitrary thread. For example, if the printed content * 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 * 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 * 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> * <p> * <p> * You can also do work on different threads, for example if you print UI * You can also do work on different threads, for example if you print UI Loading @@ -64,7 +99,7 @@ import android.os.ParcelFileDescriptor; * This will ensure that the UI does not change while you are laying out the * 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, * printed content. Then you can handle {@link #onWrite(PageRange[], ParcelFileDescriptor, * CancellationSignal, WriteResultCallback)} and {@link #onFinish()} on another * 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 * time. Also this assumes that you will generate the printed content in * {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, * {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, * LayoutResultCallback, Bundle)} which is not mandatory. If you use multiple * LayoutResultCallback, Bundle)} which is not mandatory. If you use multiple Loading @@ -76,6 +111,12 @@ public abstract class PrintDocumentAdapter { /** /** * Extra: mapped to a boolean value that is <code>true</code> if * Extra: mapped to a boolean value that is <code>true</code> if * the current layout is for a print preview, <code>false</code> otherwise. * 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"; public static final String EXTRA_PRINT_PREVIEW = "EXTRA_PRINT_PREVIEW"; Loading @@ -95,17 +136,20 @@ public abstract class PrintDocumentAdapter { * After you are done laying out, you <strong>must</strong> invoke: {@link * After you are done laying out, you <strong>must</strong> invoke: {@link * LayoutResultCallback#onLayoutFinished(PrintDocumentInfo, boolean)} with * LayoutResultCallback#onLayoutFinished(PrintDocumentInfo, boolean)} with * the last argument <code>true</code> or <code>false</code> depending on * the last argument <code>true</code> or <code>false</code> depending on * whether the layout changed the content or not, respectively; and {@link * whether the layout changed the content or not, respectively; or {@link * LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred. * LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred; * Note that you must call one of the methods of the given callback. * 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> * <p> * <p> * <strong>Note:</strong> If the content is large and a layout will be * <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 * performed, it is a good practice to schedule the work on a dedicated * thread and register an observer in the provided {@link * thread and register an observer in the provided {@link * CancellationSignal} upon invocation of which you should stop the * CancellationSignal} upon invocation of which you should stop the * layout. The cancellation callback will not be made on the main * layout. The cancellation callback <strong>will not</strong> be made on * thread. * the main thread. * </p> * </p> * * * @param oldAttributes The old print attributes. * @param oldAttributes The old print attributes. Loading @@ -128,10 +172,12 @@ public abstract class PrintDocumentAdapter { * on the main thread. * on the main thread. *<p> *<p> * After you are done writing, you should close the file descriptor and * 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( * completed successfully; or {@link WriteResultCallback#onWriteFailed( * CharSequence)}, if an error occurred. Note that you must call one of * CharSequence)}, if an error occurred; or {@link WriteResultCallback#onWriteCancelled()}, * the methods of the given callback. * 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> * <p> * <p> * <strong>Note:</strong> If the printed content is large, it is a good * <strong>Note:</strong> If the printed content is large, it is a good Loading Loading @@ -178,7 +224,8 @@ public abstract class PrintDocumentAdapter { /** /** * Notifies that all the data was written. * 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) { public void onWriteFinished(PageRange[] pages) { /* do nothing - stub */ /* do nothing - stub */ Loading @@ -187,7 +234,8 @@ public abstract class PrintDocumentAdapter { /** /** * Notifies that an error occurred while writing the data. * 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) { public void onWriteFailed(CharSequence error) { /* do nothing - stub */ /* do nothing - stub */ Loading Loading @@ -218,7 +266,7 @@ public abstract class PrintDocumentAdapter { /** /** * Notifies that the layout finished and whether the content changed. * 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. * @param changed Whether the layout changed. * * * @see PrintDocumentInfo * @see PrintDocumentInfo Loading @@ -230,7 +278,8 @@ public abstract class PrintDocumentAdapter { /** /** * Notifies that an error occurred while laying out the document. * 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) { public void onLayoutFailed(CharSequence error) { /* do nothing - stub */ /* do nothing - stub */ Loading
core/java/android/print/PrintDocumentInfo.java +68 −8 Original line number Original line Diff line number Diff line Loading @@ -21,12 +21,56 @@ import android.os.Parcelable; import android.text.TextUtils; 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 { public final class PrintDocumentInfo implements Parcelable { /** /** * Constant for unknown page count.. * Constant for unknown page count. */ */ public static final int PAGE_COUNT_UNKNOWN = -1; public static final int PAGE_COUNT_UNKNOWN = -1; Loading @@ -37,11 +81,23 @@ public final class PrintDocumentInfo implements Parcelable { /** /** * Content type: document. * 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; public static final int CONTENT_TYPE_DOCUMENT = 0; /** /** * Content type: photo. * 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; public static final int CONTENT_TYPE_PHOTO = 1; Loading Loading @@ -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. * @return The document name. */ */ Loading Loading @@ -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 { public static final class Builder { private final PrintDocumentInfo mPrototype; private final PrintDocumentInfo mPrototype; /** /** * Constructor. * Constructor. * * <p> * <p> * The values of the relevant properties are initialized with default * The values of the relevant properties are initialized with defaults. * values. Please refer to the documentation of the individual setters * Please refer to the documentation of the individual setters for * for information about the default values. * information about the default values. * </p> * </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) { public Builder(String name) { if (TextUtils.isEmpty(name)) { if (TextUtils.isEmpty(name)) { Loading
core/java/android/print/PrintJob.java +9 −3 Original line number Original line Diff line number Diff line Loading @@ -17,8 +17,13 @@ package android.print; package android.print; /** /** * This class represents a print job from the perspective of * This class represents a print job from the perspective of an * an application. * 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 { public final class PrintJob { Loading Loading @@ -145,11 +150,12 @@ public final class PrintJob { /** /** * Gets whether this print job is failed. Such a print job is * Gets whether this print job is failed. Such a print job is * not successfully printed due to an error. You can request * 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. * @return Whether the print job is failed. * * * @see #restart() * @see #restart() * @see #cancel() */ */ public boolean isFailed() { public boolean isFailed() { return getInfo().getState() == PrintJobInfo.STATE_FAILED; return getInfo().getState() == PrintJobInfo.STATE_FAILED; Loading
