Merge "Merge "Use SubscriptionId instead of SubId" am: 946410eef5 am: 9cad054e02 am: fb0acf3355" into oc-dev-plus-aosp
diff --git a/core/java/android/widget/ImageView.java b/core/java/android/widget/ImageView.java
index 7e6f2e4..57818e2 100644
--- a/core/java/android/widget/ImageView.java
+++ b/core/java/android/widget/ImageView.java
@@ -55,11 +55,31 @@
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>
+ * <LinearLayout
+ * xmlns:android="http://schemas.android.com/apk/res/android"
+ * android:layout_width="match_parent"
+ * android:layout_height="match_parent">
+ * <ImageView
+ * android:layout_width="wrap_content"
+ * android:layout_height="wrap_content"
+ * android:src="@mipmap/ic_launcher"
+ * />
+ * </LinearLayout>
+ * </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 @@
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 @@
/**
* 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 @@
/**
* 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 @@
}
/**
+ * 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 @@
}
/**
- * @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 @@
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 @@
}
/**
- * 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 @@
* 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
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);
}
diff --git a/core/java/android/widget/TextView.java b/core/java/android/widget/TextView.java
index 16a31f1..92c16af 100644
--- a/core/java/android/widget/TextView.java
+++ b/core/java/android/widget/TextView.java
@@ -178,18 +178,43 @@
import java.util.Locale;
/**
- * Displays text to the user and optionally allows them to edit it. A TextView
- * is a complete text editor, however the basic class is configured to not
- * allow editing; see {@link EditText} for a subclass that configures the text
- * view for editing.
- *
+ * A user interface element that displays text to the user.
+ * To provide user-editable text, see {@link EditText}.
* <p>
- * To allow users to copy some or all of the TextView's value and paste it somewhere else, set the
- * XML attribute {@link android.R.styleable#TextView_textIsSelectable
- * android:textIsSelectable} to "true" or call
- * {@link #setTextIsSelectable setTextIsSelectable(true)}. The {@code textIsSelectable} flag
- * allows users to make selection gestures in the TextView, which in turn triggers the system's
- * built-in copy/paste controls.
+ * The following code sample shows a typical use, with an XML layout
+ * and code to modify the contents of the text view:
+ * </p>
+
+ * <pre>
+ * <LinearLayout
+ xmlns:android="http://schemas.android.com/apk/res/android"
+ android:layout_width="match_parent"
+ android:layout_height="match_parent">
+ * <TextView
+ * android:id="@+id/text_view_id"
+ * android:layout_height="wrap_content"
+ * android:layout_width="wrap_content"
+ * android:text="@string/hello" />
+ * </LinearLayout>
+ * </pre>
+ * <p>
+ * This code sample demonstrates how to modify the contents of the text view
+ * defined in the previous XML layout:
+ * </p>
+ * <pre>
+ * public class MainActivity extends Activity {
+ *
+ * protected void onCreate(Bundle savedInstanceState) {
+ * super.onCreate(savedInstanceState);
+ * setContentView(R.layout.activity_main);
+ * final TextView helloTextView = (TextView) findViewById(R.id.text_view_id);
+ * helloTextView.setText(R.string.user_greeting);
+ * }
+ * }
+ * </pre>
+ * <p>
+ * To customize the appearance of TextView, see <a href="https://developer.android.com/guide/topics/ui/themes.html">Styles and Themes</a>.
+ * </p>
* <p>
* <b>XML attributes</b>
* <p>
@@ -674,7 +699,7 @@
int mTextEditSuggestionHighlightStyle;
/**
- * EditText specific data, created on demand when one of the Editor fields is used.
+ * {@link EditText} specific data, created on demand when one of the Editor fields is used.
* See {@link #createEditorIfNeeded()}.
*/
private Editor mEditor;
@@ -2172,10 +2197,11 @@
* with an argument of {@link android.widget.TextView.BufferType#SPANNABLE BufferType.SPANNABLE}
* or {@link android.widget.TextView.BufferType#EDITABLE BufferType.EDITABLE}, you can cast
* the return value from this method to Spannable or Editable, respectively.
- * <p/>
- * The content of the return value should not be modified. If you want a modifiable one, you
- * should make your own copy first.
*
+ * <p>The content of the return value should not be modified. If you want a modifiable one, you
+ * should make your own copy first.</p>
+ *
+ * @return The text displayed by the text view.
* @attr ref android.R.styleable#TextView_text
*/
@ViewDebug.CapturedViewProperty
@@ -2185,6 +2211,7 @@
/**
* Returns the length, in characters, of the text managed by this TextView
+ * @return The length of the text managed by the TextView in characters.
*/
public int length() {
return mText.length();
@@ -2201,26 +2228,28 @@
}
/**
- * @return the height of one standard line in pixels. Note that markup
- * within the text can cause individual lines to be taller or shorter
- * than this height, and the layout may contain additional first-
- * or last-line padding.
+ * Gets the vertical distance between lines of text, in pixels.
+ * Note that markup within the text can cause individual lines
+ * to be taller or shorter than this height, and the layout may
+ * contain additional first-or last-line padding.
+ * @return The height of one standard line in pixels.
*/
public int getLineHeight() {
return FastMath.round(mTextPaint.getFontMetricsInt(null) * mSpacingMult + mSpacingAdd);
}
/**
- * @return the Layout that is currently being used to display the text.
- * This can be null if the text or width has recently changes.
+ * Gets the {@link android.text.Layout} that is currently being used to display the text.
+ * This value can be null if the text or width has recently changed.
+ * @return The Layout that is currently being used to display the text.
*/
public final Layout getLayout() {
return mLayout;
}
/**
- * @return the Layout that is currently being used to display the hint text.
- * This can be null.
+ * @return the {@link android.text.Layout} that is currently being used to
+ * display the hint text. This can be null.
*/
final Layout getHintLayout() {
return mHintLayout;
@@ -2272,8 +2301,9 @@
}
/**
- * @return the current key listener for this TextView.
+ * Gets the current {@link KeyListener} for the TextView.
* This will frequently be null for non-EditText TextViews.
+ * @return the current key listener for this TextView.
*
* @attr ref android.R.styleable#TextView_numeric
* @attr ref android.R.styleable#TextView_digits
@@ -2350,17 +2380,20 @@
}
/**
- * @return the movement method being used for this TextView.
+ * Gets the {@link android.text.method.MovementMethod} being used for this TextView,
+ * which provides positioning, scrolling, and text selection functionality.
* This will frequently be null for non-EditText TextViews.
+ * @return the movement method being used for this TextView.
+ * @see android.text.method.MovementMethod
*/
public final MovementMethod getMovementMethod() {
return mMovement;
}
/**
- * Sets the movement method (arrow key handler) to be used for
- * this TextView. This can be null to disallow using the arrow keys
- * to move the cursor or scroll the view.
+ * Sets the {@link android.text.method.MovementMethod} for handling arrow key movement
+ * for this TextView. This can be null to disallow using the arrow keys to move the
+ * cursor or scroll the view.
* <p>
* Be warned that if you want a TextView with a key listener or movement
* method not to be focusable, or if you want a TextView without a
@@ -2397,9 +2430,9 @@
}
/**
+ * Gets the current {@link android.text.method.TransformationMethod} for the TextView.
+ * This is frequently null, except for single-line and password fields.
* @return the current transformation method for this TextView.
- * This will frequently be null except for single-line and password
- * fields.
*
* @attr ref android.R.styleable#TextView_password
* @attr ref android.R.styleable#TextView_singleLine
@@ -3432,8 +3465,8 @@
}
/**
- * Set the default {@link LocaleList} of the text in this TextView to a one-member list
- * containing just the given value.
+ * Set the default {@link Locale} of the text in this TextView to a one-member
+ * {@link LocaleList} containing just the given Locale.
*
* @param locale the {@link Locale} for drawing text, must not be null.
*
@@ -3492,7 +3525,7 @@
}
/**
- * @return the size (in scaled pixels) of thee default text size in this TextView.
+ * @return the size (in scaled pixels) of the default text size in this TextView.
* @hide
*/
@ViewDebug.ExportedProperty(category = "text")
@@ -3574,16 +3607,19 @@
}
/**
- * @return the extent by which text is currently being stretched
- * horizontally. This will usually be 1.
+ * Gets the extent by which text should be stretched horizontally.
+ * This will usually be 1.0.
+ * @return The horizontal scale factor.
*/
public float getTextScaleX() {
return mTextPaint.getTextScaleX();
}
/**
- * Sets the extent by which text should be stretched horizontally.
- *
+ * Sets the horizontal scale factor for text. The default value
+ * is 1.0. Values greater than 1.0 stretch the text wider.
+ * Values less than 1.0 make the text narrower. By default, this value is 1.0.
+ * @param size The horizontal scale factor.
* @attr ref android.R.styleable#TextView_textScaleX
*/
@android.view.RemotableViewMethod
@@ -3626,8 +3662,8 @@
}
/**
- * @return the current typeface and style in which the text is being
- * displayed.
+ * Gets the current {@link Typeface} that is used to style the text.
+ * @return The current Typeface.
*
* @see #setTypeface(Typeface)
*
@@ -3660,8 +3696,9 @@
}
/**
- * @return the extent by which text is currently being letter-spaced.
- * This will normally be 0.
+ * Gets the text letter-space value, which determines the spacing between characters.
+ * The value returned is in ems. Normally, this value is 0.0.
+ * @return The text letter-space value in ems.
*
* @see #setLetterSpacing(float)
* @see Paint#setLetterSpacing
@@ -3671,12 +3708,13 @@
}
/**
- * Sets text letter-spacing. The value is in 'EM' units. Typical values
+ * Sets text letter-spacing in em units. Typical values
* for slight expansion will be around 0.05. Negative values tighten text.
*
* @see #getLetterSpacing()
* @see Paint#getLetterSpacing
*
+ * @param letterSpacing A text letter-space value in ems.
* @attr ref android.R.styleable#TextView_letterSpacing
*/
@android.view.RemotableViewMethod
@@ -3741,7 +3779,8 @@
}
/**
- * @return the currently set break strategy.
+ * Gets the current strategy for breaking paragraphs into lines.
+ * @return the current strategy for breaking paragraphs into lines.
*
* @attr ref android.R.styleable#TextView_breakStrategy
* @see #setBreakStrategy(int)
@@ -3752,9 +3791,12 @@
}
/**
- * Sets the hyphenation frequency. The default value for both TextView and EditText, which is
- * set from the theme, is {@link Layout#HYPHENATION_FREQUENCY_NORMAL}.
+ * Sets the frequency of automatic hyphenation to use when determining word breaks.
+ * The default value for both TextView and {@link EditText} is
+ * {@link Layout#HYPHENATION_FREQUENCY_NORMAL}.
+ * Note that the default hyphenation frequency value is set from the theme.
*
+ * @param hyphenationFrequency The hyphenation frequency to use.
* @attr ref android.R.styleable#TextView_hyphenationFrequency
* @see #getHyphenationFrequency()
*/
@@ -3768,7 +3810,9 @@
}
/**
- * @return the currently set hyphenation frequency.
+ * Gets the current frequency of automatic hyphenation to be used when determining word breaks.
+ * @return the current frequency of automatic hyphenation to be used when determining word
+ * breaks.
*
* @attr ref android.R.styleable#TextView_hyphenationFrequency
* @see #setHyphenationFrequency(int)
@@ -3927,7 +3971,7 @@
}
/**
- * <p>Return the current color selected for normal text.</p>
+ * Return the current color selected for normal text.
*
* @return Returns the current text color.
*/
@@ -4037,7 +4081,8 @@
}
/**
- * @return the vertical offset of the shadow layer
+ * Gets the vertical offset of the shadow layer.
+ * @return The vertical offset of the shadow layer.
*
* @see #setShadowLayer(float, float, float, int)
*
@@ -4048,6 +4093,7 @@
}
/**
+ * Gets the color of the shadow layer.
* @return the color of the shadow layer
*
* @see #setShadowLayer(float, float, float, int)
@@ -4060,8 +4106,9 @@
}
/**
- * @return the base paint used for the text. Please use this only to
- * consult the Paint's properties and not to change them.
+ * Gets the {@link TextPaint} used for the text.
+ * Use this only to consult the Paint's properties and not to change them.
+ * @return The base paint used for the text.
*/
public TextPaint getPaint() {
return mTextPaint;
@@ -4105,7 +4152,7 @@
}
/**
- * Returns the list of URLSpans attached to the text
+ * Returns the list of {@link android.text.style.URLSpan URLSpans} attached to the text
* (by {@link Linkify} or otherwise) if any. You can call
* {@link URLSpan#getURL} on them to find where they link to
* or use {@link Spanned#getSpanStart} and {@link Spanned#getSpanEnd}
@@ -4266,7 +4313,8 @@
}
/**
- * @return the flags on the Paint being used to display the text.
+ * Gets the flags on the Paint being used to display the text.
+ * @return The flags on the Paint being used to display the text.
* @see Paint#getFlags
*/
public int getPaintFlags() {
@@ -5691,8 +5739,8 @@
/**
* Change the editor type integer associated with the text view, which
- * will be reported to an IME with {@link EditorInfo#imeOptions} when it
- * has focus.
+ * is reported to an Input Method Editor (IME) with {@link EditorInfo#imeOptions}
+ * when it has focus.
* @see #getImeOptions
* @see android.view.inputmethod.EditorInfo
* @attr ref android.R.styleable#TextView_imeOptions
@@ -5704,8 +5752,8 @@
}
/**
- * Get the type of the IME editor.
- *
+ * Get the type of the Input Method Editor (IME).
+ * @return the type of the IME
* @see #setImeOptions(int)
* @see android.view.inputmethod.EditorInfo
*/
@@ -7532,7 +7580,7 @@
/**
* Called by the framework in response to a text auto-correction (such as fixing a typo using a
- * a dictionary) from the current input method, provided by it calling
+ * dictionary) from the current input method, provided by it calling
* {@link InputConnection#commitCorrection(CorrectionInfo) InputConnection.commitCorrection()}.
* The default implementation flashes the background of the corrected word to provide
* feedback to the user.
@@ -9636,6 +9684,11 @@
return super.onTrackballEvent(event);
}
+ /**
+ * Sets the Scroller used for producing a scrolling animation
+ *
+ * @param s A Scroller instance
+ */
public void setScroller(Scroller s) {
mScroller = s;
}
@@ -10581,6 +10634,7 @@
/**
* Returns whether this text view is a current input method target. The
* default implementation just checks with {@link InputMethodManager}.
+ * @return True if the TextView is a current input method target; false otherwise.
*/
public boolean isInputMethodTarget() {
InputMethodManager imm = InputMethodManager.peekInstance();