Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
TreeHugger Robot
2017-04-27 05:21:17 +00:00
committed by Android (Google) Code Review
parent d915c42150 8e342c7b75
commit 1e5d0768cd
1 changed files with 110 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
core/java/android/widget/Button.java
View File

@@ -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.
* <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>
* &lt;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>
* <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>
*
* <pre>
* &lt;Button
* android:layout_height="wrap_content"
* android:layout_width="wrap_content"
* android:text="@string/self_destruct"
* android:onClick="selfDestruct" /&gt;</pre>
* <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>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>
*
* <h3>Button style</h3>
*
* <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);
}