diff options
16 files changed, 268 insertions, 76 deletions
diff --git a/core/java/android/text/style/AbsoluteSizeSpan.java b/core/java/android/text/style/AbsoluteSizeSpan.java index 908ef55a6ae9..3b4eea76b390 100644 --- a/core/java/android/text/style/AbsoluteSizeSpan.java +++ b/core/java/android/text/style/AbsoluteSizeSpan.java @@ -16,71 +16,105 @@ package android.text.style; +import android.annotation.NonNull; import android.os.Parcel; import android.text.ParcelableSpan; import android.text.TextPaint; import android.text.TextUtils; +/** + * A span that changes the size of the text it's attached to. + * <p> + * For example, the size of the text can be changed to 55dp like this: + * <pre>{@code + * SpannableString string = new SpannableString("Text with absolute size span"); + *string.setSpan(new AbsoluteSizeSpan(55, true), 10, 23, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre> + * <img src="{@docRoot}reference/android/images/text/style/absolutesizespan.png" /> + * <figcaption>Text with text size updated.</figcaption> + */ public class AbsoluteSizeSpan extends MetricAffectingSpan implements ParcelableSpan { private final int mSize; - private boolean mDip; + private final boolean mDip; /** * Set the text size to <code>size</code> physical pixels. */ public AbsoluteSizeSpan(int size) { - mSize = size; + this(size, false); } /** - * Set the text size to <code>size</code> physical pixels, - * or to <code>size</code> device-independent pixels if - * <code>dip</code> is true. + * Set the text size to <code>size</code> physical pixels, or to <code>size</code> + * device-independent pixels if <code>dip</code> is true. */ public AbsoluteSizeSpan(int size, boolean dip) { mSize = size; mDip = dip; } - public AbsoluteSizeSpan(Parcel src) { + /** + * Creates an {@link AbsoluteSizeSpan} from a parcel. + */ + public AbsoluteSizeSpan(@NonNull Parcel src) { mSize = src.readInt(); mDip = src.readInt() != 0; } - + + @Override public int getSpanTypeId() { return getSpanTypeIdInternal(); } /** @hide */ + @Override public int getSpanTypeIdInternal() { return TextUtils.ABSOLUTE_SIZE_SPAN; } - + + @Override public int describeContents() { return 0; } - public void writeToParcel(Parcel dest, int flags) { + @Override + public void writeToParcel(@NonNull Parcel dest, int flags) { writeToParcelInternal(dest, flags); } /** @hide */ - public void writeToParcelInternal(Parcel dest, int flags) { + @Override + public void writeToParcelInternal(@NonNull Parcel dest, int flags) { dest.writeInt(mSize); dest.writeInt(mDip ? 1 : 0); } + /** + * Get the text size. This is in physical pixels if {@link #getDip()} returns false or in + * device-independent pixels if {@link #getDip()} returns true. + * + * @return the text size, either in physical pixels or device-independent pixels. + * @see AbsoluteSizeSpan#AbsoluteSizeSpan(int, boolean) + */ public int getSize() { return mSize; } + /** + * Returns whether the size is in device-independent pixels or not, depending on the + * <code>dip</code> flag passed in {@link #AbsoluteSizeSpan(int, boolean)} + * + * @return <code>true</code> if the size is in device-independent pixels, <code>false</code> + * otherwise + * + * @see #AbsoluteSizeSpan(int, boolean) + */ public boolean getDip() { return mDip; } @Override - public void updateDrawState(TextPaint ds) { + public void updateDrawState(@NonNull TextPaint ds) { if (mDip) { ds.setTextSize(mSize * ds.density); } else { @@ -89,7 +123,7 @@ public class AbsoluteSizeSpan extends MetricAffectingSpan implements ParcelableS } @Override - public void updateMeasureState(TextPaint ds) { + public void updateMeasureState(@NonNull TextPaint ds) { if (mDip) { ds.setTextSize(mSize * ds.density); } else { diff --git a/core/java/android/text/style/BackgroundColorSpan.java b/core/java/android/text/style/BackgroundColorSpan.java index 4f471a8a2f85..44e35615ca55 100644 --- a/core/java/android/text/style/BackgroundColorSpan.java +++ b/core/java/android/text/style/BackgroundColorSpan.java @@ -27,11 +27,10 @@ import android.text.TextUtils; * Changes the background color of the text to which the span is attached. * <p> * For example, to set a green background color for a text you would create a {@link - * android.text.SpannableStringBuilder} based on the text and set the span. + * android.text.SpannableString} based on the text and set the span. * <pre>{@code * SpannableString string = new SpannableString("Text with a background color span"); - *string.setSpan(new BackgroundColorSpan(color), 12, 28, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE); - * }</pre> + *string.setSpan(new BackgroundColorSpan(color), 12, 28, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre> * <img src="{@docRoot}reference/android/images/text/style/backgroundcolorspan.png" /> * <figcaption>Set a background color for the text.</figcaption> */ @@ -58,30 +57,29 @@ public class BackgroundColorSpan extends CharacterStyle mColor = src.readInt(); } + @Override public int getSpanTypeId() { return getSpanTypeIdInternal(); } /** @hide */ + @Override public int getSpanTypeIdInternal() { return TextUtils.BACKGROUND_COLOR_SPAN; } + @Override public int describeContents() { return 0; } - /** - * Flatten this object into a Parcel. - * - * @param dest The Parcel in which the object should be written. - * @param flags Additional flags about how the object should be written. - */ + @Override public void writeToParcel(@NonNull Parcel dest, int flags) { writeToParcelInternal(dest, flags); } /** @hide */ + @Override public void writeToParcelInternal(@NonNull Parcel dest, int flags) { dest.writeInt(mColor); } diff --git a/core/java/android/text/style/ForegroundColorSpan.java b/core/java/android/text/style/ForegroundColorSpan.java index 08ab2a1f1a20..f770674503f2 100644 --- a/core/java/android/text/style/ForegroundColorSpan.java +++ b/core/java/android/text/style/ForegroundColorSpan.java @@ -27,11 +27,10 @@ import android.text.TextUtils; * Changes the color of the text to which the span is attached. * <p> * For example, to set a green text color you would create a {@link - * android.text.SpannableStringBuilder} based on the text and set the span. + * android.text.SpannableString} based on the text and set the span. * <pre>{@code * SpannableString string = new SpannableString("Text with a foreground color span"); - *string.setSpan(new ForegroundColorSpan(color), 12, 28, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE); - * }</pre> + *string.setSpan(new ForegroundColorSpan(color), 12, 28, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre> * <img src="{@docRoot}reference/android/images/text/style/foregroundcolorspan.png" /> * <figcaption>Set a text color.</figcaption> */ @@ -59,30 +58,29 @@ public class ForegroundColorSpan extends CharacterStyle mColor = src.readInt(); } + @Override public int getSpanTypeId() { return getSpanTypeIdInternal(); } /** @hide */ + @Override public int getSpanTypeIdInternal() { return TextUtils.FOREGROUND_COLOR_SPAN; } + @Override public int describeContents() { return 0; } - /** - * Flatten this object into a Parcel. - * - * @param dest The Parcel in which the object should be written. - * @param flags Additional flags about how the object should be written. - */ + @Override public void writeToParcel(@NonNull Parcel dest, int flags) { writeToParcelInternal(dest, flags); } /** @hide */ + @Override public void writeToParcelInternal(@NonNull Parcel dest, int flags) { dest.writeInt(mColor); } diff --git a/core/java/android/text/style/RelativeSizeSpan.java b/core/java/android/text/style/RelativeSizeSpan.java index 95f048a2e240..3094f27ab72d 100644 --- a/core/java/android/text/style/RelativeSizeSpan.java +++ b/core/java/android/text/style/RelativeSizeSpan.java @@ -16,56 +16,85 @@ package android.text.style; +import android.annotation.FloatRange; +import android.annotation.NonNull; import android.os.Parcel; import android.text.ParcelableSpan; import android.text.TextPaint; import android.text.TextUtils; +/** + * Uniformly scales the size of the text to which it's attached by a certain proportion. + * <p> + * For example, a <code>RelativeSizeSpan</code> that increases the text size by 50% can be + * constructed like this: + * <pre>{@code + * SpannableString string = new SpannableString("Text with relative size span"); + *string.setSpan(new RelativeSizeSpan(1.5f), 10, 24, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre> + * <img src="{@docRoot}reference/android/images/text/style/relativesizespan.png" /> + * <figcaption>Text increased by 50% with <code>RelativeSizeSpan</code>.</figcaption> + */ public class RelativeSizeSpan extends MetricAffectingSpan implements ParcelableSpan { private final float mProportion; - public RelativeSizeSpan(float proportion) { + /** + * Creates a {@link RelativeSizeSpan} based on a proportion. + * + * @param proportion the proportion with which the text is scaled. + */ + public RelativeSizeSpan(@FloatRange(from = 0) float proportion) { mProportion = proportion; } - public RelativeSizeSpan(Parcel src) { + /** + * Creates a {@link RelativeSizeSpan} from a parcel. + */ + public RelativeSizeSpan(@NonNull Parcel src) { mProportion = src.readFloat(); } - + + @Override public int getSpanTypeId() { return getSpanTypeIdInternal(); } /** @hide */ + @Override public int getSpanTypeIdInternal() { return TextUtils.RELATIVE_SIZE_SPAN; } - + + @Override public int describeContents() { return 0; } - public void writeToParcel(Parcel dest, int flags) { + @Override + public void writeToParcel(@NonNull Parcel dest, int flags) { writeToParcelInternal(dest, flags); } /** @hide */ - public void writeToParcelInternal(Parcel dest, int flags) { + @Override + public void writeToParcelInternal(@NonNull Parcel dest, int flags) { dest.writeFloat(mProportion); } + /** + * @return the proportion with which the text size is changed. + */ public float getSizeChange() { return mProportion; } @Override - public void updateDrawState(TextPaint ds) { + public void updateDrawState(@NonNull TextPaint ds) { ds.setTextSize(ds.getTextSize() * mProportion); } @Override - public void updateMeasureState(TextPaint ds) { + public void updateMeasureState(@NonNull TextPaint ds) { ds.setTextSize(ds.getTextSize() * mProportion); } } diff --git a/core/java/android/text/style/ScaleXSpan.java b/core/java/android/text/style/ScaleXSpan.java index d085018572ec..6ef4ceccced1 100644 --- a/core/java/android/text/style/ScaleXSpan.java +++ b/core/java/android/text/style/ScaleXSpan.java @@ -16,45 +16,79 @@ package android.text.style; +import android.annotation.FloatRange; +import android.annotation.NonNull; import android.os.Parcel; import android.text.ParcelableSpan; import android.text.TextPaint; import android.text.TextUtils; +/** + * Scales horizontally the size of the text to which it's attached by a certain factor. + * <p> + * Values > 1.0 will stretch the text wider. Values < 1.0 will stretch the text narrower. + * <p> + * For example, a <code>ScaleXSpan</code> that stretches the text size by 100% can be + * constructed like this: + * <pre>{@code + * SpannableString string = new SpannableString("Text with ScaleX span"); + *string.setSpan(new ScaleXSpan(2f), 10, 16, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre> + * <img src="{@docRoot}reference/android/images/text/style/scalexspan.png" /> + * <figcaption>Text scaled by 100% with <code>ScaleXSpan</code>.</figcaption> + */ public class ScaleXSpan extends MetricAffectingSpan implements ParcelableSpan { private final float mProportion; - public ScaleXSpan(float proportion) { + /** + * Creates a {@link ScaleXSpan} based on a proportion. Values > 1.0 will stretch the text wider. + * Values < 1.0 will stretch the text narrower. + * + * @param proportion the horizontal scale factor. + */ + public ScaleXSpan(@FloatRange(from = 0) float proportion) { mProportion = proportion; } - public ScaleXSpan(Parcel src) { + /** + * Creates a {@link ScaleXSpan} from a parcel. + */ + public ScaleXSpan(@NonNull Parcel src) { mProportion = src.readFloat(); } - + + @Override public int getSpanTypeId() { return getSpanTypeIdInternal(); } /** @hide */ + @Override public int getSpanTypeIdInternal() { return TextUtils.SCALE_X_SPAN; } - + + @Override public int describeContents() { return 0; } - public void writeToParcel(Parcel dest, int flags) { + @Override + public void writeToParcel(@NonNull Parcel dest, int flags) { writeToParcelInternal(dest, flags); } /** @hide */ - public void writeToParcelInternal(Parcel dest, int flags) { + @Override + public void writeToParcelInternal(@NonNull Parcel dest, int flags) { dest.writeFloat(mProportion); } + /** + * Get the horizontal scale factor for the text. + * + * @return the horizontal scale factor. + */ public float getScaleX() { return mProportion; } diff --git a/core/java/android/text/style/StrikethroughSpan.java b/core/java/android/text/style/StrikethroughSpan.java index 1389704f6ad8..a6305050656a 100644 --- a/core/java/android/text/style/StrikethroughSpan.java +++ b/core/java/android/text/style/StrikethroughSpan.java @@ -16,42 +16,65 @@ package android.text.style; +import android.annotation.NonNull; import android.os.Parcel; import android.text.ParcelableSpan; import android.text.TextPaint; import android.text.TextUtils; +/** + * A span that strikes through the text it's attached to. + * <p> + * The span can be used like this: + * <pre>{@code + * SpannableString string = new SpannableString("Text with strikethrough span"); + *string.setSpan(new StrikethroughSpan(), 10, 23, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre> + * <img src="{@docRoot}reference/android/images/text/style/strikethroughspan.png" /> + * <figcaption>Strikethrough text.</figcaption> + */ public class StrikethroughSpan extends CharacterStyle implements UpdateAppearance, ParcelableSpan { + + /** + * Creates a {@link StrikethroughSpan}. + */ public StrikethroughSpan() { } - - public StrikethroughSpan(Parcel src) { + + /** + * Creates a {@link StrikethroughSpan} from a parcel. + */ + public StrikethroughSpan(@NonNull Parcel src) { } - + + @Override public int getSpanTypeId() { return getSpanTypeIdInternal(); } /** @hide */ + @Override public int getSpanTypeIdInternal() { return TextUtils.STRIKETHROUGH_SPAN; } - + + @Override public int describeContents() { return 0; } - public void writeToParcel(Parcel dest, int flags) { + @Override + public void writeToParcel(@NonNull Parcel dest, int flags) { writeToParcelInternal(dest, flags); } /** @hide */ - public void writeToParcelInternal(Parcel dest, int flags) { + @Override + public void writeToParcelInternal(@NonNull Parcel dest, int flags) { } @Override - public void updateDrawState(TextPaint ds) { + public void updateDrawState(@NonNull TextPaint ds) { ds.setStrikeThruText(true); } } diff --git a/core/java/android/text/style/SubscriptSpan.java b/core/java/android/text/style/SubscriptSpan.java index f1b0d38cf624..3d15aad662b1 100644 --- a/core/java/android/text/style/SubscriptSpan.java +++ b/core/java/android/text/style/SubscriptSpan.java @@ -16,46 +16,74 @@ package android.text.style; +import android.annotation.NonNull; import android.os.Parcel; import android.text.ParcelableSpan; import android.text.TextPaint; import android.text.TextUtils; +/** + * The span that moves the position of the text baseline lower. + * <p> + * The span can be used like this: + * <pre>{@code + * SpannableString string = new SpannableString("☕- C8H10N4O2\n"); + *string.setSpan(new SubscriptSpan(), 4, 5, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE); + *string.setSpan(new SubscriptSpan(), 6, 8, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE); + *string.setSpan(new SubscriptSpan(), 9, 10, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE); + *string.setSpan(new SubscriptSpan(), 11, 12, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre> + * <img src="{@docRoot}reference/android/images/text/style/subscriptspan.png" /> + * <figcaption>Text with <code>SubscriptSpan</code>.</figcaption> + * Note: Since the span affects the position of the text, if the text is on the last line of a + * TextView, it may appear cut. + */ public class SubscriptSpan extends MetricAffectingSpan implements ParcelableSpan { + + /** + * Creates a {@link SubscriptSpan}. + */ public SubscriptSpan() { } - - public SubscriptSpan(Parcel src) { + + /** + * Creates a {@link SubscriptSpan} from a parcel. + */ + public SubscriptSpan(@NonNull Parcel src) { } - + + @Override public int getSpanTypeId() { return getSpanTypeIdInternal(); } /** @hide */ + @Override public int getSpanTypeIdInternal() { return TextUtils.SUBSCRIPT_SPAN; } - + + @Override public int describeContents() { return 0; } + @Override public void writeToParcel(Parcel dest, int flags) { writeToParcelInternal(dest, flags); } /** @hide */ + @Override public void writeToParcelInternal(Parcel dest, int flags) { } @Override - public void updateDrawState(TextPaint tp) { - tp.baselineShift -= (int) (tp.ascent() / 2); + public void updateDrawState(@NonNull TextPaint textPaint) { + textPaint.baselineShift -= (int) (textPaint.ascent() / 2); } @Override - public void updateMeasureState(TextPaint tp) { - tp.baselineShift -= (int) (tp.ascent() / 2); + public void updateMeasureState(@NonNull TextPaint textPaint) { + textPaint.baselineShift -= (int) (textPaint.ascent() / 2); } } diff --git a/core/java/android/text/style/SuperscriptSpan.java b/core/java/android/text/style/SuperscriptSpan.java index abcf688f10ff..3dc9d3fdfe05 100644 --- a/core/java/android/text/style/SuperscriptSpan.java +++ b/core/java/android/text/style/SuperscriptSpan.java @@ -16,46 +16,71 @@ package android.text.style; +import android.annotation.NonNull; import android.os.Parcel; import android.text.ParcelableSpan; import android.text.TextPaint; import android.text.TextUtils; +/** + * The span that moves the position of the text baseline higher. + * <p> + * The span can be used like this: + * <pre>{@code + * SpannableString string = new SpannableString("1st example"); + *string.setSpan(new SuperscriptSpan(), 1, 3, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre> + * <img src="{@docRoot}reference/android/images/text/style/superscriptspan.png" /> + * <figcaption>Text with <code>SuperscriptSpan</code>.</figcaption> + * Note: Since the span affects the position of the text, if the text is on the first line of a + * TextView, it may appear cut. This can be avoided by decreasing the text size with an {@link + * AbsoluteSizeSpan} + */ public class SuperscriptSpan extends MetricAffectingSpan implements ParcelableSpan { + /** + * Creates a {@link SuperscriptSpan}. + */ public SuperscriptSpan() { } - - public SuperscriptSpan(Parcel src) { + + /** + * Creates a {@link SuperscriptSpan} from a parcel. + */ + public SuperscriptSpan(@NonNull Parcel src) { } - + + @Override public int getSpanTypeId() { return getSpanTypeIdInternal(); } /** @hide */ + @Override public int getSpanTypeIdInternal() { return TextUtils.SUPERSCRIPT_SPAN; } - + + @Override public int describeContents() { return 0; } - public void writeToParcel(Parcel dest, int flags) { + @Override + public void writeToParcel(@NonNull Parcel dest, int flags) { writeToParcelInternal(dest, flags); } /** @hide */ - public void writeToParcelInternal(Parcel dest, int flags) { + @Override + public void writeToParcelInternal(@NonNull Parcel dest, int flags) { } @Override - public void updateDrawState(TextPaint tp) { - tp.baselineShift += (int) (tp.ascent() / 2); + public void updateDrawState(@NonNull TextPaint textPaint) { + textPaint.baselineShift += (int) (textPaint.ascent() / 2); } @Override - public void updateMeasureState(TextPaint tp) { - tp.baselineShift += (int) (tp.ascent() / 2); + public void updateMeasureState(@NonNull TextPaint textPaint) { + textPaint.baselineShift += (int) (textPaint.ascent() / 2); } } diff --git a/core/java/android/text/style/UnderlineSpan.java b/core/java/android/text/style/UnderlineSpan.java index 9024dcd39256..800838ef92e9 100644 --- a/core/java/android/text/style/UnderlineSpan.java +++ b/core/java/android/text/style/UnderlineSpan.java @@ -16,42 +16,65 @@ package android.text.style; +import android.annotation.NonNull; import android.os.Parcel; import android.text.ParcelableSpan; import android.text.TextPaint; import android.text.TextUtils; +/** + * A span that underlines the text it's attached to. + * <p> + * The span can be used like this: + * <pre>{@code + * SpannableString string = new SpannableString("Text with underline span"); + *string.setSpan(new UnderlineSpan(), 10, 19, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre> + * <img src="{@docRoot}reference/android/images/text/style/underlinespan.png" /> + * <figcaption>Underlined text.</figcaption> + */ public class UnderlineSpan extends CharacterStyle implements UpdateAppearance, ParcelableSpan { + + /** + * Creates an {@link UnderlineSpan}. + */ public UnderlineSpan() { } - - public UnderlineSpan(Parcel src) { + + /** + * Creates an {@link UnderlineSpan} from a parcel. + */ + public UnderlineSpan(@NonNull Parcel src) { } - + + @Override public int getSpanTypeId() { return getSpanTypeIdInternal(); } /** @hide */ + @Override public int getSpanTypeIdInternal() { return TextUtils.UNDERLINE_SPAN; } - + + @Override public int describeContents() { return 0; } - public void writeToParcel(Parcel dest, int flags) { + @Override + public void writeToParcel(@NonNull Parcel dest, int flags) { writeToParcelInternal(dest, flags); } /** @hide */ - public void writeToParcelInternal(Parcel dest, int flags) { + @Override + public void writeToParcelInternal(@NonNull Parcel dest, int flags) { } @Override - public void updateDrawState(TextPaint ds) { + public void updateDrawState(@NonNull TextPaint ds) { ds.setUnderlineText(true); } } diff --git a/docs/html/reference/images/text/style/absolutesizespan.png b/docs/html/reference/images/text/style/absolutesizespan.png Binary files differnew file mode 100644 index 000000000000..40d5a79ae37e --- /dev/null +++ b/docs/html/reference/images/text/style/absolutesizespan.png diff --git a/docs/html/reference/images/text/style/relativesizespan.png b/docs/html/reference/images/text/style/relativesizespan.png Binary files differnew file mode 100644 index 000000000000..eaca5ad0e93f --- /dev/null +++ b/docs/html/reference/images/text/style/relativesizespan.png diff --git a/docs/html/reference/images/text/style/scalexspan.png b/docs/html/reference/images/text/style/scalexspan.png Binary files differnew file mode 100644 index 000000000000..a5ca26f571c6 --- /dev/null +++ b/docs/html/reference/images/text/style/scalexspan.png diff --git a/docs/html/reference/images/text/style/strikethroughspan.png b/docs/html/reference/images/text/style/strikethroughspan.png Binary files differnew file mode 100644 index 000000000000..a49ecadea063 --- /dev/null +++ b/docs/html/reference/images/text/style/strikethroughspan.png diff --git a/docs/html/reference/images/text/style/subscriptspan.png b/docs/html/reference/images/text/style/subscriptspan.png Binary files differnew file mode 100644 index 000000000000..aac7092a3322 --- /dev/null +++ b/docs/html/reference/images/text/style/subscriptspan.png diff --git a/docs/html/reference/images/text/style/superscriptspan.png b/docs/html/reference/images/text/style/superscriptspan.png Binary files differnew file mode 100644 index 000000000000..996f59d55dde --- /dev/null +++ b/docs/html/reference/images/text/style/superscriptspan.png diff --git a/docs/html/reference/images/text/style/underlinespan.png b/docs/html/reference/images/text/style/underlinespan.png Binary files differnew file mode 100644 index 000000000000..dbcd0d9f1498 --- /dev/null +++ b/docs/html/reference/images/text/style/underlinespan.png |
