From 4d4c66dd38e940082e385b49a33f4022ab04c738 Mon Sep 17 00:00:00 2001 From: Svetoslav Ganov Date: Thu, 24 Oct 2013 18:04:39 -0700 Subject: Update the documentaton of the android.print package. bug:10551786 bug:10551697 bug:10705082 bug:10741641 bug:11318976 bug:10550979 bug:10551761 Change-Id: I46ceb66a69b6d32d6b417356178f67f2e25e891a --- core/java/android/print/PrintAttributes.java | 59 ++++++++++++++++------------ 1 file changed, 33 insertions(+), 26 deletions(-) (limited to 'core/java/android/print/PrintAttributes.java') diff --git a/core/java/android/print/PrintAttributes.java b/core/java/android/print/PrintAttributes.java index e1a9cb7..c6254e0 100644 --- a/core/java/android/print/PrintAttributes.java +++ b/core/java/android/print/PrintAttributes.java @@ -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. *

* Note: 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. *

*/ public static final MediaSize UNKNOWN_PORTRAIT = @@ -288,7 +292,7 @@ public final class PrintAttributes implements Parcelable { * Unknown media size in landscape mode. *

* Note: 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. *

*/ 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 internationalized human readable label. + * @param label The localized 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,8 +889,8 @@ 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 - * the one with 300DPI resolution. + * For example, a printer with 600 DPI can produce higher quality images + * the one with 300 DPI resolution. */ public static final class Resolution { private final String mId; @@ -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 internationalized human readable label. + * @param label The localized 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)) { -- cgit v1.1