diff options
| -rw-r--r-- | api/current.txt | 6 | ||||
| -rw-r--r-- | core/java/android/text/style/QuoteSpan.java | 143 | ||||
| -rw-r--r-- | docs/html/reference/images/text/style/customquotespan.png | bin | 0 -> 16345 bytes | |||
| -rw-r--r-- | docs/html/reference/images/text/style/defaultquotespan.png | bin | 0 -> 16008 bytes |
4 files changed, 134 insertions, 15 deletions
diff --git a/api/current.txt b/api/current.txt index be46e937168a..a3e51e1d5463 100644 --- a/api/current.txt +++ b/api/current.txt @@ -43847,13 +43847,19 @@ package android.text.style { public class QuoteSpan implements android.text.style.LeadingMarginSpan android.text.ParcelableSpan { ctor public QuoteSpan(); ctor public QuoteSpan(int); + ctor public QuoteSpan(int, int, int); ctor public QuoteSpan(android.os.Parcel); method public int describeContents(); method public void drawLeadingMargin(android.graphics.Canvas, android.graphics.Paint, int, int, int, int, int, java.lang.CharSequence, int, int, boolean, android.text.Layout); method public int getColor(); + method public int getGapWidth(); method public int getLeadingMargin(boolean); method public int getSpanTypeId(); + method public int getStripeWidth(); method public void writeToParcel(android.os.Parcel, int); + field public static final int STANDARD_COLOR = -16776961; // 0xff0000ff + field public static final int STANDARD_GAP_WIDTH_PX = 2; // 0x2 + field public static final int STANDARD_STRIPE_WIDTH_PX = 2; // 0x2 } public class RelativeSizeSpan extends android.text.style.MetricAffectingSpan implements android.text.ParcelableSpan { diff --git a/core/java/android/text/style/QuoteSpan.java b/core/java/android/text/style/QuoteSpan.java index 7217e1e5efa8..a1c12c256fa1 100644 --- a/core/java/android/text/style/QuoteSpan.java +++ b/core/java/android/text/style/QuoteSpan.java @@ -17,6 +17,9 @@ package android.text.style; import android.annotation.ColorInt; +import android.annotation.IntRange; +import android.annotation.NonNull; +import android.annotation.Px; import android.graphics.Canvas; import android.graphics.Paint; import android.os.Parcel; @@ -24,68 +27,178 @@ import android.text.Layout; import android.text.ParcelableSpan; import android.text.TextUtils; +/** + * A span which styles paragraphs by adding a vertical stripe at the beginning of the text + * (respecting layout direction). + * <p> + * A <code>QuoteSpan</code> must be attached from the first character to the last character of a + * single paragraph, otherwise the span will not be displayed. + * <p> + * <code>QuoteSpans</code> allow configuring the following elements: + * <ul> + * <li><b>color</b> - the vertical stripe color. By default, the stripe color is 0xff0000ff</li> + * <li><b>gap width</b> - the distance, in pixels, between the stripe and the paragraph. + * Default value is 2px.</li> + * <li><b>stripe width</b> - the width, in pixels, of the stripe. Default value is + * 2px.</li> + * </ul> + * For example, a <code>QuoteSpan</code> using the default values can be constructed like this: + * <pre>{@code SpannableString string = new SpannableString("Text with quote span on a long line"); + *string.setSpan(new QuoteSpan(), 0, string.length(), Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre> + * <img src="{@docRoot}reference/android/images/text/style/defaultquotespan.png" /> + * <figcaption><code>QuoteSpan</code> constructed with default values.</figcaption> + * <p> + * <p> + * To construct a <code>QuoteSpan</code> with a green stripe, of 20px in width and a gap width of + * 40px: + * <pre>{@code SpannableString string = new SpannableString("Text with quote span on a long line"); + *string.setSpan(new QuoteSpan(Color.GREEN, 20, 40), 0, string.length(), + *Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre> + * <img src="{@docRoot}reference/android/images/text/style/customquotespan.png" /> + * <figcaption>Customized <code>QuoteSpan</code>.</figcaption> + */ public class QuoteSpan implements LeadingMarginSpan, ParcelableSpan { - private static final int STRIPE_WIDTH = 2; - private static final int GAP_WIDTH = 2; + /** + * Default stripe width in pixels. + */ + public static final int STANDARD_STRIPE_WIDTH_PX = 2; + + /** + * Default gap width in pixels. + */ + public static final int STANDARD_GAP_WIDTH_PX = 2; + + /** + * Default color for the quote stripe. + */ + @ColorInt + public static final int STANDARD_COLOR = 0xff0000ff; + @ColorInt private final int mColor; - + @Px + private final int mStripeWidth; + @Px + private final int mGapWidth; + + /** + * Creates a {@link QuoteSpan} with the default values. + */ public QuoteSpan() { - super(); - mColor = 0xff0000ff; + this(STANDARD_COLOR, STANDARD_STRIPE_WIDTH_PX, STANDARD_GAP_WIDTH_PX); } + /** + * Creates a {@link QuoteSpan} based on a color. + * + * @param color the color of the quote stripe. + */ public QuoteSpan(@ColorInt int color) { - super(); + this(color, STANDARD_STRIPE_WIDTH_PX, STANDARD_GAP_WIDTH_PX); + } + + /** + * Creates a {@link QuoteSpan} based on a color, a stripe width and the width of the gap + * between the stripe and the text. + * + * @param color the color of the quote stripe. + * @param stripeWidth the width of the stripe. + * @param gapWidth the width of the gap between the stripe and the text. + */ + public QuoteSpan(@ColorInt int color, @IntRange(from = 0) int stripeWidth, + @IntRange(from = 0) int gapWidth) { mColor = color; + mStripeWidth = stripeWidth; + mGapWidth = gapWidth; } - public QuoteSpan(Parcel src) { + /** + * Create a {@link QuoteSpan} from a parcel. + */ + public QuoteSpan(@NonNull Parcel src) { mColor = src.readInt(); + mStripeWidth = src.readInt(); + mGapWidth = src.readInt(); } + @Override public int getSpanTypeId() { return getSpanTypeIdInternal(); } - /** @hide */ + /** + * @hide + */ + @Override public int getSpanTypeIdInternal() { return TextUtils.QUOTE_SPAN; } + @Override public int describeContents() { return 0; } + @Override public void writeToParcel(Parcel dest, int flags) { writeToParcelInternal(dest, flags); } - /** @hide */ + /** + * @hide + */ + @Override public void writeToParcelInternal(Parcel dest, int flags) { dest.writeInt(mColor); + dest.writeInt(mStripeWidth); + dest.writeInt(mGapWidth); } + /** + * Get the color of the quote stripe. + * + * @return the color of the quote stripe. + */ @ColorInt public int getColor() { return mColor; } + /** + * Get the width of the quote stripe. + * + * @return the width of the quote stripe. + */ + public int getStripeWidth() { + return mStripeWidth; + } + + /** + * Get the width of the gap between the stripe and the text. + * + * @return the width of the gap between the stripe and the text. + */ + public int getGapWidth() { + return mGapWidth; + } + + @Override public int getLeadingMargin(boolean first) { - return STRIPE_WIDTH + GAP_WIDTH; + return mStripeWidth + mGapWidth; } - public void drawLeadingMargin(Canvas c, Paint p, int x, int dir, - int top, int baseline, int bottom, - CharSequence text, int start, int end, - boolean first, Layout layout) { + @Override + public void drawLeadingMargin(@NonNull Canvas c, @NonNull Paint p, int x, int dir, + int top, int baseline, int bottom, + @NonNull CharSequence text, int start, int end, + boolean first, @NonNull Layout layout) { Paint.Style style = p.getStyle(); int color = p.getColor(); p.setStyle(Paint.Style.FILL); p.setColor(mColor); - c.drawRect(x, top, x + dir * STRIPE_WIDTH, bottom, p); + c.drawRect(x, top, x + dir * mStripeWidth, bottom, p); p.setStyle(style); p.setColor(color); diff --git a/docs/html/reference/images/text/style/customquotespan.png b/docs/html/reference/images/text/style/customquotespan.png Binary files differnew file mode 100644 index 000000000000..27f521a1b0d0 --- /dev/null +++ b/docs/html/reference/images/text/style/customquotespan.png diff --git a/docs/html/reference/images/text/style/defaultquotespan.png b/docs/html/reference/images/text/style/defaultquotespan.png Binary files differnew file mode 100644 index 000000000000..6c5a41f35e0b --- /dev/null +++ b/docs/html/reference/images/text/style/defaultquotespan.png |
