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

Commit de41eeaa authored by Seigo Nonaka's avatar Seigo Nonaka
Browse files

Address API review from the council 

Here are the list this CL includes:
- Adding missing @NonNull, @Nullable, @IntRange annotations
- Added @Px annotation to Paint.set/getWordSpacing
- Change Builder classes to final.
- Change FileDescriptor to ParcelFileDescriptor as described in guideline.
- With this change, additional error handling is required in old
  Typeface.Builder but we can keep the same behavior (silently fallback to
  system fallback in error case).
- Fix comment in getLineHyphenEdit in LineBreaker.Result
- Rename setJustified to setJustificationMode in LineBreaker.Builder

Fix: 126702154
Fix: 126701272
Fix: 126701569
Fix: 126701953
Fix: 126701507
Fix: 126701667
Fix: 126700866
Fix: 126701009
Fix: 126700795
Fix: 126700292
Fix: 126699209
Fix: 124795407
Fix: 124795470
Bug: 124794844
Bug: 124794899

Test: m update-api
Test: TreeHugger

Change-Id: If6e8566b0eef9151d35d75b7f258128d7d3df358
parent fbdcc72d

api/current.txt

+28 −28
Original line number Diff line number Diff line
@@ -14459,7 +14459,7 @@ package android.graphics { 
    method public android.graphics.Paint.Style getStyle();

    method public android.graphics.Paint.Align getTextAlign();

    method public void getTextBounds(String, int, int, android.graphics.Rect);

    method public void getTextBounds(CharSequence, int, int, android.graphics.Rect);

    method public void getTextBounds(@NonNull CharSequence, int, int, @NonNull android.graphics.Rect);

    method public void getTextBounds(char[], int, int, android.graphics.Rect);

    method @NonNull public java.util.Locale getTextLocale();

    method @NonNull @Size(min=1) public android.os.LocaleList getTextLocales();
@@ -14478,7 +14478,7 @@ package android.graphics { 
    method public android.graphics.Typeface getTypeface();

    method @Px public float getUnderlinePosition();

    method @Px public float getUnderlineThickness();

    method public float getWordSpacing();

    method @Px public float getWordSpacing();

    method @Deprecated public android.graphics.Xfermode getXfermode();

    method public boolean hasGlyph(String);

    method public final boolean isAntiAlias();
@@ -14534,7 +14534,7 @@ package android.graphics { 
    method public void setTextSkewX(float);

    method public android.graphics.Typeface setTypeface(android.graphics.Typeface);

    method public void setUnderlineText(boolean);

    method public void setWordSpacing(float);

    method public void setWordSpacing(@Px float);

    method @Deprecated public android.graphics.Xfermode setXfermode(android.graphics.Xfermode);

    field public static final int ANTI_ALIAS_FLAG = 1; // 0x1

    field public static final int CURSOR_AFTER = 0; // 0x0
@@ -15114,13 +15114,13 @@ package android.graphics { 
    method public android.graphics.Typeface.Builder setWeight(@IntRange(from=1, to=1000) int);

  }













  public static class Typeface.CustomFallbackBuilder {













  public static final class Typeface.CustomFallbackBuilder {















    ctor public Typeface.CustomFallbackBuilder(@NonNull android.graphics.fonts.FontFamily);













    method public android.graphics.Typeface.CustomFallbackBuilder addCustomFallback(@NonNull android.graphics.fonts.FontFamily);













    method public android.graphics.Typeface build();













    method @NonNull public android.graphics.Typeface.CustomFallbackBuilder addCustomFallback(@NonNull android.graphics.fonts.FontFamily);













    method @NonNull public android.graphics.Typeface build();















    method @IntRange(from=64) public static int getMaxCustomFallbackCount();













    method public android.graphics.Typeface.CustomFallbackBuilder setStyle(@NonNull android.graphics.fonts.FontStyle);













    method public android.graphics.Typeface.CustomFallbackBuilder setSystemFallback(@NonNull String);













    method @NonNull public android.graphics.Typeface.CustomFallbackBuilder setStyle(@NonNull android.graphics.fonts.FontStyle);













    method @NonNull public android.graphics.Typeface.CustomFallbackBuilder setSystemFallback(@NonNull String);















  }





























  public class Xfermode {










@@ -15774,15 +15774,15 @@ package android.graphics.fonts {













    method @NonNull public java.nio.ByteBuffer getBuffer();















    method @Nullable public java.io.File getFile();















    method @NonNull public android.os.LocaleList getLocaleList();













    method public android.graphics.fonts.FontStyle getStyle();













    method @NonNull public android.graphics.fonts.FontStyle getStyle();















    method @IntRange(from=0) public int getTtcIndex();















  }



























  public static class Font.Builder {













  public static final class Font.Builder {















    ctor public Font.Builder(@NonNull java.nio.ByteBuffer);















    ctor public Font.Builder(@NonNull java.io.File);













    ctor public Font.Builder(@NonNull java.io.FileDescriptor);













    ctor public Font.Builder(@NonNull java.io.FileDescriptor, @IntRange(from=0) long, @IntRange(from=0xffffffff) long);













    ctor public Font.Builder(@NonNull android.os.ParcelFileDescriptor);













    ctor public Font.Builder(@NonNull android.os.ParcelFileDescriptor, @IntRange(from=0) long, @IntRange(from=0xffffffff) long);















    ctor public Font.Builder(@NonNull android.content.res.AssetManager, @NonNull String);















    ctor public Font.Builder(@NonNull android.content.res.Resources, int);















    method @Nullable public android.graphics.fonts.Font build() throws java.io.IOException;









@@ -15794,11 +15794,11 @@ package android.graphics.fonts {













  }





























  public final class FontFamily {













    method public android.graphics.fonts.Font getFont(@IntRange(from=0) int);













    method public int getSize();













    method @NonNull public android.graphics.fonts.Font getFont(@IntRange(from=0) int);













    method @IntRange(from=1) public int getSize();















  }



























  public static class FontFamily.Builder {













  public static final class FontFamily.Builder {















    ctor public FontFamily.Builder(@NonNull android.graphics.fonts.Font);















    method @NonNull public android.graphics.fonts.FontFamily.Builder addFont(@NonNull android.graphics.fonts.Font);















    method @NonNull public android.graphics.fonts.FontFamily build();










@@ -15890,7 +15890,7 @@ package android.graphics.pdf {













package android.graphics.text {





























  public class LineBreaker {













    method public android.graphics.text.LineBreaker.Result computeLineBreaks(@NonNull android.graphics.text.MeasuredText, @NonNull android.graphics.text.LineBreaker.ParagraphConstraints, @IntRange(from=0) int);













    method @NonNull public android.graphics.text.LineBreaker.Result computeLineBreaks(@NonNull android.graphics.text.MeasuredText, @NonNull android.graphics.text.LineBreaker.ParagraphConstraints, @IntRange(from=0) int);















    field public static final int BREAK_STRATEGY_BALANCED = 2; // 0x2















    field public static final int BREAK_STRATEGY_HIGH_QUALITY = 1; // 0x1















    field public static final int BREAK_STRATEGY_SIMPLE = 0; // 0x0









@@ -15901,13 +15901,13 @@ package android.graphics.text {













    field public static final int JUSTIFICATION_MODE_NONE = 0; // 0x0















  }



























  public static class LineBreaker.Builder {













  public static final class LineBreaker.Builder {















    ctor public LineBreaker.Builder();













    method public android.graphics.text.LineBreaker build();













    method public android.graphics.text.LineBreaker.Builder setBreakStrategy(int);













    method public android.graphics.text.LineBreaker.Builder setHyphenationFrequency(int);













    method public android.graphics.text.LineBreaker.Builder setIndents(@Nullable int[]);













    method public android.graphics.text.LineBreaker.Builder setJustified(int);













    method @NonNull public android.graphics.text.LineBreaker build();













    method @NonNull public android.graphics.text.LineBreaker.Builder setBreakStrategy(int);













    method @NonNull public android.graphics.text.LineBreaker.Builder setHyphenationFrequency(int);













    method @NonNull public android.graphics.text.LineBreaker.Builder setIndents(@Nullable int[]);













    method @NonNull public android.graphics.text.LineBreaker.Builder setJustificationMode(int);















  }





























  public static class LineBreaker.ParagraphConstraints {










@@ -15939,14 +15939,14 @@ package android.graphics.text {













    method @FloatRange(from=0.0) @Px public float getWidth(@IntRange(from=0) int, @IntRange(from=0) int);















  }



























  public static class MeasuredText.Builder {













  public static final class MeasuredText.Builder {















    ctor public MeasuredText.Builder(@NonNull char[]);















    ctor public MeasuredText.Builder(@NonNull android.graphics.text.MeasuredText);













    method public android.graphics.text.MeasuredText.Builder appendReplacementRun(@NonNull android.graphics.Paint, @IntRange(from=0) int, @FloatRange(from=0) float);













    method public android.graphics.text.MeasuredText.Builder appendStyleRun(@NonNull android.graphics.Paint, @IntRange(from=0) int, boolean);













    method public android.graphics.text.MeasuredText build();













    method public android.graphics.text.MeasuredText.Builder setComputeHyphenation(boolean);













    method public android.graphics.text.MeasuredText.Builder setComputeLayout(boolean);













    method @NonNull public android.graphics.text.MeasuredText.Builder appendReplacementRun(@NonNull android.graphics.Paint, @IntRange(from=0) int, @Px @FloatRange(from=0) float);













    method @NonNull public android.graphics.text.MeasuredText.Builder appendStyleRun(@NonNull android.graphics.Paint, @IntRange(from=0) int, boolean);













    method @NonNull public android.graphics.text.MeasuredText build();













    method @NonNull public android.graphics.text.MeasuredText.Builder setComputeHyphenation(boolean);













    method @NonNull public android.graphics.text.MeasuredText.Builder setComputeLayout(boolean);















  }





























}

























core/java/android/text/StaticLayout.java



+1
−1




























Original line number
Diff line number
Diff line








@@ -643,7 +643,7 @@ public class StaticLayout extends Layout {













                .setBreakStrategy(b.mBreakStrategy)















                .setHyphenationFrequency(b.mHyphenationFrequency)















                // TODO: Support more justification mode, e.g. letter spacing, stretching.













                .setJustified(b.mJustificationMode)













                .setJustificationMode(b.mJustificationMode)















                .setIndents(indents)















                .build();

















































graphics/java/android/graphics/Paint.java



+8
−3




























Original line number
Diff line number
Diff line








@@ -1733,7 +1733,7 @@ public class Paint {













     * @return the paint's extra word-spacing for drawing text in pixels.















     * @see #setWordSpacing(float)















     */













    public float getWordSpacing() {













    public @Px float getWordSpacing() {















        return nGetWordSpacing(mNativePaint);















    }

























@@ -1746,7 +1746,7 @@ public class Paint {













     * @param wordSpacing set the paint's extra word-spacing for drawing text in pixels.















     * @see #getWordSpacing()















     */













    public void setWordSpacing(float wordSpacing) {













    public void setWordSpacing(@Px float wordSpacing) {















        nSetWordSpacing(mNativePaint, wordSpacing);















    }


























@@ -2706,6 +2706,8 @@ public class Paint {













    }































    /**













     * Retrieve the text boundary box and store to bounds.













     *















     * Return in bounds (allocated by the caller) the smallest rectangle that















     * encloses all of the characters, with an implied origin at (0,0).















     *









@@ -2725,6 +2727,8 @@ public class Paint {













    }































    /**













     * Retrieve the text boundary box and store to bounds.













     *















     * Return in bounds (allocated by the caller) the smallest rectangle that















     * encloses all of the characters, with an implied origin at (0,0).















     *









@@ -2736,7 +2740,8 @@ public class Paint {













     * @param end 1 past the last char in the text to measure















     * @param bounds returns the unioned bounds of all the text. Must be allocated by the caller















     */













    public void getTextBounds(CharSequence text, int start, int end, Rect bounds) {













    public void getTextBounds(@NonNull CharSequence text, int start, int end,













            @NonNull Rect bounds) {















        if ((start | end | (end - start) | (text.length() - end)) < 0) {















            throw new IndexOutOfBoundsException();















        }

































graphics/java/android/graphics/Typeface.java



+20
−7




























Original line number
Diff line number
Diff line








@@ -34,6 +34,7 @@ import android.graphics.fonts.FontVariationAxis;













import android.graphics.fonts.SystemFonts;















import android.os.Build;















import android.os.Build.VERSION_CODES;













import android.os.ParcelFileDescriptor;















import android.provider.FontRequest;















import android.provider.FontsContract;















import android.text.FontConfig;










@@ -368,7 +369,7 @@ public class Typeface {













        private final AssetManager mAssetManager;















        private final String mPath;





























        private final Font.Builder mFontBuilder;













        private final @Nullable Font.Builder mFontBuilder;































        private String mFallbackFamilyName;

























@@ -395,7 +396,16 @@ public class Typeface {













         * @param fd The file descriptor. The passed fd must be mmap-able.















         */















        public Builder(@NonNull FileDescriptor fd) {













            mFontBuilder = new Font.Builder(fd);













            Font.Builder builder;













            try {













                builder = new Font.Builder(ParcelFileDescriptor.dup(fd));













            } catch (IOException e) {













                // We cannot tell the error to developer at this moment since we cannot change the













                // public API signature. Instead, silently fallbacks to system fallback in the build













                // method as the same as other error cases.













                builder = null;













            }













            mFontBuilder = builder;















            mAssetManager = null;















            mPath = null;















        }










@@ -585,6 +595,9 @@ public class Typeface {













         * @return Newly created Typeface. May return null if some parameters are invalid.















         */















        public Typeface build() {













            if (mFontBuilder == null) {













                return resolveFallbackTypeface();













            }















            try {















                final Font font = mFontBuilder.build();















                final String key = mAssetManager == null ? null : createAssetUid(










@@ -687,7 +700,7 @@ public class Typeface {













     * </pre>















     * </p>















     */













    public static class CustomFallbackBuilder {













    public static final class CustomFallbackBuilder {















        private static final int MAX_CUSTOM_FALLBACK = 64;















        private final ArrayList<FontFamily> mFamilies = new ArrayList<>();















        private String mFallbackName = null;










@@ -728,7 +741,7 @@ public class Typeface {













         * @param familyName a family name to be used for fallback if the provided fonts can not be















         *                   used















         */













        public CustomFallbackBuilder setSystemFallback(@NonNull String familyName) {













        public @NonNull CustomFallbackBuilder setSystemFallback(@NonNull String familyName) {















            Preconditions.checkNotNull(familyName);















            mFallbackName = familyName;















            return this;









@@ -743,7 +756,7 @@ public class Typeface {













         *















         * @param style a font style















         */













        public CustomFallbackBuilder setStyle(@NonNull FontStyle style) {













        public @NonNull CustomFallbackBuilder setStyle(@NonNull FontStyle style) {















            mStyle = style;















            return this;















        }









@@ -758,7 +771,7 @@ public class Typeface {













         * @param family a fallback family















         * @throws IllegalArgumentException if you give more than 64 custom fallback families















         */













        public CustomFallbackBuilder addCustomFallback(@NonNull FontFamily family) {













        public @NonNull CustomFallbackBuilder addCustomFallback(@NonNull FontFamily family) {















            Preconditions.checkNotNull(family);















            Preconditions.checkArgument(mFamilies.size() < getMaxCustomFallbackCount(),















                    "Custom fallback limit exceeded(" + getMaxCustomFallbackCount() + ")");









@@ -771,7 +784,7 @@ public class Typeface {













         *















         * @return the Typeface object















         */













        public Typeface build() {













        public @NonNull Typeface build() {















            final int userFallbackSize = mFamilies.size();















            final FontFamily[] fallback = SystemFonts.getSystemFallback(mFallbackName);















            final long[] ptrArray = new long[fallback.length + userFallbackSize];

































graphics/java/android/graphics/fonts/Font.java



+6
−6




























Original line number
Diff line number
Diff line








@@ -22,6 +22,7 @@ import android.annotation.Nullable;













import android.content.res.AssetManager;















import android.content.res.Resources;















import android.os.LocaleList;













import android.os.ParcelFileDescriptor;















import android.util.TypedValue;































import com.android.internal.util.Preconditions;









@@ -31,7 +32,6 @@ import dalvik.annotation.optimization.CriticalNative;













import libcore.util.NativeAllocationRegistry;































import java.io.File;













import java.io.FileDescriptor;















import java.io.FileInputStream;















import java.io.FileNotFoundException;















import java.io.IOException;









@@ -53,7 +53,7 @@ public final class Font {













    /**















     * A builder class for creating new Font.















     */













    public static class Builder {













    public static final class Builder {















        private static final NativeAllocationRegistry sAssetByteBufferRegistroy =















                new NativeAllocationRegistry(ByteBuffer.class.getClassLoader(),















                    nGetReleaseNativeAssetFunc(), 64);










@@ -122,7 +122,7 @@ public final class Font {













         *















         * @param fd a file descriptor















         */













        public Builder(@NonNull FileDescriptor fd) {













        public Builder(@NonNull ParcelFileDescriptor fd) {















            this(fd, 0, -1);















        }

























@@ -133,9 +133,9 @@ public final class Font {













         * @param offset an offset to of the font data in the file















         * @param size a size of the font data. If -1 is passed, use until end of the file.















         */













        public Builder(@NonNull FileDescriptor fd, @IntRange(from = 0) long offset,













        public Builder(@NonNull ParcelFileDescriptor fd, @IntRange(from = 0) long offset,















                @IntRange(from = -1) long size) {













            try (FileInputStream fis = new FileInputStream(fd)) {













            try (FileInputStream fis = new FileInputStream(fd.getFileDescriptor())) {















                final FileChannel fc = fis.getChannel();















                size = (size == -1) ? fc.size() - offset : size;















                mBuffer = fc.map(FileChannel.MapMode.READ_ONLY, offset, size);










@@ -467,7 +467,7 @@ public final class Font {













     * @see Builder#setSlant(int)















     * @return a font style















     */













    public FontStyle getStyle() {













    public @NonNull FontStyle getStyle() {















        return mFontStyle;















    }