/*
* Copyright (c) 1995, 2019, 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.beans.BeanProperty;
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: 1.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}" button as it appears
* under the Solaris operating system:
* <p>
* <img src="doc-files/Button-1.gif" alt="The following context describes the
* graphic" style="margin: 7px 10px;">
* <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},
* 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},
* or it can register itself as a listener for mouse events by
* calling {@code addMouseListener}. Both of these methods are
* defined by {@code Component}, the abstract superclass of
* all components.
* <p>
* When a button is pressed and released, AWT sends an instance
* of {@code ActionEvent} to the button, by calling
* {@code processEvent} on the button. The button's
* {@code processEvent} method receives all events
* for the button; it passes an action event along by
* calling its own {@code 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.
* <p>
* If an application wants to perform some action based on
* a button being pressed and released, it should implement
* {@code ActionListener} and register the new listener
* to receive events from this button, by calling the button's
* {@code addActionListener} 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 1.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: - HeadlessException – if GraphicsEnvironment.isHeadless()
returns true
See Also:
/**
* Constructs a button with the specified label.
*
* @param label a string label for the button, or
* {@code null} 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: - getToolkit.getToolkit()
/**
* 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.Component#getToolkit()
*/
public void addNotify() {
synchronized(getTreeLock()) {
if (peer == null)
peer = getComponentFactory().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}
* 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}
* 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: 1.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} then the action command
* is set to match the label of the button.
* @see java.awt.event.ActionEvent
* @since 1.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 action command name (or label) for this button
/**
* Returns the command name of the action event fired by this button.
* If the command name is {@code null} (default) then this method
* returns the label of the button.
*
* @return the action command name (or label) for this 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: 1.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 1.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: 1.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 1.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 ActionListener
s 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}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 getListeners(ActionListener.class);
}
Returns an array of all the objects currently registered
as FooListener
s upon this Button
. FooListener
s 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
FooListener
s 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><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} argument
* with a class literal, such as
* <code><em>Foo</em>Listener.class</code>.
* For example, you can query a
* {@code Button b}
* 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}
* @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}
* doesn't specify a class or interface that implements
* {@code java.util.EventListener}
*
* @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: 1.1
/**
* Processes events on this button. If an event is
* an instance of {@code ActionEvent}, this method invokes
* the {@code processActionEvent} method. Otherwise,
* it invokes {@code processEvent} on the superclass.
* <p>Note that if the event parameter is {@code null}
* 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 1.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: 1.1
/**
* Processes action events occurring on this button
* by dispatching them to any registered
* {@code ActionListener} 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:
* <ul>
* <li>An {@code ActionListener} object is registered
* via {@code addActionListener}.
* <li>Action events are enabled via {@code enableEvents}.
* </ul>
* <p>Note that if the event parameter is {@code null}
* 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 1.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}.
* 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}.
*
* @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: @serialData null
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}
* as optional data. The non-serializable
* {@code ActionListeners} are detected and
* no attempt is made to serialize them.
*
* @serialData {@code null} terminated sequence of 0 or
* more pairs: the pair consists of a {@code String}
* and an {@code Object}; the {@code String}
* indicates the type of object and is one of the following:
* {@code actionListenerK} indicating an
* {@code ActionListener} object
*
* @param s the {@code ObjectOutputStream} 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: - HeadlessException – if
GraphicsEnvironment.isHeadless
returns true
See Also: @serial
/**
* Reads the {@code ObjectInputStream} and if
* it isn't {@code null} adds a listener to
* receive action events fired by the button.
* Unrecognized keys or values will be ignored.
*
* @param s the {@code ObjectInputStream} to read
* @exception HeadlessException if
* {@code GraphicsEnvironment.isHeadless} returns
* {@code true}
* @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
Since: 1.3
/**
* Gets the {@code AccessibleContext} associated with
* this {@code Button}. For buttons, the
* {@code AccessibleContext} takes the form of an
* {@code AccessibleAWTButton}.
* A new {@code AccessibleAWTButton} instance is
* created if necessary.
*
* @return an {@code AccessibleAWTButton} that serves as the
* {@code AccessibleContext} of this {@code Button}
* @since 1.3
*/
@BeanProperty(expert = true, description
= "The AccessibleContext associated with this Button.")
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} 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 "click";
} else {
return null;
}
}
Perform the specified Action on the object
Params: - i – zero-based index of actions
Returns: true if the action was performed; else false.
/**
* Perform the specified Action on the object
*
* @param i zero-based index of actions
* @return true if 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
}