001: /*
002: * Copyright 1995-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.awt;
027:
028: import java.awt.peer.ButtonPeer;
029: import java.util.EventListener;
030: import java.awt.event.*;
031: import java.io.ObjectOutputStream;
032: import java.io.ObjectInputStream;
033: import java.io.IOException;
034: import javax.accessibility.*;
035:
036: /**
037: * This class creates a labeled button. The application can cause
038: * some action to happen when the button is pushed. This image
039: * depicts three views of a "<code>Quit</code>" button as it appears
040: * under the Solaris operating system:
041: * <p>
042: * <img src="doc-files/Button-1.gif" alt="The following context describes the graphic"
043: * ALIGN=center HSPACE=10 VSPACE=7>
044: * <p>
045: * The first view shows the button as it appears normally.
046: * The second view shows the button
047: * when it has input focus. Its outline is darkened to let the
048: * user know that it is an active object. The third view shows the
049: * button when the user clicks the mouse over the button, and thus
050: * requests that an action be performed.
051: * <p>
052: * The gesture of clicking on a button with the mouse
053: * is associated with one instance of <code>ActionEvent</code>,
054: * which is sent out when the mouse is both pressed and released
055: * over the button. If an application is interested in knowing
056: * when the button has been pressed but not released, as a separate
057: * gesture, it can specialize <code>processMouseEvent</code>,
058: * or it can register itself as a listener for mouse events by
059: * calling <code>addMouseListener</code>. Both of these methods are
060: * defined by <code>Component</code>, the abstract superclass of
061: * all components.
062: * <p>
063: * When a button is pressed and released, AWT sends an instance
064: * of <code>ActionEvent</code> to the button, by calling
065: * <code>processEvent</code> on the button. The button's
066: * <code>processEvent</code> method receives all events
067: * for the button; it passes an action event along by
068: * calling its own <code>processActionEvent</code> method.
069: * The latter method passes the action event on to any action
070: * listeners that have registered an interest in action
071: * events generated by this button.
072: * <p>
073: * If an application wants to perform some action based on
074: * a button being pressed and released, it should implement
075: * <code>ActionListener</code> and register the new listener
076: * to receive events from this button, by calling the button's
077: * <code>addActionListener</code> method. The application can
078: * make use of the button's action command as a messaging protocol.
079: *
080: * @version 1.89 05/05/07
081: * @author Sami Shaio
082: * @see java.awt.event.ActionEvent
083: * @see java.awt.event.ActionListener
084: * @see java.awt.Component#processMouseEvent
085: * @see java.awt.Component#addMouseListener
086: * @since JDK1.0
087: */
088: public class Button extends Component implements Accessible {
089:
090: /**
091: * The button's label. This value may be null.
092: * @serial
093: * @see #getLabel()
094: * @see #setLabel(String)
095: */
096: String label;
097:
098: /**
099: * The action to be performed once a button has been
100: * pressed. This value may be null.
101: * @serial
102: * @see #getActionCommand()
103: * @see #setActionCommand(String)
104: */
105: String actionCommand;
106:
107: transient ActionListener actionListener;
108:
109: private static final String base = "button";
110: private static int nameCounter = 0;
111:
112: /*
113: * JDK 1.1 serialVersionUID
114: */
115: private static final long serialVersionUID = -8774683716313001058L;
116:
117: static {
118: /* ensure that the necessary native libraries are loaded */
119: Toolkit.loadLibraries();
120: if (!GraphicsEnvironment.isHeadless()) {
121: initIDs();
122: }
123: }
124:
125: /**
126: * Initialize JNI field and method IDs for fields that may be
127: * accessed from C.
128: */
129: private static native void initIDs();
130:
131: /**
132: * Constructs a button with an empty string for its label.
133: *
134: * @exception HeadlessException if GraphicsEnvironment.isHeadless()
135: * returns true
136: * @see java.awt.GraphicsEnvironment#isHeadless
137: */
138: public Button() throws HeadlessException {
139: this ("");
140: }
141:
142: /**
143: * Constructs a button with the specified label.
144: *
145: * @param label a string label for the button, or
146: * <code>null</code> for no label
147: * @exception HeadlessException if GraphicsEnvironment.isHeadless()
148: * returns true
149: * @see java.awt.GraphicsEnvironment#isHeadless
150: */
151: public Button(String label) throws HeadlessException {
152: GraphicsEnvironment.checkHeadless();
153: this .label = label;
154: }
155:
156: /**
157: * Construct a name for this component. Called by getName() when the
158: * name is null.
159: */
160: String constructComponentName() {
161: synchronized (Button.class) {
162: return base + nameCounter++;
163: }
164: }
165:
166: /**
167: * Creates the peer of the button. The button's peer allows the
168: * application to change the look of the button without changing
169: * its functionality.
170: *
171: * @see java.awt.Toolkit#createButton(java.awt.Button)
172: * @see java.awt.Component#getToolkit()
173: */
174: public void addNotify() {
175: synchronized (getTreeLock()) {
176: if (peer == null)
177: peer = getToolkit().createButton(this );
178: super .addNotify();
179: }
180: }
181:
182: /**
183: * Gets the label of this button.
184: *
185: * @return the button's label, or <code>null</code>
186: * if the button has no label.
187: * @see java.awt.Button#setLabel
188: */
189: public String getLabel() {
190: return label;
191: }
192:
193: /**
194: * Sets the button's label to be the specified string.
195: *
196: * @param label the new label, or <code>null</code>
197: * if the button has no label.
198: * @see java.awt.Button#getLabel
199: */
200: public void setLabel(String label) {
201: boolean testvalid = false;
202:
203: synchronized (this ) {
204: if (label != this .label
205: && (this .label == null || !this .label.equals(label))) {
206: this .label = label;
207: ButtonPeer peer = (ButtonPeer) this .peer;
208: if (peer != null) {
209: peer.setLabel(label);
210: }
211: testvalid = true;
212: }
213: }
214:
215: // This could change the preferred size of the Component.
216: if (testvalid && valid) {
217: invalidate();
218: }
219: }
220:
221: /**
222: * Sets the command name for the action event fired
223: * by this button. By default this action command is
224: * set to match the label of the button.
225: *
226: * @param command a string used to set the button's
227: * action command.
228: * If the string is <code>null</code> then the action command
229: * is set to match the label of the button.
230: * @see java.awt.event.ActionEvent
231: * @since JDK1.1
232: */
233: public void setActionCommand(String command) {
234: actionCommand = command;
235: }
236:
237: /**
238: * Returns the command name of the action event fired by this button.
239: * If the command name is <code>null</code> (default) then this method
240: * returns the label of the button.
241: */
242: public String getActionCommand() {
243: return (actionCommand == null ? label : actionCommand);
244: }
245:
246: /**
247: * Adds the specified action listener to receive action events from
248: * this button. Action events occur when a user presses or releases
249: * the mouse over this button.
250: * If l is null, no exception is thrown and no action is performed.
251: * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
252: * >AWT Threading Issues</a> for details on AWT's threading model.
253: *
254: * @param l the action listener
255: * @see #removeActionListener
256: * @see #getActionListeners
257: * @see java.awt.event.ActionListener
258: * @since JDK1.1
259: */
260: public synchronized void addActionListener(ActionListener l) {
261: if (l == null) {
262: return;
263: }
264: actionListener = AWTEventMulticaster.add(actionListener, l);
265: newEventsOnly = true;
266: }
267:
268: /**
269: * Removes the specified action listener so that it no longer
270: * receives action events from this button. Action events occur
271: * when a user presses or releases the mouse over this button.
272: * If l is null, no exception is thrown and no action is performed.
273: * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
274: * >AWT Threading Issues</a> for details on AWT's threading model.
275: *
276: * @param l the action listener
277: * @see #addActionListener
278: * @see #getActionListeners
279: * @see java.awt.event.ActionListener
280: * @since JDK1.1
281: */
282: public synchronized void removeActionListener(ActionListener l) {
283: if (l == null) {
284: return;
285: }
286: actionListener = AWTEventMulticaster.remove(actionListener, l);
287: }
288:
289: /**
290: * Returns an array of all the action listeners
291: * registered on this button.
292: *
293: * @return all of this button's <code>ActionListener</code>s
294: * or an empty array if no action
295: * listeners are currently registered
296: *
297: * @see #addActionListener
298: * @see #removeActionListener
299: * @see java.awt.event.ActionListener
300: * @since 1.4
301: */
302: public synchronized ActionListener[] getActionListeners() {
303: return (ActionListener[]) (getListeners(ActionListener.class));
304: }
305:
306: /**
307: * Returns an array of all the objects currently registered
308: * as <code><em>Foo</em>Listener</code>s
309: * upon this <code>Button</code>.
310: * <code><em>Foo</em>Listener</code>s are registered using the
311: * <code>add<em>Foo</em>Listener</code> method.
312: *
313: * <p>
314: * You can specify the <code>listenerType</code> argument
315: * with a class literal, such as
316: * <code><em>Foo</em>Listener.class</code>.
317: * For example, you can query a
318: * <code>Button</code> <code>b</code>
319: * for its action listeners with the following code:
320: *
321: * <pre>ActionListener[] als = (ActionListener[])(b.getListeners(ActionListener.class));</pre>
322: *
323: * If no such listeners exist, this method returns an empty array.
324: *
325: * @param listenerType the type of listeners requested; this parameter
326: * should specify an interface that descends from
327: * <code>java.util.EventListener</code>
328: * @return an array of all objects registered as
329: * <code><em>Foo</em>Listener</code>s on this button,
330: * or an empty array if no such
331: * listeners have been added
332: * @exception ClassCastException if <code>listenerType</code>
333: * doesn't specify a class or interface that implements
334: * <code>java.util.EventListener</code>
335: *
336: * @see #getActionListeners
337: * @since 1.3
338: */
339: public <T extends EventListener> T[] getListeners(
340: Class<T> listenerType) {
341: EventListener l = null;
342: if (listenerType == ActionListener.class) {
343: l = actionListener;
344: } else {
345: return super .getListeners(listenerType);
346: }
347: return AWTEventMulticaster.getListeners(l, listenerType);
348: }
349:
350: // REMIND: remove when filtering is done at lower level
351: boolean eventEnabled(AWTEvent e) {
352: if (e.id == ActionEvent.ACTION_PERFORMED) {
353: if ((eventMask & AWTEvent.ACTION_EVENT_MASK) != 0
354: || actionListener != null) {
355: return true;
356: }
357: return false;
358: }
359: return super .eventEnabled(e);
360: }
361:
362: /**
363: * Processes events on this button. If an event is
364: * an instance of <code>ActionEvent</code>, this method invokes
365: * the <code>processActionEvent</code> method. Otherwise,
366: * it invokes <code>processEvent</code> on the superclass.
367: * <p>Note that if the event parameter is <code>null</code>
368: * the behavior is unspecified and may result in an
369: * exception.
370: *
371: * @param e the event
372: * @see java.awt.event.ActionEvent
373: * @see java.awt.Button#processActionEvent
374: * @since JDK1.1
375: */
376: protected void processEvent(AWTEvent e) {
377: if (e instanceof ActionEvent) {
378: processActionEvent((ActionEvent) e);
379: return;
380: }
381: super .processEvent(e);
382: }
383:
384: /**
385: * Processes action events occurring on this button
386: * by dispatching them to any registered
387: * <code>ActionListener</code> objects.
388: * <p>
389: * This method is not called unless action events are
390: * enabled for this button. Action events are enabled
391: * when one of the following occurs:
392: * <p><ul>
393: * <li>An <code>ActionListener</code> object is registered
394: * via <code>addActionListener</code>.
395: * <li>Action events are enabled via <code>enableEvents</code>.
396: * </ul>
397: * <p>Note that if the event parameter is <code>null</code>
398: * the behavior is unspecified and may result in an
399: * exception.
400: *
401: * @param e the action event
402: * @see java.awt.event.ActionListener
403: * @see java.awt.Button#addActionListener
404: * @see java.awt.Component#enableEvents
405: * @since JDK1.1
406: */
407: protected void processActionEvent(ActionEvent e) {
408: ActionListener listener = actionListener;
409: if (listener != null) {
410: listener.actionPerformed(e);
411: }
412: }
413:
414: /**
415: * Returns a string representing the state of this <code>Button</code>.
416: * This method is intended to be used only for debugging purposes, and the
417: * content and format of the returned string may vary between
418: * implementations. The returned string may be empty but may not be
419: * <code>null</code>.
420: *
421: * @return the parameter string of this button
422: */
423: protected String paramString() {
424: return super .paramString() + ",label=" + label;
425: }
426:
427: /* Serialization support.
428: */
429:
430: /*
431: * Button Serial Data Version.
432: * @serial
433: */
434: private int buttonSerializedDataVersion = 1;
435:
436: /**
437: * Writes default serializable fields to stream. Writes
438: * a list of serializable <code>ActionListeners</code>
439: * as optional data. The non-serializable
440: * <code>ActionListeners</code> are detected and
441: * no attempt is made to serialize them.
442: *
443: * @serialData <code>null</code> terminated sequence of 0 or
444: * more pairs: the pair consists of a <code>String</code>
445: * and an <code>Object</code>; the <code>String</code>
446: * indicates the type of object and is one of the following:
447: * <code>actionListenerK</code> indicating an
448: * <code>ActionListener</code> object
449: *
450: * @param s the <code>ObjectOutputStream</code> to write
451: * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
452: * @see java.awt.Component#actionListenerK
453: * @see #readObject(ObjectInputStream)
454: */
455: private void writeObject(ObjectOutputStream s) throws IOException {
456: s.defaultWriteObject();
457:
458: AWTEventMulticaster.save(s, actionListenerK, actionListener);
459: s.writeObject(null);
460: }
461:
462: /**
463: * Reads the <code>ObjectInputStream</code> and if
464: * it isn't <code>null</code> adds a listener to
465: * receive action events fired by the button.
466: * Unrecognized keys or values will be ignored.
467: *
468: * @param s the <code>ObjectInputStream</code> to read
469: * @exception HeadlessException if
470: * <code>GraphicsEnvironment.isHeadless</code> returns
471: * <code>true</code>
472: * @serial
473: * @see #removeActionListener(ActionListener)
474: * @see #addActionListener(ActionListener)
475: * @see java.awt.GraphicsEnvironment#isHeadless
476: * @see #writeObject(ObjectOutputStream)
477: */
478: private void readObject(ObjectInputStream s)
479: throws ClassNotFoundException, IOException,
480: HeadlessException {
481: GraphicsEnvironment.checkHeadless();
482: s.defaultReadObject();
483:
484: Object keyOrNull;
485: while (null != (keyOrNull = s.readObject())) {
486: String key = ((String) keyOrNull).intern();
487:
488: if (actionListenerK == key)
489: addActionListener((ActionListener) (s.readObject()));
490:
491: else
492: // skip value for unrecognized key
493: s.readObject();
494: }
495: }
496:
497: /////////////////
498: // Accessibility support
499: ////////////////
500:
501: /**
502: * Gets the <code>AccessibleContext</code> associated with
503: * this <code>Button</code>. For buttons, the
504: * <code>AccessibleContext</code> takes the form of an
505: * <code>AccessibleAWTButton</code>.
506: * A new <code>AccessibleAWTButton</code> instance is
507: * created if necessary.
508: *
509: * @return an <code>AccessibleAWTButton</code> that serves as the
510: * <code>AccessibleContext</code> of this <code>Button</code>
511: * @beaninfo
512: * expert: true
513: * description: The AccessibleContext associated with this Button.
514: * @since 1.3
515: */
516: public AccessibleContext getAccessibleContext() {
517: if (accessibleContext == null) {
518: accessibleContext = new AccessibleAWTButton();
519: }
520: return accessibleContext;
521: }
522:
523: /**
524: * This class implements accessibility support for the
525: * <code>Button</code> class. It provides an implementation of the
526: * Java Accessibility API appropriate to button user-interface elements.
527: * @since 1.3
528: */
529: protected class AccessibleAWTButton extends AccessibleAWTComponent
530: implements AccessibleAction, AccessibleValue {
531: /*
532: * JDK 1.3 serialVersionUID
533: */
534: private static final long serialVersionUID = -5932203980244017102L;
535:
536: /**
537: * Get the accessible name of this object.
538: *
539: * @return the localized name of the object -- can be null if this
540: * object does not have a name
541: */
542: public String getAccessibleName() {
543: if (accessibleName != null) {
544: return accessibleName;
545: } else {
546: if (getLabel() == null) {
547: return super .getAccessibleName();
548: } else {
549: return getLabel();
550: }
551: }
552: }
553:
554: /**
555: * Get the AccessibleAction associated with this object. In the
556: * implementation of the Java Accessibility API for this class,
557: * return this object, which is responsible for implementing the
558: * AccessibleAction interface on behalf of itself.
559: *
560: * @return this object
561: */
562: public AccessibleAction getAccessibleAction() {
563: return this ;
564: }
565:
566: /**
567: * Get the AccessibleValue associated with this object. In the
568: * implementation of the Java Accessibility API for this class,
569: * return this object, which is responsible for implementing the
570: * AccessibleValue interface on behalf of itself.
571: *
572: * @return this object
573: */
574: public AccessibleValue getAccessibleValue() {
575: return this ;
576: }
577:
578: /**
579: * Returns the number of Actions available in this object. The
580: * default behavior of a button is to have one action - toggle
581: * the button.
582: *
583: * @return 1, the number of Actions in this object
584: */
585: public int getAccessibleActionCount() {
586: return 1;
587: }
588:
589: /**
590: * Return a description of the specified action of the object.
591: *
592: * @param i zero-based index of the actions
593: */
594: public String getAccessibleActionDescription(int i) {
595: if (i == 0) {
596: // [[[PENDING: WDW -- need to provide a localized string]]]
597: return new String("click");
598: } else {
599: return null;
600: }
601: }
602:
603: /**
604: * Perform the specified Action on the object
605: *
606: * @param i zero-based index of actions
607: * @return true if the the action was performed; else false.
608: */
609: public boolean doAccessibleAction(int i) {
610: if (i == 0) {
611: // Simulate a button click
612: Toolkit.getEventQueue().postEvent(
613: new ActionEvent(Button.this ,
614: ActionEvent.ACTION_PERFORMED,
615: Button.this .getActionCommand()));
616: return true;
617: } else {
618: return false;
619: }
620: }
621:
622: /**
623: * Get the value of this object as a Number.
624: *
625: * @return An Integer of 0 if this isn't selected or an Integer of 1 if
626: * this is selected.
627: * @see javax.swing.AbstractButton#isSelected()
628: */
629: public Number getCurrentAccessibleValue() {
630: return Integer.valueOf(0);
631: }
632:
633: /**
634: * Set the value of this object as a Number.
635: *
636: * @return True if the value was set.
637: */
638: public boolean setCurrentAccessibleValue(Number n) {
639: return false;
640: }
641:
642: /**
643: * Get the minimum value of this object as a Number.
644: *
645: * @return An Integer of 0.
646: */
647: public Number getMinimumAccessibleValue() {
648: return Integer.valueOf(0);
649: }
650:
651: /**
652: * Get the maximum value of this object as a Number.
653: *
654: * @return An Integer of 0.
655: */
656: public Number getMaximumAccessibleValue() {
657: return Integer.valueOf(0);
658: }
659:
660: /**
661: * Get the role of this object.
662: *
663: * @return an instance of AccessibleRole describing the role of the
664: * object
665: * @see AccessibleRole
666: */
667: public AccessibleRole getAccessibleRole() {
668: return AccessibleRole.PUSH_BUTTON;
669: }
670: } // inner class AccessibleAWTButton
671:
672: }
|
