1 /*
   2  * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package javax.swing;
  26 
  27 import java.awt.*;
  28 import java.awt.event.*;
  29 import java.beans.*;
  30 
  31 import javax.swing.plaf.*;
  32 import javax.accessibility.*;
  33 
  34 import java.io.ObjectOutputStream;
  35 import java.io.ObjectInputStream;
  36 import java.io.IOException;
  37 
  38 
  39 /**
  40  * An implementation of a radio button -- an item that can be selected or
  41  * deselected, and which displays its state to the user.
  42  * Used with a {@link ButtonGroup} object to create a group of buttons
  43  * in which only one button at a time can be selected. (Create a ButtonGroup
  44  * object and use its <code>add</code> method to include the JRadioButton objects
  45  * in the group.)
  46  * <blockquote>
  47  * <strong>Note:</strong>
  48  * The ButtonGroup object is a logical grouping -- not a physical grouping.
  49  * To create a button panel, you should still create a {@link JPanel} or similar
  50  * container-object and add a {@link javax.swing.border.Border} to it to set it off from surrounding
  51  * components.
  52  * </blockquote>
  53  * <p>
  54  * Buttons can be configured, and to some degree controlled, by
  55  * <code><a href="Action.html">Action</a></code>s.  Using an
  56  * <code>Action</code> with a button has many benefits beyond directly
  57  * configuring a button.  Refer to <a href="Action.html#buttonActions">
  58  * Swing Components Supporting <code>Action</code></a> for more
  59  * details, and you can find more information in <a
  60  * href="http://java.sun.com/docs/books/tutorial/uiswing/misc/action.html">How
  61  * to Use Actions</a>, a section in <em>The Java Tutorial</em>.
  62  * <p>
  63  * See <a href="http://java.sun.com/docs/books/tutorial/uiswing/components/button.html">How to Use Buttons, Check Boxes, and Radio Buttons</a>
  64  * in <em>The Java Tutorial</em>
  65  * for further documentation.
  66  * <p>
  67  * <strong>Warning:</strong> Swing is not thread safe. For more
  68  * information see <a
  69  * href="package-summary.html#threading">Swing's Threading
  70  * Policy</a>.
  71  * <p>
  72  * <strong>Warning:</strong>
  73  * Serialized objects of this class will not be compatible with
  74  * future Swing releases. The current serialization support is
  75  * appropriate for short term storage or RMI between applications running
  76  * the same version of Swing.  As of 1.4, support for long term storage
  77  * of all JavaBeans<sup><font size="-2">TM</font></sup>
  78  * has been added to the <code>java.beans</code> package.
  79  * Please see {@link java.beans.XMLEncoder}.
  80  *
  81  * @beaninfo
  82  *   attribute: isContainer false
  83  * description: A component which can display it's state as selected or deselected.
  84  *
  85  * @see ButtonGroup
  86  * @see JCheckBox
  87  * @author Jeff Dinkins
  88  */
  89 public class JRadioButton extends JToggleButton implements Accessible {
  90 
  91     /**
  92      * @see #getUIClassID
  93      * @see #readObject
  94      */
  95     private static final String uiClassID = "RadioButtonUI";
  96 
  97 
  98     /**
  99      * Creates an initially unselected radio button
 100      * with no set text.
 101      */
 102     public JRadioButton () {
 103         this(null, null, false);
 104     }
 105 
 106     /**
 107      * Creates an initially unselected radio button
 108      * with the specified image but no text.
 109      *
 110      * @param icon  the image that the button should display
 111      */
 112     public JRadioButton(Icon icon) {
 113         this(null, icon, false);
 114     }
 115 
 116     /**
 117      * Creates a radiobutton where properties are taken from the
 118      * Action supplied.
 119      *
 120      * @since 1.3
 121      */
 122     public JRadioButton(Action a) {
 123         this();
 124         setAction(a);
 125     }
 126 
 127     /**
 128      * Creates a radio button with the specified image
 129      * and selection state, but no text.
 130      *
 131      * @param icon  the image that the button should display
 132      * @param selected  if true, the button is initially selected;
 133      *                  otherwise, the button is initially unselected
 134      */
 135     public JRadioButton(Icon icon, boolean selected) {
 136         this(null, icon, selected);
 137     }
 138 
 139     /**
 140      * Creates an unselected radio button with the specified text.
 141      *
 142      * @param text  the string displayed on the radio button
 143      */
 144     public JRadioButton (String text) {
 145         this(text, null, false);
 146     }
 147 
 148     /**
 149      * Creates a radio button with the specified text
 150      * and selection state.
 151      *
 152      * @param text  the string displayed on the radio button
 153      * @param selected  if true, the button is initially selected;
 154      *                  otherwise, the button is initially unselected
 155      */
 156     public JRadioButton (String text, boolean selected) {
 157         this(text, null, selected);
 158     }
 159 
 160     /**
 161      * Creates a radio button that has the specified text and image,
 162      * and that is initially unselected.
 163      *
 164      * @param text  the string displayed on the radio button
 165      * @param icon  the image that the button should display
 166      */
 167     public JRadioButton(String text, Icon icon) {
 168         this(text, icon, false);
 169     }
 170 
 171     /**
 172      * Creates a radio button that has the specified text, image,
 173      * and selection state.
 174      *
 175      * @param text  the string displayed on the radio button
 176      * @param icon  the image that the button should display
 177      */
 178     public JRadioButton (String text, Icon icon, boolean selected) {
 179         super(text, icon, selected);
 180         setBorderPainted(false);
 181         setHorizontalAlignment(LEADING);
 182     }
 183 
 184 
 185     /**
 186      * Resets the UI property to a value from the current look and feel.
 187      *
 188      * @see JComponent#updateUI
 189      */
 190     public void updateUI() {
 191         setUI((ButtonUI)UIManager.getUI(this));
 192     }
 193 
 194 
 195     /**
 196      * Returns the name of the L&amp;F class
 197      * that renders this component.
 198      *
 199      * @return String "RadioButtonUI"
 200      * @see JComponent#getUIClassID
 201      * @see UIDefaults#getUI
 202      * @beaninfo
 203      *        expert: true
 204      *   description: A string that specifies the name of the L&amp;F class.
 205      */
 206     public String getUIClassID() {
 207         return uiClassID;
 208     }
 209 
 210 
 211     /**
 212      * The icon for radio buttons comes from the look and feel,
 213      * not the Action.
 214      */
 215     void setIconFromAction(Action a) {
 216     }
 217 
 218     /**
 219      * See readObject() and writeObject() in JComponent for more
 220      * information about serialization in Swing.
 221      */
 222     private void writeObject(ObjectOutputStream s) throws IOException {
 223         s.defaultWriteObject();
 224         if (getUIClassID().equals(uiClassID)) {
 225             byte count = JComponent.getWriteObjCounter(this);
 226             JComponent.setWriteObjCounter(this, --count);
 227             if (count == 0 && ui != null) {
 228                 ui.installUI(this);
 229             }
 230         }
 231     }
 232 
 233 
 234     /**
 235      * Returns a string representation of this JRadioButton. This method
 236      * is intended to be used only for debugging purposes, and the
 237      * content and format of the returned string may vary between
 238      * implementations. The returned string may be empty but may not
 239      * be <code>null</code>.
 240      *
 241      * @return  a string representation of this JRadioButton.
 242      */
 243     protected String paramString() {
 244         return super.paramString();
 245     }
 246 
 247 
 248 /////////////////
 249 // Accessibility support
 250 ////////////////
 251 
 252 
 253     /**
 254      * Gets the AccessibleContext associated with this JRadioButton.
 255      * For JRadioButtons, the AccessibleContext takes the form of an
 256      * AccessibleJRadioButton.
 257      * A new AccessibleJRadioButton instance is created if necessary.
 258      *
 259      * @return an AccessibleJRadioButton that serves as the
 260      *         AccessibleContext of this JRadioButton
 261      * @beaninfo
 262      *       expert: true
 263      *  description: The AccessibleContext associated with this Button
 264      */
 265     public AccessibleContext getAccessibleContext() {
 266         if (accessibleContext == null) {
 267             accessibleContext = new AccessibleJRadioButton();
 268         }
 269         return accessibleContext;
 270     }
 271 
 272     /**
 273      * This class implements accessibility support for the
 274      * <code>JRadioButton</code> class.  It provides an implementation of the
 275      * Java Accessibility API appropriate to radio button
 276      * user-interface elements.
 277      * <p>
 278      * <strong>Warning:</strong>
 279      * Serialized objects of this class will not be compatible with
 280      * future Swing releases. The current serialization support is
 281      * appropriate for short term storage or RMI between applications running
 282      * the same version of Swing.  As of 1.4, support for long term storage
 283      * of all JavaBeans<sup><font size="-2">TM</font></sup>
 284      * has been added to the <code>java.beans</code> package.
 285      * Please see {@link java.beans.XMLEncoder}.
 286      */
 287     protected class AccessibleJRadioButton extends AccessibleJToggleButton {
 288 
 289         /**
 290          * Get the role of this object.
 291          *
 292          * @return an instance of AccessibleRole describing the role of the object
 293          * @see AccessibleRole
 294          */
 295         public AccessibleRole getAccessibleRole() {
 296             return AccessibleRole.RADIO_BUTTON;
 297         }
 298 
 299     } // inner class AccessibleJRadioButton
 300 }