1 /*
   2  * Copyright (c) 1997, 2015, 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.beans.JavaBean;
  28 import java.beans.BeanProperty;
  29 
  30 import javax.swing.plaf.*;
  31 import javax.accessibility.*;
  32 
  33 import java.io.ObjectOutputStream;
  34 import java.io.ObjectInputStream;
  35 import java.io.IOException;
  36 
  37 /**
  38  * An implementation of a check box -- an item that can be selected or
  39  * deselected, and which displays its state to the user.
  40  * By convention, any number of check boxes in a group can be selected.
  41  * See <a href="https://docs.oracle.com/javase/tutorial/uiswing/components/button.html">How to Use Buttons, Check Boxes, and Radio Buttons</a>
  42  * in <em>The Java Tutorial</em>
  43  * for examples and information on using check boxes.
  44  * <p>
  45  * Buttons can be configured, and to some degree controlled, by
  46  * <code><a href="Action.html">Action</a></code>s.  Using an
  47  * <code>Action</code> with a button has many benefits beyond directly
  48  * configuring a button.  Refer to <a href="Action.html#buttonActions">
  49  * Swing Components Supporting <code>Action</code></a> for more
  50  * details, and you can find more information in <a
  51  * href="https://docs.oracle.com/javase/tutorial/uiswing/misc/action.html">How
  52  * to Use Actions</a>, a section in <em>The Java Tutorial</em>.
  53  * <p>
  54  * <strong>Warning:</strong> Swing is not thread safe. For more
  55  * information see <a
  56  * href="package-summary.html#threading">Swing's Threading
  57  * Policy</a>.
  58  * <p>
  59  * <strong>Warning:</strong>
  60  * Serialized objects of this class will not be compatible with
  61  * future Swing releases. The current serialization support is
  62  * appropriate for short term storage or RMI between applications running
  63  * the same version of Swing.  As of 1.4, support for long term storage
  64  * of all JavaBeans&trade;
  65  * has been added to the <code>java.beans</code> package.
  66  * Please see {@link java.beans.XMLEncoder}.
  67  *
  68  * @see JRadioButton
  69  *
  70  * @author Jeff Dinkins
  71  * @since 1.2
  72  */
  73 @JavaBean(description = "A component which can be selected or deselected.")
  74 @SwingContainer(false)
  75 @SuppressWarnings("serial") // Same-version serialization only
  76 public class JCheckBox extends JToggleButton implements Accessible {
  77 
  78     /** Identifies a change to the flat property. */
  79     public static final String BORDER_PAINTED_FLAT_CHANGED_PROPERTY = "borderPaintedFlat";
  80 
  81     private boolean flat = false;
  82 
  83     /**
  84      * @see #getUIClassID
  85      * @see #readObject
  86      */
  87     private static final String uiClassID = "CheckBoxUI";
  88 
  89 
  90     /**
  91      * Creates an initially unselected check box button with no text, no icon.
  92      */
  93     public JCheckBox () {
  94         this(null, null, false);
  95     }
  96 
  97     /**
  98      * Creates an initially unselected check box with an icon.
  99      *
 100      * @param icon  the Icon image to display
 101      */
 102     public JCheckBox(Icon icon) {
 103         this(null, icon, false);
 104     }
 105 
 106     /**
 107      * Creates a check box with an icon and specifies whether
 108      * or not it is initially selected.
 109      *
 110      * @param icon  the Icon image to display
 111      * @param selected a boolean value indicating the initial selection
 112      *        state. If <code>true</code> the check box is selected
 113      */
 114     public JCheckBox(Icon icon, boolean selected) {
 115         this(null, icon, selected);
 116     }
 117 
 118     /**
 119      * Creates an initially unselected check box with text.
 120      *
 121      * @param text the text of the check box.
 122      */
 123     public JCheckBox (String text) {
 124         this(text, null, false);
 125     }
 126 
 127     /**
 128      * Creates a check box where properties are taken from the
 129      * Action supplied.
 130      *
 131      * @param a the {@code Action} used to specify the new check box
 132      * @since 1.3
 133      */
 134     public JCheckBox(Action a) {
 135         this();
 136         setAction(a);
 137     }
 138 
 139 
 140     /**
 141      * Creates a check box with text and specifies whether
 142      * or not it is initially selected.
 143      *
 144      * @param text the text of the check box.
 145      * @param selected a boolean value indicating the initial selection
 146      *        state. If <code>true</code> the check box is selected
 147      */
 148     public JCheckBox (String text, boolean selected) {
 149         this(text, null, selected);
 150     }
 151 
 152     /**
 153      * Creates an initially unselected check box with
 154      * the specified text and icon.
 155      *
 156      * @param text the text of the check box.
 157      * @param icon  the Icon image to display
 158      */
 159     public JCheckBox(String text, Icon icon) {
 160         this(text, icon, false);
 161     }
 162 
 163     /**
 164      * Creates a check box with text and icon,
 165      * and specifies whether or not it is initially selected.
 166      *
 167      * @param text the text of the check box.
 168      * @param icon  the Icon image to display
 169      * @param selected a boolean value indicating the initial selection
 170      *        state. If <code>true</code> the check box is selected
 171      */
 172     public JCheckBox (String text, Icon icon, boolean selected) {
 173         super(text, icon, selected);
 174         setUIProperty("borderPainted", Boolean.FALSE);
 175         setHorizontalAlignment(LEADING);
 176     }
 177 
 178     /**
 179      * Sets the <code>borderPaintedFlat</code> property,
 180      * which gives a hint to the look and feel as to the
 181      * appearance of the check box border.
 182      * This is usually set to <code>true</code> when a
 183      * <code>JCheckBox</code> instance is used as a
 184      * renderer in a component such as a <code>JTable</code> or
 185      * <code>JTree</code>.  The default value for the
 186      * <code>borderPaintedFlat</code> property is <code>false</code>.
 187      * This method fires a property changed event.
 188      * Some look and feels might not implement flat borders;
 189      * they will ignore this property.
 190      *
 191      * @param b <code>true</code> requests that the border be painted flat;
 192      *          <code>false</code> requests normal borders
 193      * @see #isBorderPaintedFlat
 194      * @since 1.3
 195      */
 196     @BeanProperty(visualUpdate = true, description
 197             = "Whether the border is painted flat.")
 198     public void setBorderPaintedFlat(boolean b) {
 199         boolean oldValue = flat;
 200         flat = b;
 201         firePropertyChange(BORDER_PAINTED_FLAT_CHANGED_PROPERTY, oldValue, flat);
 202         if (b != oldValue) {
 203             revalidate();
 204             repaint();
 205         }
 206     }
 207 
 208     /**
 209      * Gets the value of the <code>borderPaintedFlat</code> property.
 210      *
 211      * @return the value of the <code>borderPaintedFlat</code> property
 212      * @see #setBorderPaintedFlat
 213      * @since 1.3
 214      */
 215     public boolean isBorderPaintedFlat() {
 216         return flat;
 217     }
 218 
 219     /**
 220      * Resets the UI property to a value from the current look and feel.
 221      *
 222      * @see JComponent#updateUI
 223      */
 224     public void updateUI() {
 225         setUI((ButtonUI)UIManager.getUI(this));
 226     }
 227 
 228 
 229     /**
 230      * Returns a string that specifies the name of the L&amp;F class
 231      * that renders this component.
 232      *
 233      * @return the string "CheckBoxUI"
 234      * @see JComponent#getUIClassID
 235      * @see UIDefaults#getUI
 236      */
 237     @BeanProperty(bound = false, expert = true, description
 238             = "A string that specifies the name of the L&F class")
 239     public String getUIClassID() {
 240         return uiClassID;
 241     }
 242 
 243 
 244     /**
 245      * The icon for checkboxs comes from the look and feel,
 246      * not the Action; this is overriden to do nothing.
 247      */
 248     void setIconFromAction(Action a) {
 249     }
 250 
 251      /*
 252       * See readObject and writeObject in JComponent for more
 253       * information about serialization in Swing.
 254       */
 255      private void writeObject(ObjectOutputStream s) throws IOException {
 256         s.defaultWriteObject();
 257         if (getUIClassID().equals(uiClassID)) {
 258             byte count = JComponent.getWriteObjCounter(this);
 259             JComponent.setWriteObjCounter(this, --count);
 260             if (count == 0 && ui != null) {
 261                 ui.installUI(this);
 262             }
 263         }
 264      }
 265 
 266 
 267     /**
 268      * See JComponent.readObject() for information about serialization
 269      * in Swing.
 270      */
 271     private void readObject(ObjectInputStream s)
 272         throws IOException, ClassNotFoundException
 273     {
 274         s.defaultReadObject();
 275         if (getUIClassID().equals(uiClassID)) {
 276             updateUI();
 277         }
 278     }
 279 
 280 
 281     /**
 282      * Returns a string representation of this JCheckBox. This method
 283      * is intended to be used only for debugging purposes, and the
 284      * content and format of the returned string may vary between
 285      * implementations. The returned string may be empty but may not
 286      * be <code>null</code>.
 287      * specific new aspects of the JFC components.
 288      *
 289      * @return  a string representation of this JCheckBox.
 290      */
 291     protected String paramString() {
 292         return super.paramString();
 293     }
 294 
 295 /////////////////
 296 // Accessibility support
 297 ////////////////
 298 
 299     /**
 300      * Gets the AccessibleContext associated with this JCheckBox.
 301      * For JCheckBoxes, the AccessibleContext takes the form of an
 302      * AccessibleJCheckBox.
 303      * A new AccessibleJCheckBox instance is created if necessary.
 304      *
 305      * @return an AccessibleJCheckBox that serves as the
 306      *         AccessibleContext of this JCheckBox
 307      */
 308     @BeanProperty(bound = false, expert = true, description
 309             = "The AccessibleContext associated with this CheckBox.")
 310     public AccessibleContext getAccessibleContext() {
 311         if (accessibleContext == null) {
 312             accessibleContext = new AccessibleJCheckBox();
 313         }
 314         return accessibleContext;
 315     }
 316 
 317     /**
 318      * This class implements accessibility support for the
 319      * <code>JCheckBox</code> class.  It provides an implementation of the
 320      * Java Accessibility API appropriate to check box user-interface
 321      * elements.
 322      * <p>
 323      * <strong>Warning:</strong>
 324      * Serialized objects of this class will not be compatible with
 325      * future Swing releases. The current serialization support is
 326      * appropriate for short term storage or RMI between applications running
 327      * the same version of Swing.  As of 1.4, support for long term storage
 328      * of all JavaBeans&trade;
 329      * has been added to the <code>java.beans</code> package.
 330      * Please see {@link java.beans.XMLEncoder}.
 331      */
 332     @SuppressWarnings("serial") // Same-version serialization only
 333     protected class AccessibleJCheckBox extends AccessibleJToggleButton {
 334 
 335         /**
 336          * Get the role of this object.
 337          *
 338          * @return an instance of AccessibleRole describing the role of the object
 339          * @see AccessibleRole
 340          */
 341         public AccessibleRole getAccessibleRole() {
 342             return AccessibleRole.CHECK_BOX;
 343         }
 344 
 345     } // inner class AccessibleJCheckBox
 346 }