diff --git a/api/current.txt b/api/current.txt
index 7c7c11b0b9fa72e4198e454d9d939901d50c15d7..d44b7d7d6505037fd0109cce35d8a263d5f55eee 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -43313,13 +43313,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 7217e1e5efa86ff0a73417fd3da42692c8cd27c3..a1c12c256fa1f02295e17f0df1b35fc07709d569 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
new file mode 100644
index 0000000000000000000000000000000000000000..27f521a1b0d0d79bde1d0725adde3da9de58d657
Binary files /dev/null and b/docs/html/reference/images/text/style/customquotespan.png differ
diff --git a/docs/html/reference/images/text/style/defaultquotespan.png b/docs/html/reference/images/text/style/defaultquotespan.png
new file mode 100644
index 0000000000000000000000000000000000000000..6c5a41f35e0b26944f697d4a74dc8536ee01988c
Binary files /dev/null and b/docs/html/reference/images/text/style/defaultquotespan.png differ