core/java/android/widget/Button.java

   1 /*
   2  * Copyright (C) 2006 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package android.widget;
  18
  19 import android.content.Context;
  20 import android.util.AttributeSet;
  21 import android.view.MotionEvent;
  22 import android.view.PointerIcon;
  23 import android.widget.RemoteViews.RemoteView;
  24
  25
  26 /**
  27  * A user interface element the user can tap or click to perform an action.
  28  *
  29  * <p>To display a button in an activity, add a button to the activity's layout XML file:</p>
  30  *
  31  * <pre>
  32  * &lt;Button
  33  *     android:id="@+id/button_id"
  34  *     android:layout_height="wrap_content"
  35  *     android:layout_width="wrap_content"
  36  *     android:text="@string/self_destruct" /&gt;</pre>
  37  *
  38  * <p>To specify an action when the button is pressed, set a click
  39  * listener on the button object in the corresponding activity code:</p>
  40  *
  41  * <pre>
  42  * public class MyActivity extends Activity {
  43  *     protected void onCreate(Bundle savedInstanceState) {
  44  *         super.onCreate(savedInstanceState);
  45  *
  46  *         setContentView(R.layout.content_layout_id);
  47  *
  48  *         final Button button = findViewById(R.id.button_id);
  49  *         button.setOnClickListener(new View.OnClickListener() {
  50  *             public void onClick(View v) {
  51  *                 // Code here executes on main thread after user presses button
  52  *             }
  53  *         });
  54  *     }
  55  * }</pre>
  56  *
  57  * <p>The above snippet creates an instance of {@link View.OnClickListener} and wires
  58  * the listener to the button using
  59  * {@link #setOnClickListener setOnClickListener(View.OnClickListener)}.
  60  * As a result, the system executes the code you write in {@code onClick(View)} after the
  61  * user presses the button.</p>
  62  *
  63  * <p class="note">The system executes the code in {@code onClick} on the
  64  * <a href="{@docRoot}guide/components/processes-and-threads.html#Threads">main thread</a>.
  65  * This means your onClick code must execute quickly to avoid delaying your app's response
  66  * to further user actions.  See
  67  * <a href="{@docRoot}training/articles/perf-anr.html">Keeping Your App Responsive</a>
  68  * for more details.</p>
  69  *
  70  * <p>Every button is styled using the system's default button background, which is often
  71  * different from one version of the platform to another. If you are not satisfied with the
  72  * default button style, you can customize it. For more details and code samples, see the
  73  * <a href="{@docRoot}guide/topics/ui/controls/button.html#Style">Styling Your Button</a>
  74  * guide.</p>
  75  *
  76  * <p>For all XML style attributes available on Button see
  77  * {@link android.R.styleable#Button Button Attributes},
  78  * {@link android.R.styleable#TextView TextView Attributes},
  79  * {@link android.R.styleable#View View Attributes}.  See the
  80  * {@link <a href="{@docRoot}guide/topics/ui/themes.html#ApplyingStyles">Styles and Themes</a>
  81  * guide to learn how to implement and organize overrides to style-related attributes.</p>
  82  *
  83  * @see
  84  * <a href="{@docRoot}guide/topics/ui/controls/button.html">Buttons Guide</a>
  85  * {@link android.R.styleable#Button Styleable Button Attributes},
  86  * {@link android.R.styleable#TextView Styleable TextView Attributes},
  87  * {@link android.R.styleable#View Styleable View Attributes},
  88  *
  89  */
  90 @RemoteView
  91 public class Button extends TextView {
  92
  93     /**
  94      * Simple constructor to use when creating a button from code.
  95      *
  96      * @param context The Context the Button is running in, through which it can
  97      *        access the current theme, resources, etc.
  98      *
  99      * @see #Button(Context, AttributeSet)
 100      */
 101     public Button(Context context) {
 102         this(context, null);
 103     }
 104
 105     /**
 106      * {@link LayoutInflater} calls this constructor when inflating a Button from XML.
 107      * The attributes defined by the current theme's
 108      * {@link android.R.attr#buttonStyle android:buttonStyle}
 109      * override base view attributes.
 110      *
 111      * You typically do not call this constructor to create your own button instance in code.
 112      * However, you must override this constructor when
 113      * <a href="{@docRoot}training/custom-views/index.html">creating custom views</a>.
 114      *
 115      * @param context The Context the view is running in, through which it can
 116      *        access the current theme, resources, etc.
 117      * @param attrs The attributes of the XML Button tag being used to inflate the view.
 118      *
 119      * @see #Button(Context, AttributeSet, int)
 120      * @see android.view.View#View(Context, AttributeSet)
 121      */
 122     public Button(Context context, AttributeSet attrs) {
 123         this(context, attrs, com.android.internal.R.attr.buttonStyle);
 124     }
 125
 126     /**
 127      * This constructor allows a Button subclass to use its own class-specific base style from a
 128      * theme attribute when inflating. The attributes defined by the current theme's
 129      * {@code defStyleAttr} override base view attributes.
 130      *
 131      * <p>For Button's base view attributes see
 132      * {@link android.R.styleable#Button Button Attributes},
 133      * {@link android.R.styleable#TextView TextView Attributes},
 134      * {@link android.R.styleable#View View Attributes}.
 135      *
 136      * @param context The Context the Button is running in, through which it can
 137      *        access the current theme, resources, etc.
 138      * @param attrs The attributes of the XML Button tag that is inflating the view.
 139      * @param defStyleAttr The resource identifier of an attribute in the current theme
 140      *        whose value is the the resource id of a style. The specified style’s
 141      *        attribute values serve as default values for the button. Set this parameter
 142      *        to 0 to avoid use of default values.
 143      * @see #Button(Context, AttributeSet, int, int)
 144      * @see android.view.View#View(Context, AttributeSet, int)
 145      */
 146     public Button(Context context, AttributeSet attrs, int defStyleAttr) {
 147         this(context, attrs, defStyleAttr, 0);
 148     }
 149
 150     /**
 151      * This constructor allows a Button subclass to use its own class-specific base style from
 152      * either a theme attribute or style resource when inflating. To see how the final value of a
 153      * particular attribute is resolved based on your inputs to this constructor, see
 154      * {@link android.view.View#View(Context, AttributeSet, int, int)}.
 155      *
 156      * @param context The Context the Button is running in, through which it can
 157      *        access the current theme, resources, etc.
 158      * @param attrs The attributes of the XML Button tag that is inflating the view.
 159      * @param defStyleAttr The resource identifier of an attribute in the current theme
 160      *        whose value is the the resource id of a style. The specified style’s
 161      *        attribute values serve as default values for the button. Set this parameter
 162      *        to 0 to avoid use of default values.
 163      * @param defStyleRes The identifier of a style resource that
 164      *        supplies default values for the button, used only if
 165      *        defStyleAttr is 0 or cannot be found in the theme.
 166      *        Set this parameter to 0 to avoid use of default values.
 167      *
 168      * @see #Button(Context, AttributeSet, int)
 169      * @see android.view.View#View(Context, AttributeSet, int, int)
 170      */
 171     public Button(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes) {
 172         super(context, attrs, defStyleAttr, defStyleRes);
 173     }
 174
 175     @Override
 176     public CharSequence getAccessibilityClassName() {
 177         return Button.class.getName();
 178     }
 179
 180     @Override
 181     public PointerIcon onResolvePointerIcon(MotionEvent event, int pointerIndex) {
 182         if (getPointerIcon() == null && isClickable() && isEnabled()) {
 183             return PointerIcon.getSystemIcon(getContext(), PointerIcon.TYPE_HAND);
 184         }
 185         return super.onResolvePointerIcon(event, pointerIndex);
 186     }
 187 }