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

/**

 * Represents a push-button widget. Push-buttons can be

 * pressed, or clicked, by the user to perform an action.

 * <p>A typical use of a push-button in an activity would be the following:

 * </p>

 * A user interface element the user can tap or click to perform an action.

 *

 * <p>To display a button in an activity, add a button to the activity's layout XML file:</p>

 *

 * <pre>

 * <Button

 *     android:id="@+id/button_id"

 *     android:layout_height="wrap_content"

 *     android:layout_width="wrap_content"

 *     android:text="@string/self_destruct" /&gt;</pre>

 *

 * <p>To specify an action when the button is pressed, set a click

 * listener on the button object in the corresponding activity code:</p>

 *

 * <pre>

 * public class MyActivity extends Activity {

 *     protected void onCreate(Bundle icicle) {

 *         super.onCreate(icicle);

 *     protected void onCreate(Bundle savedInstanceState) {

 *         super.onCreate(savedInstanceState);

 *

 *         setContentView(R.layout.content_layout_id);

 *

 *         final Button button = findViewById(R.id.button_id);

 *         button.setOnClickListener(new View.OnClickListener() {

 *             public void onClick(View v) {

 *                 // Perform action on click

 *                 // Code here executes on main thread after user presses button

 *             }

 *         });

 *     }

 * }</pre>

 *

 * <p>However, instead of applying an {@link android.view.View.OnClickListener OnClickListener} to

 * the button in your activity, you can assign a method to your button in the XML layout,

 * using the {@link android.R.attr#onClick android:onClick} attribute. For example:</p>

 *

 * <pre>

 * <Button

 *     android:layout_height="wrap_content"

 *     android:layout_width="wrap_content"

 *     android:text="@string/self_destruct"

 *     android:onClick="selfDestruct" /&gt;</pre>

 *

 * <p>Now, when a user clicks the button, the Android system calls the activity's {@code

 * selfDestruct(View)} method. In order for this to work, the method must be public and accept

 * a {@link android.view.View} as its only parameter. For example:</p>

 *

 * <pre>

 * public void selfDestruct(View view) {

 *     // Kabloey

 * }</pre>

 *

 * <p>The {@link android.view.View} passed into the method is a reference to the widget

 * that was clicked.</p>

 * <p>The above snippet creates an instance of {@link View.OnClickListener} and wires

 * the listener to the button using

 * {@link #setOnClickListener setOnClickListener(View.OnClickListener)}.

 * As a result, the system executes the code you write in {@code onClick(View)} after the

 * user presses the button.</p>

 *

 * <h3>Button style</h3>

 * <p class="note">The system executes the code in {@code onClick} on the

 * <a href="{@docRoot}guide/components/processes-and-threads.html#Threads">main thread</a>.

 * This means your onClick code must execute quickly to avoid delaying your app's response

 * to further user actions.  See

 * <a href="{@docRoot}training/articles/perf-anr.html">Keeping Your App Responsive</a>

 * for more details.</p>

 *

 * <p>Every Button is styled using the system's default button background, which is often different

 * from one device to another and from one version of the platform to another. If you're not

 * satisfied with the default button style and want to customize it to match the design of your

 * application, then you can replace the button's background image with a <a

 * href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state list drawable</a>.

 * A state list drawable is a drawable resource defined in XML that changes its image based on

 * the current state of the button. Once you've defined a state list drawable in XML, you can apply

 * it to your Button with the {@link android.R.attr#background android:background}

 * attribute. For more information and an example, see <a

 * href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">State List

 * Drawable</a>.</p>

 *

 * <p>See the <a href="{@docRoot}guide/topics/ui/controls/button.html">Buttons</a>

 * <p>Every button is styled using the system's default button background, which is often

 * different from one version of the platform to another. If you are not satisfied with the

 * default button style, you can customize it. For more details and code samples, see the

 * <a href="{@docRoot}guide/topics/ui/controls/button.html#Style">Styling Your Button</a>

 * guide.</p>

 *

 * <p><strong>XML attributes</strong></p>

 * <p>

 * See {@link android.R.styleable#Button Button Attributes},

 * <p>For all XML style attributes available on Button see

 * {@link android.R.styleable#Button Button Attributes},

 * {@link android.R.styleable#TextView TextView Attributes},

 * {@link android.R.styleable#View View Attributes}

 * </p>

 * {@link android.R.styleable#View View Attributes}.  See the

 * {@link <a href="{@docRoot}guide/topics/ui/themes.html#ApplyingStyles">Styles and Themes</a>

 * guide to learn how to implement and organize overrides to style-related attributes.</p>

 *

 * @see

 * <a href="{@docRoot}guide/topics/ui/controls/button.html">Buttons Guide</a>

 * {@link android.R.styleable#Button Styleable Button Attributes},

 * {@link android.R.styleable#TextView Styleable TextView Attributes},

 * {@link android.R.styleable#View Styleable View Attributes},

 *

 */

@RemoteView

public class Button extends TextView {

    /**

     * Simple constructor to use when creating a button from code.

     *

     * @param context The Context the Button is running in, through which it can

     *        access the current theme, resources, etc.

     *

     * @see #Button(Context, AttributeSet)

     */

    public Button(Context context) {

        this(context, null);

    }

    /**

     * {@link LayoutInflater} calls this constructor when inflating a Button from XML.

     * The attributes defined by the current theme's

     * {@link android.R.attr#buttonStyle android:buttonStyle}

     * override base view attributes.

     *

     * You typically do not call this constructor to create your own button instance in code.

     * However, you must override this constructor when

     * <a href="{@docRoot}training/custom-views/index.html">creating custom views</a>.

     *

     * @param context The Context the view is running in, through which it can

     *        access the current theme, resources, etc.

     * @param attrs The attributes of the XML Button tag being used to inflate the view.

     *

     * @see #Button(Context, AttributeSet, int)

     * @see android.view.View#View(Context, AttributeSet)

     */

    public Button(Context context, AttributeSet attrs) {

        this(context, attrs, com.android.internal.R.attr.buttonStyle);

    }

    /**

     * This constructor allows a Button subclass to use its own class-specific base style from a

     * theme attribute when inflating. The attributes defined by the current theme's

     * {@code defStyleAttr} override base view attributes.

     *

     * <p>For Button's base view attributes see

     * {@link android.R.styleable#Button Button Attributes},

     * {@link android.R.styleable#TextView TextView Attributes},

     * {@link android.R.styleable#View View Attributes}.

     *

     * @param context The Context the Button is running in, through which it can

     *        access the current theme, resources, etc.

     * @param attrs The attributes of the XML Button tag that is inflating the view.

     * @param defStyleAttr The resource identifier of an attribute in the current theme

     *        whose value is the the resource id of a style. The specified style’s

     *        attribute values serve as default values for the button. Set this parameter

     *        to 0 to avoid use of default values.

     * @see #Button(Context, AttributeSet, int, int)

     * @see android.view.View#View(Context, AttributeSet, int)

     */

    public Button(Context context, AttributeSet attrs, int defStyleAttr) {

        this(context, attrs, defStyleAttr, 0);

    }

    /**

     * This constructor allows a Button subclass to use its own class-specific base style from

     * either a theme attribute or style resource when inflating. To see how the final value of a

     * particular attribute is resolved based on your inputs to this constructor, see

     * {@link android.view.View#View(Context, AttributeSet, int, int)}.

     *

     * @param context The Context the Button is running in, through which it can

     *        access the current theme, resources, etc.

     * @param attrs The attributes of the XML Button tag that is inflating the view.

     * @param defStyleAttr The resource identifier of an attribute in the current theme

     *        whose value is the the resource id of a style. The specified style’s

     *        attribute values serve as default values for the button. Set this parameter

     *        to 0 to avoid use of default values.

     * @param defStyleRes The identifier of a style resource that

     *        supplies default values for the button, used only if

     *        defStyleAttr is 0 or cannot be found in the theme.

     *        Set this parameter to 0 to avoid use of default values.

     *

     * @see #Button(Context, AttributeSet, int)

     * @see android.view.View#View(Context, AttributeSet, int, int)

     */

    public Button(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes) {

        super(context, attrs, defStyleAttr, defStyleRes);

    }