Merge "docs: Update Imageview JavaDoc comments" into oc-dev

core/java/android/widget/ImageView.java

@@ -55,11 +55,31 @@ import java.io.IOException;
 import java.io.InputStream;
 
 /**
- * Displays an arbitrary image, such as an icon.  The ImageView class
- * can load images from various sources (such as resources or content
- * providers), takes care of computing its measurement from the image so that
- * it can be used in any layout manager, and provides various display options
- * such as scaling and tinting.
+ * Displays image resources, for example {@link android.graphics.Bitmap}
+ * or {@link android.graphics.drawable.Drawable} resources.
+ * ImageView is also commonly used to {@link #setImageTintMode(PorterDuff.Mode)
+ * apply tints to an image} and handle {@link #setScaleType(ScaleType) image scaling}.
+ *
+ * <p>
+ * The following XML snippet is a common example of using an ImageView to display an image resource:
+ * </p>
+ * <pre>
+ * &lt;LinearLayout
+ *     xmlns:android="http://schemas.android.com/apk/res/android"
+ *     android:layout_width="match_parent"
+ *     android:layout_height="match_parent"&gt;
+ *     &lt;ImageView
+ *         android:layout_width="wrap_content"
+ *         android:layout_height="wrap_content"
+ *         android:src="@mipmap/ic_launcher"
+ *         /&gt;
+ * &lt;/LinearLayout&gt;
+ * </pre>
+ *
+ * <p>
+ * To learn more about Drawables, see: <a href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.
+ * To learn more about working with Bitmaps, see: <a href="{@docRoot}topic/performance/graphics/index.htm">Handling Bitmaps</a>.
+ * </p>
  *
  * @attr ref android.R.styleable#ImageView_adjustViewBounds
  * @attr ref android.R.styleable#ImageView_src
@@ -395,9 +415,13 @@ public class ImageView extends View {
         mMaxHeight = maxHeight;
     }
 
-    /** Return the view's drawable, or null if no drawable has been
-        assigned.
-    */
+    /**
+     * Gets the current Drawable, or null if no Drawable has been
+     * assigned.
+     *
+     * @return the view's drawable, or null if no drawable has been
+     * assigned.
+     */
     public Drawable getDrawable() {
         if (mDrawable == mRecycleableBitmapDrawable) {
             // Consider our cached version dirty since app code now has a reference to it
@@ -428,7 +452,6 @@ public class ImageView extends View {
 
     /**
      * Sets a drawable as the content of this ImageView.
-     *
      * <p class="note">This does Bitmap reading and decoding on the UI
      * thread, which can cause a latency hiccup.  If that's a concern,
      * consider using {@link #setImageDrawable(android.graphics.drawable.Drawable)} or
@@ -474,7 +497,10 @@ public class ImageView extends View {
 
     /**
      * Sets the content of this ImageView to the specified Uri.
-     *
+     * Note that you use this method to load images from a local Uri only.
+     * <p/>
+     * To learn how to display images from a remote Uri see: <a href="https://developer.android.com/topic/performance/graphics/index.html">Handling Bitmaps</a>
+     * <p/>
      * <p class="note">This does Bitmap reading and decoding on the UI
      * thread, which can cause a latency hiccup.  If that's a concern,
      * consider using {@link #setImageDrawable(Drawable)} or
@@ -598,6 +624,9 @@ public class ImageView extends View {
     }
 
     /**
+     * Get the current {@link android.content.res.ColorStateList} used to tint the image Drawable,
+     * or null if no tint is applied.
+     *
      * @return the tint applied to the image drawable
      * @attr ref android.R.styleable#ImageView_tint
      * @see #setImageTintList(ColorStateList)
@@ -626,7 +655,8 @@ public class ImageView extends View {
     }
 
     /**
-     * @return the blending mode used to apply the tint to the image drawable
+     * Gets the blending mode used to apply the tint to the image Drawable
+     * @return the blending mode used to apply the tint to the image Drawable
      * @attr ref android.R.styleable#ImageView_tintMode
      * @see #setImageTintMode(PorterDuff.Mode)
      */
@@ -673,6 +703,13 @@ public class ImageView extends View {
         setImageDrawable(mRecycleableBitmapDrawable);
     }
 
+    /**
+     * Set the state of the current {@link android.graphics.drawable.StateListDrawable}.
+     * For more information about State List Drawables, see: <a href="https://developer.android.com/guide/topics/resources/drawable-resource.html#StateList">the Drawable Resource Guide</a>.
+     *
+     * @param state the state to set for the StateListDrawable
+     * @param merge if true, merges the state values for the state you specify into the current state
+     */
     public void setImageState(int[] state, boolean merge) {
         mState = state;
         mMergeState = merge;
@@ -786,17 +823,16 @@ public class ImageView extends View {
     }
 
     /**
-     * Return the current scale type in use by this ImageView.
-     *
+     * Returns the current ScaleType that is used to scale the bounds of an image to the bounds of the ImageView.
+     * @return The ScaleType used to scale the image.
      * @see ImageView.ScaleType
-     *
      * @attr ref android.R.styleable#ImageView_scaleType
      */
     public ScaleType getScaleType() {
         return mScaleType;
     }
 
-    /** Return the view's optional matrix. This is applied to the
+    /** Returns the view's optional matrix. This is applied to the
         view's drawable when it is drawn. If there is no matrix,
         this method will return an identity matrix.
         Do not change this matrix in place but make a copy.
@@ -815,7 +851,7 @@ public class ImageView extends View {
      * to the view's drawable when it is drawn.  Allows custom scaling,
      * translation, and perspective distortion.
      *
-     * @param matrix the transformation parameters in matrix form
+     * @param matrix The transformation parameters in matrix form.
      */
     public void setImageMatrix(Matrix matrix) {
         // collapse null and identity to just null
@@ -1367,11 +1403,10 @@ public class ImageView extends View {
     }
 
     /**
-     * Set whether to set the baseline of this view to the bottom of the view.
+     * Sets whether the baseline of this view to the bottom of the view.
      * Setting this value overrides any calls to setBaseline.
      *
-     * @param aligned If true, the image view will be baseline aligned with
-     *      based on its bottom edge.
+     * @param aligned If true, the image view will be baseline aligned by its bottom edge.
      *
      * @attr ref android.R.styleable#ImageView_baselineAlignBottom
      */
@@ -1383,8 +1418,9 @@ public class ImageView extends View {
     }
 
     /**
-     * Return whether this view's baseline will be considered the bottom of the view.
+     * Checks whether this view's baseline is considered the bottom of the view.
      *
+     * @return True if the ImageView's baseline is considered the bottom of the view, false if otherwise.
      * @see #setBaselineAlignBottom(boolean)
      */
     public boolean getBaselineAlignBottom() {
@@ -1392,7 +1428,7 @@ public class ImageView extends View {
     }
 
     /**
-     * Set a tinting option for the image.
+     * Sets a tinting option for the image.
      *
      * @param color Color tint to apply.
      * @param mode How to apply the color.  The standard mode is
@@ -1416,6 +1452,12 @@ public class ImageView extends View {
         setColorFilter(color, PorterDuff.Mode.SRC_ATOP);
     }
 
+    /**
+     * Removes the image's {@link android.graphics.ColorFilter}.
+     *
+     * @see #setColorFilter(int)
+     * @see #getColorFilter()
+     */
     public final void clearColorFilter() {
         setColorFilter(null);
     }