| /* |
| * 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 "<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. |
| * @serial |
| * @see #getLabel() |
| * @see #setLabel(String) |
| */ |
| String label; |
| |
| /** |
| * 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. |
| */ |
| private static native void initIDs(); |
| |
| /** |
| * 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. |
| * |
| * @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. |
| */ |
| 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 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. |
| * |
| * @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. |
| * |
| * @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. |
| * |
| * @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 <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. |
| * <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. |
| * <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. |
| * |
| * @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 <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 <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 |
| * <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 <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 <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 <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 <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 |
| * <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. |
| * |
| * @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. |
| * |
| * @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. |
| * |
| * @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. |
| * |
| * @return 1, the number of Actions in this object |
| */ |
| public int getAccessibleActionCount() { |
| return 1; |
| } |
| |
| /** |
| * 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 |
| * |
| * @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. |
| * |
| * @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. |
| * |
| * @return True if the value was set. |
| */ |
| public boolean setCurrentAccessibleValue(Number n) { |
| return false; |
| } |
| |
| /** |
| * 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. |
| * |
| * @return An Integer of 0. |
| */ |
| public Number getMaximumAccessibleValue() { |
| return Integer.valueOf(0); |
| } |
| |
| /** |
| * 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 |
| |
| } |
