Merge "docs: Update TextView JavaDoc comments" into oc-dev am: 28973b38

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>

 * 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>

 * 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.

 * 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>

    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;

     * 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

    /**

     * 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();

    }

    /**

     * @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;

    }

    /**

     * @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

    }

    /**

     * @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

    }

    /**

     * 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

    }

    /**

     * 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.

     *

    }

    /**

     * @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")

    }

    /**

     * @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

    }

    /**

     * @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)

     *

    }

    /**

     * @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

    }

    /**

     * 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

    }

    /**

     * @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)

    }

    /**

     * 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()

     */

    }

    /**

     * @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)

    }

    /**

     * <p>Return the current color selected for normal text.</p>

     * Return the current color selected for normal text.

     *

     * @return Returns the current text color.

     */

    }

    /**

     * @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)

     *

    }

    /**

     * Gets the color of the shadow layer.

     * @return the color of the shadow layer

     *

     * @see #setShadowLayer(float, float, float, int)

    }

    /**

     * @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;

    }

    /**

     * 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}

    }

    /**

     * @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() {

    /**

     * 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

    }

    /**

     * 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

     */

    /**

     * 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.

        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;

    }

    /**

     * 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();