diff --git a/core/java/android/text/style/AlignmentSpan.java b/core/java/android/text/style/AlignmentSpan.java
index 615830949ed3e936c0721b25690972e81472a407..18c3e16b910ab468a5e3b44f4d8c9db52195f99c 100644
--- a/core/java/android/text/style/AlignmentSpan.java
+++ b/core/java/android/text/style/AlignmentSpan.java
@@ -16,49 +16,90 @@
package android.text.style;
+import android.annotation.NonNull;
import android.os.Parcel;
import android.text.Layout;
import android.text.ParcelableSpan;
import android.text.TextUtils;
+/**
+ * Span that allows defining the alignment of text at the paragraph level.
+ */
public interface AlignmentSpan extends ParagraphStyle {
+
+ /**
+ * Returns the alignment of the text.
+ *
+ * @return the text alignment
+ */
Layout.Alignment getAlignment();
+ /**
+ * Default implementation of the {@link AlignmentSpan}.
+ * <p>
+ * For example, a text written in a left to right language, like English, which is by default
+ * aligned to the left, can be aligned opposite to the layout direction like this:
+ * <pre>{@code SpannableString string = new SpannableString("Text with opposite alignment");
+ *string.setSpan(new AlignmentSpan.Standard(Layout.Alignment.ALIGN_OPPOSITE), 0,
+ *string.length(), Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre>
+ * <img src="{@docRoot}reference/android/images/text/style/ltralignmentspan.png" />
+ * <figcaption>Align left to right text opposite to the layout direction.</figcaption>
+ * <p>
+ * A text written in a right to left language, like Hebrew, which is by default aligned to the
+ * right, can be aligned opposite to the layout direction like this:
+ * <pre>{@code SpannableString string = new SpannableString("טקסט ×¢× ×™×™×©×•×¨ הפוך");
+ *string.setSpan(new AlignmentSpan.Standard(Layout.Alignment.ALIGN_OPPOSITE), 0,
+ *string.length(), Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre>
+ * <img src="{@docRoot}reference/android/images/text/style/rtlalignmentspan.png" />
+ * <figcaption>Align right to left text opposite to the layout direction.</figcaption>
+ */
class Standard implements AlignmentSpan, ParcelableSpan {
- public Standard(Layout.Alignment align) {
+ private final Layout.Alignment mAlignment;
+
+ /**
+ * Constructs a {@link Standard} from an alignment.
+ */
+ public Standard(@NonNull Layout.Alignment align) {
mAlignment = align;
}
- public Standard(Parcel src) {
+ /**
+ * Constructs a {@link Standard} from a parcel.
+ */
+ public Standard(@NonNull Parcel src) {
mAlignment = Layout.Alignment.valueOf(src.readString());
}
-
+
+ @Override
public int getSpanTypeId() {
- return getSpanTypeIdInternal();
- }
+ return getSpanTypeIdInternal();
+ }
- /** @hide */
- public int getSpanTypeIdInternal() {
+ /** @hide */
+ @Override
+ public int getSpanTypeIdInternal() {
return TextUtils.ALIGNMENT_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.writeString(mAlignment.name());
}
+ @Override
public Layout.Alignment getAlignment() {
return mAlignment;
}
-
- private final Layout.Alignment mAlignment;
}
}
diff --git a/core/java/android/text/style/ClickableSpan.java b/core/java/android/text/style/ClickableSpan.java
index b098f16da1eda1c969af339534a8dd56aad70451..60aed2a782ab3227b9aedb1a9f8fd3322b4198d6 100644
--- a/core/java/android/text/style/ClickableSpan.java
+++ b/core/java/android/text/style/ClickableSpan.java
@@ -16,6 +16,7 @@
package android.text.style;
+import android.annotation.NonNull;
import android.text.TextPaint;
import android.view.View;
@@ -24,6 +25,16 @@ import android.view.View;
* with a movement method of LinkMovementMethod, the affected spans of
* text can be selected. If selected and clicked, the {@link #onClick} method will
* be called.
+ * <p>
+ * The text with a <code>ClickableSpan</code> attached will be underlined and the link color will be
+ * used as a text color. The default link color is the theme's accent color or
+ * <code>android:textColorLink</code> if this attribute is defined in the theme.
+ * For example, considering that we have a <code>CustomClickableSpan</code> that extends
+ * <code>ClickableSpan</code>, it can be used like this:
+ * <pre>{@code SpannableString string = new SpannableString("Text with clickable text");
+ *string.setSpan(new CustomClickableSpan(), 10, 19, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);}</pre>
+ * <img src="{@docRoot}reference/android/images/text/style/clickablespan.png" />
+ * <figcaption>Text with <code>ClickableSpan</code>.</figcaption>
*/
public abstract class ClickableSpan extends CharacterStyle implements UpdateAppearance {
private static int sIdCounter = 0;
@@ -33,13 +44,13 @@ public abstract class ClickableSpan extends CharacterStyle implements UpdateAppe
/**
* Performs the click action associated with this span.
*/
- public abstract void onClick(View widget);
+ public abstract void onClick(@NonNull View widget);
/**
* Makes the text underlined and in the link color.
*/
@Override
- public void updateDrawState(TextPaint ds) {
+ public void updateDrawState(@NonNull TextPaint ds) {
ds.setColor(ds.linkColor);
ds.setUnderlineText(true);
}
diff --git a/core/java/android/text/style/EasyEditSpan.java b/core/java/android/text/style/EasyEditSpan.java
index 7af1c2c8960070dc0ce24115c0e6a7b9dae07fc8..9ee0b074459e0e85bfb97fd609422ab8a35c078a 100644
--- a/core/java/android/text/style/EasyEditSpan.java
+++ b/core/java/android/text/style/EasyEditSpan.java
@@ -16,6 +16,7 @@
package android.text.style;
+import android.annotation.NonNull;
import android.app.PendingIntent;
import android.os.Parcel;
import android.text.ParcelableSpan;
@@ -79,7 +80,7 @@ public class EasyEditSpan implements ParcelableSpan {
/**
* Constructor called from {@link TextUtils} to restore the span.
*/
- public EasyEditSpan(Parcel source) {
+ public EasyEditSpan(@NonNull Parcel source) {
mPendingIntent = source.readParcelable(null);
mDeleteEnabled = (source.readByte() == 1);
}
@@ -90,12 +91,12 @@ public class EasyEditSpan implements ParcelableSpan {
}
@Override
- public void writeToParcel(Parcel dest, int flags) {
+ public void writeToParcel(@NonNull Parcel dest, int flags) {
writeToParcelInternal(dest, flags);
}
/** @hide */
- public void writeToParcelInternal(Parcel dest, int flags) {
+ public void writeToParcelInternal(@NonNull Parcel dest, int flags) {
dest.writeParcelable(mPendingIntent, 0);
dest.writeByte((byte) (mDeleteEnabled ? 1 : 0));
}
diff --git a/core/java/android/text/style/MetricAffectingSpan.java b/core/java/android/text/style/MetricAffectingSpan.java
index 853ecc6e8f4961302ce4004d62c3dfb74bb9212d..61b7947af6389d0d70dc900b140fc19ab6e90310 100644
--- a/core/java/android/text/style/MetricAffectingSpan.java
+++ b/core/java/android/text/style/MetricAffectingSpan.java
@@ -16,6 +16,7 @@
package android.text.style;
+import android.annotation.NonNull;
import android.text.TextPaint;
/**
@@ -23,13 +24,19 @@ import android.text.TextPaint;
* changes the width or height of characters extend this class.
*/
public abstract class MetricAffectingSpan
-extends CharacterStyle
-implements UpdateLayout {
+ extends CharacterStyle
+ implements UpdateLayout {
- public abstract void updateMeasureState(TextPaint p);
+ /**
+ * Classes that extend MetricAffectingSpan implement this method to update the text formatting
+ * in a way that can change the width or height of characters.
+ *
+ * @param textPaint the paint used for drawing the text
+ */
+ public abstract void updateMeasureState(@NonNull TextPaint textPaint);
/**
- * Returns "this" for most MetricAffectingSpans, but for
+ * Returns "this" for most MetricAffectingSpans, but for
* MetricAffectingSpans that were generated by {@link #wrap},
* returns the underlying MetricAffectingSpan.
*/
@@ -41,18 +48,18 @@ implements UpdateLayout {
/**
* A Passthrough MetricAffectingSpan is one that
* passes {@link #updateDrawState} and {@link #updateMeasureState}
- * calls through to the specified MetricAffectingSpan
+ * calls through to the specified MetricAffectingSpan
* while still being a distinct object,
* and is therefore able to be attached to the same Spannable
* to which the specified MetricAffectingSpan is already attached.
*/
/* package */ static class Passthrough extends MetricAffectingSpan {
private MetricAffectingSpan mStyle;
-
+
/**
* Creates a new Passthrough of the specfied MetricAffectingSpan.
*/
- public Passthrough(MetricAffectingSpan cs) {
+ Passthrough(@NonNull MetricAffectingSpan cs) {
mStyle = cs;
}
@@ -60,7 +67,7 @@ implements UpdateLayout {
* Passes updateDrawState through to the underlying MetricAffectingSpan.
*/
@Override
- public void updateDrawState(TextPaint tp) {
+ public void updateDrawState(@NonNull TextPaint tp) {
mStyle.updateDrawState(tp);
}
@@ -68,10 +75,10 @@ implements UpdateLayout {
* Passes updateMeasureState through to the underlying MetricAffectingSpan.
*/
@Override
- public void updateMeasureState(TextPaint tp) {
+ public void updateMeasureState(@NonNull TextPaint tp) {
mStyle.updateMeasureState(tp);
}
-
+
/**
* Returns the MetricAffectingSpan underlying this one, or the one
* underlying it if it too is a Passthrough.
diff --git a/docs/html/reference/images/text/style/clickablespan.png b/docs/html/reference/images/text/style/clickablespan.png
new file mode 100644
index 0000000000000000000000000000000000000000..8e3e6bfc6b5c74ac399246d51cad1d08e930fece
Binary files /dev/null and b/docs/html/reference/images/text/style/clickablespan.png differ
diff --git a/docs/html/reference/images/text/style/ltralignmentspan.png b/docs/html/reference/images/text/style/ltralignmentspan.png
new file mode 100644
index 0000000000000000000000000000000000000000..6ee5943da235b99fd82fe351b837e5b880208696
Binary files /dev/null and b/docs/html/reference/images/text/style/ltralignmentspan.png differ
diff --git a/docs/html/reference/images/text/style/rtlalignmentspan.png b/docs/html/reference/images/text/style/rtlalignmentspan.png
new file mode 100644
index 0000000000000000000000000000000000000000..952258ded842e7178eb9bf1cbad86f0cbbed5835
Binary files /dev/null and b/docs/html/reference/images/text/style/rtlalignmentspan.png differ