From 8e342c7b75fc8a9b9f35e9c6453ca731af7f27f5 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Mon, 24 Apr 2017 11:59:54 -0700 Subject: docs: Update Button JavaDoc comments - Simplify first-line description - Update top-level code sample - Add caveat about onClick running on main thread - Simplify button style discussion - Add distinct See Also section - Convert future tense to present tense - Add closing paragraph tags - Remove references to push-button - Clean up code introduction sentence - Use present tense - Connect reasoning to user experience - Format threading information as aside - Change future tense to present tense - Add transition statement - Use active language in parameter description - Use cannot instead of can not - Use common parlance name for button - Clean up parameter descriptions Test: Docs change only. Tested with a doc build run. Change-Id: Ie0cd25ed4f8372ba5ec58bdf8b7dfce9100ee3fc --- core/java/android/widget/Button.java | 159 ++++++++++++++++++++++++----------- 1 file changed, 110 insertions(+), 49 deletions(-) diff --git a/core/java/android/widget/Button.java b/core/java/android/widget/Button.java index 09ba553cbf3e..452ff17ee3d9 100644 --- a/core/java/android/widget/Button.java +++ b/core/java/android/widget/Button.java @@ -24,89 +24,150 @@ import android.widget.RemoteViews.RemoteView; /** - * Represents a push-button widget. Push-buttons can be - * pressed, or clicked, by the user to perform an action. - - *

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

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

To display a button in an activity, add a button to the activity's layout XML file:

+ * + * 
+ * <Button
+ *     android:id="@+id/button_id"
+ *     android:layout_height="wrap_content"
+ *     android:layout_width="wrap_content"
+ *     android:text="@string/self_destruct" />
+ * + *

To specify an action when the button is pressed, set a click + * listener on the button object in the corresponding activity code:

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

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:

- * - * 
- * <Button
- *     android:layout_height="wrap_content"
- *     android:layout_width="wrap_content"
- *     android:text="@string/self_destruct"
- *     android:onClick="selfDestruct" />
- * - *

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:

- * - * 
- * public void selfDestruct(View view) {
- *     // Kabloey
- * }
- * - *

The {@link android.view.View} passed into the method is a reference to the widget - * that was clicked.

- * - *

Button style

+ *

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.

* - *

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 state list drawable. - * 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 State List - * Drawable.

+ *

The system executes the code in {@code onClick} on the + * main thread. + * This means your onClick code must execute quickly to avoid delaying your app's response + * to further user actions. See + * Keeping Your App Responsive + * for more details.

* - *

See the Buttons + *

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 + * Styling Your Button * guide.

* - *

XML attributes

- *

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

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

+ * {@link android.R.styleable#View View Attributes}. See the + * {@link Styles and Themes + * guide to learn how to implement and organize overrides to style-related attributes.

+ * + * @see + * Buttons Guide + * {@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 + * creating custom views. + * + * @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. + * + *

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); } -- cgit v1.2.3-59-g8ed1b