Merge "Update JavaDocs for Alignment, Clickable, Editable and MetricAffecting spans."

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());
         }
-        
-        public int getSpanTypeId() {
-        return getSpanTypeIdInternal();
-    }
 
-    /** @hide */
-    public int getSpanTypeIdInternal() {
+        @Override
+        public int getSpanTypeId() {
+            return 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;
     }
 }

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);
     }

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));
     }

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 {
-
-    public abstract void updateMeasureState(TextPaint p);
+        extends CharacterStyle
+        implements UpdateLayout {
 
     /**
-     * Returns "this" for most MetricAffectingSpans, but for 
+     * 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
      * 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.