/*
 * Copyright (c) 1995, 2008, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.awt;

import java.awt.peer.ButtonPeer;
import java.util.EventListener;
import java.awt.event.*;
import java.io.ObjectOutputStream;
import java.io.ObjectInputStream;
import java.io.IOException;
import javax.accessibility.*;

This class creates a labeled button. The application can cause some action to happen when the button is pushed. This image depicts three views of a "Quit" button as it appears under the Solaris operating system:

The first view shows the button as it appears normally. The second view shows the button when it has input focus. Its outline is darkened to let the user know that it is an active object. The third view shows the button when the user clicks the mouse over the button, and thus requests that an action be performed.

The gesture of clicking on a button with the mouse is associated with one instance of ActionEvent, which is sent out when the mouse is both pressed and released over the button. If an application is interested in knowing when the button has been pressed but not released, as a separate gesture, it can specialize processMouseEvent, or it can register itself as a listener for mouse events by calling addMouseListener. Both of these methods are defined by Component, the abstract superclass of all components.

When a button is pressed and released, AWT sends an instance of ActionEvent to the button, by calling processEvent on the button. The button's processEvent method receives all events for the button; it passes an action event along by calling its own processActionEvent method. The latter method passes the action event on to any action listeners that have registered an interest in action events generated by this button.

If an application wants to perform some action based on a button being pressed and released, it should implement ActionListener and register the new listener to receive events from this button, by calling the button's addActionListener method. The application can make use of the button's action command as a messaging protocol.

Author: Sami Shaio
See Also:
Since: JDK1.0
/** * This class creates a labeled button. The application can cause * some action to happen when the button is pushed. This image * depicts three views of a "<code>Quit</code>" button as it appears * under the Solaris operating system: * <p> * <img src="doc-files/Button-1.gif" alt="The following context describes the graphic" * ALIGN=center HSPACE=10 VSPACE=7> * <p> * The first view shows the button as it appears normally. * The second view shows the button * when it has input focus. Its outline is darkened to let the * user know that it is an active object. The third view shows the * button when the user clicks the mouse over the button, and thus * requests that an action be performed. * <p> * The gesture of clicking on a button with the mouse * is associated with one instance of <code>ActionEvent</code>, * which is sent out when the mouse is both pressed and released * over the button. If an application is interested in knowing * when the button has been pressed but not released, as a separate * gesture, it can specialize <code>processMouseEvent</code>, * or it can register itself as a listener for mouse events by * calling <code>addMouseListener</code>. Both of these methods are * defined by <code>Component</code>, the abstract superclass of * all components. * <p> * When a button is pressed and released, AWT sends an instance * of <code>ActionEvent</code> to the button, by calling * <code>processEvent</code> on the button. The button's * <code>processEvent</code> method receives all events * for the button; it passes an action event along by * calling its own <code>processActionEvent</code> method. * The latter method passes the action event on to any action * listeners that have registered an interest in action * events generated by this button. * <p> * If an application wants to perform some action based on * a button being pressed and released, it should implement * <code>ActionListener</code> and register the new listener * to receive events from this button, by calling the button's * <code>addActionListener</code> method. The application can * make use of the button's action command as a messaging protocol. * * @author Sami Shaio * @see java.awt.event.ActionEvent * @see java.awt.event.ActionListener * @see java.awt.Component#processMouseEvent * @see java.awt.Component#addMouseListener * @since JDK1.0 */
public class Button extends Component implements Accessible {
The button's label. This value may be null.
See Also:
@serial
/** * The button's label. This value may be null. * @serial * @see #getLabel() * @see #setLabel(String) */
String label;
The action to be performed once a button has been pressed. This value may be null.
See Also:
@serial
/** * The action to be performed once a button has been * pressed. This value may be null. * @serial * @see #getActionCommand() * @see #setActionCommand(String) */
String actionCommand; transient ActionListener actionListener; private static final String base = "button"; private static int nameCounter = 0; /* * JDK 1.1 serialVersionUID */ private static final long serialVersionUID = -8774683716313001058L; static { /* ensure that the necessary native libraries are loaded */ Toolkit.loadLibraries(); if (!GraphicsEnvironment.isHeadless()) { initIDs(); } }
Initialize JNI field and method IDs for fields that may be accessed from C.
/** * Initialize JNI field and method IDs for fields that may be * accessed from C. */
private static native void initIDs();
Constructs a button with an empty string for its label.
Throws:
  • HeadlessException – if GraphicsEnvironment.isHeadless() returns true
See Also:
/** * Constructs a button with an empty string for its label. * * @exception HeadlessException if GraphicsEnvironment.isHeadless() * returns true * @see java.awt.GraphicsEnvironment#isHeadless */
public Button() throws HeadlessException { this(""); }
Constructs a button with the specified label.
Params:
  • label – a string label for the button, or null for no label
Throws:
See Also:
/** * Constructs a button with the specified label. * * @param label a string label for the button, or * <code>null</code> for no label * @exception HeadlessException if GraphicsEnvironment.isHeadless() * returns true * @see java.awt.GraphicsEnvironment#isHeadless */
public Button(String label) throws HeadlessException { GraphicsEnvironment.checkHeadless(); this.label = label; }
Construct a name for this component. Called by getName() when the name is null.
/** * Construct a name for this component. Called by getName() when the * name is null. */
String constructComponentName() { synchronized (Button.class) { return base + nameCounter++; } }
Creates the peer of the button. The button's peer allows the application to change the look of the button without changing its functionality.
See Also:
/** * Creates the peer of the button. The button's peer allows the * application to change the look of the button without changing * its functionality. * * @see java.awt.Toolkit#createButton(java.awt.Button) * @see java.awt.Component#getToolkit() */
public void addNotify() { synchronized(getTreeLock()) { if (peer == null) peer = getToolkit().createButton(this); super.addNotify(); } }
Gets the label of this button.
See Also:
Returns: the button's label, or null if the button has no label.
/** * Gets the label of this button. * * @return the button's label, or <code>null</code> * if the button has no label. * @see java.awt.Button#setLabel */
public String getLabel() { return label; }
Sets the button's label to be the specified string.
Params:
  • label – the new label, or null if the button has no label.
See Also:
/** * Sets the button's label to be the specified string. * * @param label the new label, or <code>null</code> * if the button has no label. * @see java.awt.Button#getLabel */
public void setLabel(String label) { boolean testvalid = false; synchronized (this) { if (label != this.label && (this.label == null || !this.label.equals(label))) { this.label = label; ButtonPeer peer = (ButtonPeer)this.peer; if (peer != null) { peer.setLabel(label); } testvalid = true; } } // This could change the preferred size of the Component. if (testvalid) { invalidateIfValid(); } }
Sets the command name for the action event fired by this button. By default this action command is set to match the label of the button.
Params:
  • command – a string used to set the button's action command. If the string is null then the action command is set to match the label of the button.
See Also:
Since: JDK1.1
/** * Sets the command name for the action event fired * by this button. By default this action command is * set to match the label of the button. * * @param command a string used to set the button's * action command. * If the string is <code>null</code> then the action command * is set to match the label of the button. * @see java.awt.event.ActionEvent * @since JDK1.1 */
public void setActionCommand(String command) { actionCommand = command; }
Returns the command name of the action event fired by this button. If the command name is null (default) then this method returns the label of the button.
/** * Returns the command name of the action event fired by this button. * If the command name is <code>null</code> (default) then this method * returns the label of the button. */
public String getActionCommand() { return (actionCommand == null? label : actionCommand); }
Adds the specified action listener to receive action events from this button. Action events occur when a user presses or releases the mouse over this button. If l is null, no exception is thrown and no action is performed.

Refer to AWT Threading Issues for details on AWT's threading model.

Params:
  • l – the action listener
See Also:
Since: JDK1.1
/** * Adds the specified action listener to receive action events from * this button. Action events occur when a user presses or releases * the mouse over this button. * If l is null, no exception is thrown and no action is performed. * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads" * >AWT Threading Issues</a> for details on AWT's threading model. * * @param l the action listener * @see #removeActionListener * @see #getActionListeners * @see java.awt.event.ActionListener * @since JDK1.1 */
public synchronized void addActionListener(ActionListener l) { if (l == null) { return; } actionListener = AWTEventMulticaster.add(actionListener, l); newEventsOnly = true; }
Removes the specified action listener so that it no longer receives action events from this button. Action events occur when a user presses or releases the mouse over this button. If l is null, no exception is thrown and no action is performed.

Refer to AWT Threading Issues for details on AWT's threading model.

Params:
  • l – the action listener
See Also:
Since: JDK1.1
/** * Removes the specified action listener so that it no longer * receives action events from this button. Action events occur * when a user presses or releases the mouse over this button. * If l is null, no exception is thrown and no action is performed. * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads" * >AWT Threading Issues</a> for details on AWT's threading model. * * @param l the action listener * @see #addActionListener * @see #getActionListeners * @see java.awt.event.ActionListener * @since JDK1.1 */
public synchronized void removeActionListener(ActionListener l) { if (l == null) { return; } actionListener = AWTEventMulticaster.remove(actionListener, l); }
Returns an array of all the action listeners registered on this button.
See Also:
Returns:all of this button's ActionListeners or an empty array if no action listeners are currently registered
Since:1.4
/** * Returns an array of all the action listeners * registered on this button. * * @return all of this button's <code>ActionListener</code>s * or an empty array if no action * listeners are currently registered * * @see #addActionListener * @see #removeActionListener * @see java.awt.event.ActionListener * @since 1.4 */
public synchronized ActionListener[] getActionListeners() { return (ActionListener[]) (getListeners(ActionListener.class)); }
Returns an array of all the objects currently registered as FooListeners upon this Button. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a Button b for its action listeners with the following code:

ActionListener[] als = (ActionListener[])(b.getListeners(ActionListener.class));
If no such listeners exist, this method returns an empty array.
Params:
  • listenerType – the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Throws:
  • ClassCastException – if listenerType doesn't specify a class or interface that implements java.util.EventListener
See Also:
Returns:an array of all objects registered as FooListeners on this button, or an empty array if no such listeners have been added
Since:1.3
/** * Returns an array of all the objects currently registered * as <code><em>Foo</em>Listener</code>s * upon this <code>Button</code>. * <code><em>Foo</em>Listener</code>s are registered using the * <code>add<em>Foo</em>Listener</code> method. * * <p> * You can specify the <code>listenerType</code> argument * with a class literal, such as * <code><em>Foo</em>Listener.class</code>. * For example, you can query a * <code>Button</code> <code>b</code> * for its action listeners with the following code: * * <pre>ActionListener[] als = (ActionListener[])(b.getListeners(ActionListener.class));</pre> * * If no such listeners exist, this method returns an empty array. * * @param listenerType the type of listeners requested; this parameter * should specify an interface that descends from * <code>java.util.EventListener</code> * @return an array of all objects registered as * <code><em>Foo</em>Listener</code>s on this button, * or an empty array if no such * listeners have been added * @exception ClassCastException if <code>listenerType</code> * doesn't specify a class or interface that implements * <code>java.util.EventListener</code> * * @see #getActionListeners * @since 1.3 */
public <T extends EventListener> T[] getListeners(Class<T> listenerType) { EventListener l = null; if (listenerType == ActionListener.class) { l = actionListener; } else { return super.getListeners(listenerType); } return AWTEventMulticaster.getListeners(l, listenerType); } // REMIND: remove when filtering is done at lower level boolean eventEnabled(AWTEvent e) { if (e.id == ActionEvent.ACTION_PERFORMED) { if ((eventMask & AWTEvent.ACTION_EVENT_MASK) != 0 || actionListener != null) { return true; } return false; } return super.eventEnabled(e); }
Processes events on this button. If an event is an instance of ActionEvent, this method invokes the processActionEvent method. Otherwise, it invokes processEvent on the superclass.

Note that if the event parameter is null the behavior is unspecified and may result in an exception.

Params:
  • e – the event
See Also:
Since: JDK1.1
/** * Processes events on this button. If an event is * an instance of <code>ActionEvent</code>, this method invokes * the <code>processActionEvent</code> method. Otherwise, * it invokes <code>processEvent</code> on the superclass. * <p>Note that if the event parameter is <code>null</code> * the behavior is unspecified and may result in an * exception. * * @param e the event * @see java.awt.event.ActionEvent * @see java.awt.Button#processActionEvent * @since JDK1.1 */
protected void processEvent(AWTEvent e) { if (e instanceof ActionEvent) { processActionEvent((ActionEvent)e); return; } super.processEvent(e); }
Processes action events occurring on this button by dispatching them to any registered ActionListener objects.

This method is not called unless action events are enabled for this button. Action events are enabled when one of the following occurs:

  • An ActionListener object is registered via addActionListener.
  • Action events are enabled via enableEvents.

Note that if the event parameter is null the behavior is unspecified and may result in an exception.

Params:
  • e – the action event
See Also:
Since: JDK1.1
/** * Processes action events occurring on this button * by dispatching them to any registered * <code>ActionListener</code> objects. * <p> * This method is not called unless action events are * enabled for this button. Action events are enabled * when one of the following occurs: * <p><ul> * <li>An <code>ActionListener</code> object is registered * via <code>addActionListener</code>. * <li>Action events are enabled via <code>enableEvents</code>. * </ul> * <p>Note that if the event parameter is <code>null</code> * the behavior is unspecified and may result in an * exception. * * @param e the action event * @see java.awt.event.ActionListener * @see java.awt.Button#addActionListener * @see java.awt.Component#enableEvents * @since JDK1.1 */
protected void processActionEvent(ActionEvent e) { ActionListener listener = actionListener; if (listener != null) { listener.actionPerformed(e); } }
Returns a string representing the state of this Button. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.
Returns: the parameter string of this button
/** * Returns a string representing the state of this <code>Button</code>. * This method is intended to be used only for debugging purposes, and the * content and format of the returned string may vary between * implementations. The returned string may be empty but may not be * <code>null</code>. * * @return the parameter string of this button */
protected String paramString() { return super.paramString() + ",label=" + label; } /* Serialization support. */ /* * Button Serial Data Version. * @serial */ private int buttonSerializedDataVersion = 1;
Writes default serializable fields to stream. Writes a list of serializable ActionListeners as optional data. The non-serializable ActionListeners are detected and no attempt is made to serialize them.
Params:
  • s – the ObjectOutputStream to write
See Also:
@serialDatanull terminated sequence of 0 or more pairs: the pair consists of a String and an Object; the String indicates the type of object and is one of the following: actionListenerK indicating an ActionListener object
/** * Writes default serializable fields to stream. Writes * a list of serializable <code>ActionListeners</code> * as optional data. The non-serializable * <code>ActionListeners</code> are detected and * no attempt is made to serialize them. * * @serialData <code>null</code> terminated sequence of 0 or * more pairs: the pair consists of a <code>String</code> * and an <code>Object</code>; the <code>String</code> * indicates the type of object and is one of the following: * <code>actionListenerK</code> indicating an * <code>ActionListener</code> object * * @param s the <code>ObjectOutputStream</code> to write * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener) * @see java.awt.Component#actionListenerK * @see #readObject(ObjectInputStream) */
private void writeObject(ObjectOutputStream s) throws IOException { s.defaultWriteObject(); AWTEventMulticaster.save(s, actionListenerK, actionListener); s.writeObject(null); }
Reads the ObjectInputStream and if it isn't null adds a listener to receive action events fired by the button. Unrecognized keys or values will be ignored.
Params:
  • s – the ObjectInputStream to read
Throws:
See Also:
@serial
/** * Reads the <code>ObjectInputStream</code> and if * it isn't <code>null</code> adds a listener to * receive action events fired by the button. * Unrecognized keys or values will be ignored. * * @param s the <code>ObjectInputStream</code> to read * @exception HeadlessException if * <code>GraphicsEnvironment.isHeadless</code> returns * <code>true</code> * @serial * @see #removeActionListener(ActionListener) * @see #addActionListener(ActionListener) * @see java.awt.GraphicsEnvironment#isHeadless * @see #writeObject(ObjectOutputStream) */
private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException, HeadlessException { GraphicsEnvironment.checkHeadless(); s.defaultReadObject(); Object keyOrNull; while(null != (keyOrNull = s.readObject())) { String key = ((String)keyOrNull).intern(); if (actionListenerK == key) addActionListener((ActionListener)(s.readObject())); else // skip value for unrecognized key s.readObject(); } } ///////////////// // Accessibility support ////////////////
Gets the AccessibleContext associated with this Button. For buttons, the AccessibleContext takes the form of an AccessibleAWTButton. A new AccessibleAWTButton instance is created if necessary.
Returns:an AccessibleAWTButton that serves as the AccessibleContext of this Button
@beaninfo expert: true description: The AccessibleContext associated with this Button.
Since:1.3
/** * Gets the <code>AccessibleContext</code> associated with * this <code>Button</code>. For buttons, the * <code>AccessibleContext</code> takes the form of an * <code>AccessibleAWTButton</code>. * A new <code>AccessibleAWTButton</code> instance is * created if necessary. * * @return an <code>AccessibleAWTButton</code> that serves as the * <code>AccessibleContext</code> of this <code>Button</code> * @beaninfo * expert: true * description: The AccessibleContext associated with this Button. * @since 1.3 */
public AccessibleContext getAccessibleContext() { if (accessibleContext == null) { accessibleContext = new AccessibleAWTButton(); } return accessibleContext; }
This class implements accessibility support for the Button class. It provides an implementation of the Java Accessibility API appropriate to button user-interface elements.
Since:1.3
/** * This class implements accessibility support for the * <code>Button</code> class. It provides an implementation of the * Java Accessibility API appropriate to button user-interface elements. * @since 1.3 */
protected class AccessibleAWTButton extends AccessibleAWTComponent implements AccessibleAction, AccessibleValue { /* * JDK 1.3 serialVersionUID */ private static final long serialVersionUID = -5932203980244017102L;
Get the accessible name of this object.
Returns:the localized name of the object -- can be null if this object does not have a name
/** * Get the accessible name of this object. * * @return the localized name of the object -- can be null if this * object does not have a name */
public String getAccessibleName() { if (accessibleName != null) { return accessibleName; } else { if (getLabel() == null) { return super.getAccessibleName(); } else { return getLabel(); } } }
Get the AccessibleAction associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleAction interface on behalf of itself.
Returns:this object
/** * Get the AccessibleAction associated with this object. In the * implementation of the Java Accessibility API for this class, * return this object, which is responsible for implementing the * AccessibleAction interface on behalf of itself. * * @return this object */
public AccessibleAction getAccessibleAction() { return this; }
Get the AccessibleValue associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleValue interface on behalf of itself.
Returns:this object
/** * Get the AccessibleValue associated with this object. In the * implementation of the Java Accessibility API for this class, * return this object, which is responsible for implementing the * AccessibleValue interface on behalf of itself. * * @return this object */
public AccessibleValue getAccessibleValue() { return this; }
Returns the number of Actions available in this object. The default behavior of a button is to have one action - toggle the button.
Returns:1, the number of Actions in this object
/** * Returns the number of Actions available in this object. The * default behavior of a button is to have one action - toggle * the button. * * @return 1, the number of Actions in this object */
public int getAccessibleActionCount() { return 1; }
Return a description of the specified action of the object.
Params:
  • i – zero-based index of the actions
/** * Return a description of the specified action of the object. * * @param i zero-based index of the actions */
public String getAccessibleActionDescription(int i) { if (i == 0) { // [[[PENDING: WDW -- need to provide a localized string]]] return new String("click"); } else { return null; } }
Perform the specified Action on the object
Params:
  • i – zero-based index of actions
Returns:true if the the action was performed; else false.
/** * Perform the specified Action on the object * * @param i zero-based index of actions * @return true if the the action was performed; else false. */
public boolean doAccessibleAction(int i) { if (i == 0) { // Simulate a button click Toolkit.getEventQueue().postEvent( new ActionEvent(Button.this, ActionEvent.ACTION_PERFORMED, Button.this.getActionCommand())); return true; } else { return false; } }
Get the value of this object as a Number.
See Also:
Returns:An Integer of 0 if this isn't selected or an Integer of 1 if this is selected.
/** * Get the value of this object as a Number. * * @return An Integer of 0 if this isn't selected or an Integer of 1 if * this is selected. * @see javax.swing.AbstractButton#isSelected() */
public Number getCurrentAccessibleValue() { return Integer.valueOf(0); }
Set the value of this object as a Number.
Returns:True if the value was set.
/** * Set the value of this object as a Number. * * @return True if the value was set. */
public boolean setCurrentAccessibleValue(Number n) { return false; }
Get the minimum value of this object as a Number.
Returns:An Integer of 0.
/** * Get the minimum value of this object as a Number. * * @return An Integer of 0. */
public Number getMinimumAccessibleValue() { return Integer.valueOf(0); }
Get the maximum value of this object as a Number.
Returns:An Integer of 0.
/** * Get the maximum value of this object as a Number. * * @return An Integer of 0. */
public Number getMaximumAccessibleValue() { return Integer.valueOf(0); }
Get the role of this object.
See Also:
Returns:an instance of AccessibleRole describing the role of the object
/** * Get the role of this object. * * @return an instance of AccessibleRole describing the role of the * object * @see AccessibleRole */
public AccessibleRole getAccessibleRole() { return AccessibleRole.PUSH_BUTTON; } } // inner class AccessibleAWTButton }