1 /*

     2  * Copyright 1997-2006 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package javax.swing;

    27 

    28 import javax.swing.plaf.*;

    29 import javax.accessibility.*;

    30 

    31 import java.io.ObjectOutputStream;

    32 import java.io.ObjectInputStream;

    33 import java.io.IOException;

    34 

    35 

    36 /**

    37  * <code>JSeparator</code> provides a general purpose component for

    38  * implementing divider lines - most commonly used as a divider

    39  * between menu items that breaks them up into logical groupings.

    40  * Instead of using <code>JSeparator</code> directly,

    41  * you can use the <code>JMenu</code> or <code>JPopupMenu</code>

    42  * <code>addSeparator</code> method to create and add a separator.

    43  * <code>JSeparator</code>s may also be used elsewhere in a GUI

    44  * wherever a visual divider is useful.

    45  *

    46  * <p>

    47  *

    48  * For more information and examples see

    49  * <a

    50  href="http://java.sun.com/docs/books/tutorial/uiswing/components/menu.html">How to Use Menus</a>,

    51  * a section in <em>The Java Tutorial.</em>

    52  * <p>

    53  * <strong>Warning:</strong> Swing is not thread safe. For more

    54  * information see <a

    55  * href="package-summary.html#threading">Swing's Threading

    56  * Policy</a>.

    57  * <p>

    58  * <strong>Warning:</strong>

    59  * Serialized objects of this class will not be compatible with

    60  * future Swing releases. The current serialization support is

    61  * appropriate for short term storage or RMI between applications running

    62  * the same version of Swing.  As of 1.4, support for long term storage

    63  * of all JavaBeans<sup><font size="-2">TM</font></sup>

    64  * has been added to the <code>java.beans</code> package.

    65  * Please see {@link java.beans.XMLEncoder}.

    66  *

    67  * @beaninfo

    68  *      attribute: isContainer false

    69  *    description: A divider between menu items.

    70  *

    71  * @author Georges Saab

    72  * @author Jeff Shapiro

    73  */

    74 public class JSeparator extends JComponent implements SwingConstants, Accessible

    75 {

    76     /**

    77      * @see #getUIClassID

    78      * @see #readObject

    79      */

    80     private static final String uiClassID = "SeparatorUI";

    81 

    82     private int orientation = HORIZONTAL;

    83 

    84     /** Creates a new horizontal separator. */

    85     public JSeparator()

    86     {

    87         this( HORIZONTAL );

    88     }

    89 

    90     /**

    91      * Creates a new separator with the specified horizontal or

    92      * vertical orientation.

    93      *

    94      * @param orientation an integer specifying

    95      *          <code>SwingConstants.HORIZONTAL</code> or

    96      *          <code>SwingConstants.VERTICAL</code>

    97      * @exception IllegalArgumentException if <code>orientation</code>

    98      *          is neither <code>SwingConstants.HORIZONTAL</code> nor

    99      *          <code>SwingConstants.VERTICAL</code>

   100      */

   101     public JSeparator( int orientation )

   102     {

   103         checkOrientation( orientation );

   104         this.orientation = orientation;

   105         setFocusable(false);

   106         updateUI();

   107     }

   108 

   109     /**

   110      * Returns the L&F object that renders this component.

   111      *

   112      * @return the SeparatorUI object that renders this component

   113      */

   114     public SeparatorUI getUI() {

   115         return (SeparatorUI)ui;

   116     }

   117 

   118     /**

   119      * Sets the L&F object that renders this component.

   120      *

   121      * @param ui  the SeparatorUI L&F object

   122      * @see UIDefaults#getUI

   123      * @beaninfo

   124      *        bound: true

   125      *       hidden: true

   126      *    attribute: visualUpdate true

   127      *  description: The UI object that implements the Component's LookAndFeel.

   128      */

   129     public void setUI(SeparatorUI ui) {

   130         super.setUI(ui);

   131     }

   132 

   133     /**

   134      * Resets the UI property to a value from the current look and feel.

   135      *

   136      * @see JComponent#updateUI

   137      */

   138     public void updateUI() {

   139         setUI((SeparatorUI)UIManager.getUI(this));

   140     }

   141 

   142 

   143     /**

   144      * Returns the name of the L&F class that renders this component.

   145      *

   146      * @return the string "SeparatorUI"

   147      * @see JComponent#getUIClassID

   148      * @see UIDefaults#getUI

   149      */

   150     public String getUIClassID() {

   151         return uiClassID;

   152     }

   153 

   154 

   155     /**

   156      * See <code>readObject</code> and <code>writeObject</code> in

   157      * <code>JComponent</code> for more

   158      * information about serialization in Swing.

   159      */

   160     private void writeObject(ObjectOutputStream s) throws IOException {

   161         s.defaultWriteObject();

   162         if (getUIClassID().equals(uiClassID)) {

   163             byte count = JComponent.getWriteObjCounter(this);

   164             JComponent.setWriteObjCounter(this, --count);

   165             if (count == 0 && ui != null) {

   166                 ui.installUI(this);

   167             }

   168         }

   169     }

   170 

   171     /**

   172      * Returns the orientation of this separator.

   173      *

   174      * @return   The value of the orientation property, one of the

   175      *           following constants defined in <code>SwingConstants</code>:

   176      *           <code>VERTICAL</code>, or

   177      *           <code>HORIZONTAL</code>.

   178      *

   179      * @see SwingConstants

   180      * @see #setOrientation

   181      */

   182     public int getOrientation() {

   183         return this.orientation;

   184     }

   185 

   186     /**

   187      * Sets the orientation of the separator.

   188      * The default value of this property is HORIZONTAL.

   189      * @param orientation  either <code>SwingConstants.HORIZONTAL</code>

   190      *                  or <code>SwingConstants.VERTICAL</code>

   191      * @exception IllegalArgumentException  if <code>orientation</code>

   192      *          is neither <code>SwingConstants.HORIZONTAL</code>

   193      *          nor <code>SwingConstants.VERTICAL</code>

   194      *

   195      * @see SwingConstants

   196      * @see #getOrientation

   197      * @beaninfo

   198      *        bound: true

   199      *    preferred: true

   200      *         enum: HORIZONTAL SwingConstants.HORIZONTAL

   201      *               VERTICAL   SwingConstants.VERTICAL

   202      *    attribute: visualUpdate true

   203      *  description: The orientation of the separator.

   204      */

   205     public void setOrientation( int orientation ) {

   206         if (this.orientation == orientation) {

   207             return;

   208         }

   209         int oldValue = this.orientation;

   210         checkOrientation( orientation );

   211         this.orientation = orientation;

   212         firePropertyChange("orientation", oldValue, orientation);

   213         revalidate();

   214         repaint();

   215     }

   216 

   217     private void checkOrientation( int orientation )

   218     {

   219         switch ( orientation )

   220         {

   221             case VERTICAL:

   222             case HORIZONTAL:

   223                 break;

   224             default:

   225                 throw new IllegalArgumentException( "orientation must be one of: VERTICAL, HORIZONTAL" );

   226         }

   227     }

   228 

   229 

   230     /**

   231      * Returns a string representation of this <code>JSeparator</code>.

   232      * This method

   233      * is intended to be used only for debugging purposes, and the

   234      * content and format of the returned string may vary between

   235      * implementations. The returned string may be empty but may not

   236      * be <code>null</code>.

   237      *

   238      * @return  a string representation of this <code>JSeparator</code>

   239      */

   240     protected String paramString() {

   241         String orientationString = (orientation == HORIZONTAL ?

   242                                     "HORIZONTAL" : "VERTICAL");

   243 

   244         return super.paramString() +

   245         ",orientation=" + orientationString;

   246     }

   247 

   248 /////////////////

   249 // Accessibility support

   250 ////////////////

   251 

   252     /**

   253      * Gets the AccessibleContext associated with this JSeparator.

   254      * For separators, the AccessibleContext takes the form of an

   255      * AccessibleJSeparator.

   256      * A new AccessibleJSeparator instance is created if necessary.

   257      *

   258      * @return an AccessibleJSeparator that serves as the

   259      *         AccessibleContext of this JSeparator

   260      */

   261     public AccessibleContext getAccessibleContext() {

   262         if (accessibleContext == null) {

   263             accessibleContext = new AccessibleJSeparator();

   264         }

   265         return accessibleContext;

   266     }

   267 

   268     /**

   269      * This class implements accessibility support for the

   270      * <code>JSeparator</code> class.  It provides an implementation of the

   271      * Java Accessibility API appropriate to separator user-interface elements.

   272      * <p>

   273      * <strong>Warning:</strong>

   274      * Serialized objects of this class will not be compatible with

   275      * future Swing releases. The current serialization support is

   276      * appropriate for short term storage or RMI between applications running

   277      * the same version of Swing.  As of 1.4, support for long term storage

   278      * of all JavaBeans<sup><font size="-2">TM</font></sup>

   279      * has been added to the <code>java.beans</code> package.

   280      * Please see {@link java.beans.XMLEncoder}.

   281      */

   282     protected class AccessibleJSeparator extends AccessibleJComponent {

   283 

   284         /**

   285          * Get the role of this object.

   286          *

   287          * @return an instance of AccessibleRole describing the role of the

   288          * object

   289          */

   290         public AccessibleRole getAccessibleRole() {

   291             return AccessibleRole.SEPARATOR;

   292         }

   293     }

   294 }