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 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 @SuppressWarnings("serial") 75 public class JSeparator extends JComponent implements SwingConstants, Accessible 76 { 77 /** 78 * @see #getUIClassID 79 * @see #readObject 80 */ 81 private static final String uiClassID = "SeparatorUI"; 82 83 private int orientation = HORIZONTAL; 84 85 /** Creates a new horizontal separator. */ 86 public JSeparator() 87 { 88 this( HORIZONTAL ); 89 } 90 91 /** 92 * Creates a new separator with the specified horizontal or 93 * vertical orientation. 94 * 95 * @param orientation an integer specifying 96 * <code>SwingConstants.HORIZONTAL</code> or 97 * <code>SwingConstants.VERTICAL</code> 98 * @exception IllegalArgumentException if <code>orientation</code> 99 * is neither <code>SwingConstants.HORIZONTAL</code> nor 100 * <code>SwingConstants.VERTICAL</code> 101 */ 102 public JSeparator( int orientation ) 103 { 104 checkOrientation( orientation ); 105 this.orientation = orientation; 106 setFocusable(false); 107 updateUI(); 108 } 109 110 /** 111 * Returns the L&F object that renders this component. 112 * 113 * @return the SeparatorUI object that renders this component 114 */ 115 public SeparatorUI getUI() { 116 return (SeparatorUI)ui; 117 } 118 119 /** 120 * Sets the L&F object that renders this component. 121 * 122 * @param ui the SeparatorUI L&F object 123 * @see UIDefaults#getUI 124 * @beaninfo 125 * bound: true 126 * hidden: true 127 * attribute: visualUpdate true 128 * description: The UI object that implements the Component's LookAndFeel. 129 */ 130 public void setUI(SeparatorUI ui) { 131 super.setUI(ui); 132 } 133 134 /** 135 * Resets the UI property to a value from the current look and feel. 136 * 137 * @see JComponent#updateUI 138 */ 139 public void updateUI() { 140 setUI((SeparatorUI)UIManager.getUI(this)); 141 } 142 143 144 /** 145 * Returns the name of the L&F class that renders this component. 146 * 147 * @return the string "SeparatorUI" 148 * @see JComponent#getUIClassID 149 * @see UIDefaults#getUI 150 */ 151 public String getUIClassID() { 152 return uiClassID; 153 } 154 155 156 /** 157 * See <code>readObject</code> and <code>writeObject</code> in 158 * <code>JComponent</code> for more 159 * information about serialization in Swing. 160 */ 161 private void writeObject(ObjectOutputStream s) throws IOException { 162 s.defaultWriteObject(); 163 if (getUIClassID().equals(uiClassID)) { 164 byte count = JComponent.getWriteObjCounter(this); 165 JComponent.setWriteObjCounter(this, --count); 166 if (count == 0 && ui != null) { 167 ui.installUI(this); 168 } 169 } 170 } 171 172 /** 173 * Returns the orientation of this separator. 174 * 175 * @return The value of the orientation property, one of the 176 * following constants defined in <code>SwingConstants</code>: 177 * <code>VERTICAL</code>, or 178 * <code>HORIZONTAL</code>. 179 * 180 * @see SwingConstants 181 * @see #setOrientation 182 */ 183 public int getOrientation() { 184 return this.orientation; 185 } 186 187 /** 188 * Sets the orientation of the separator. 189 * The default value of this property is HORIZONTAL. 190 * @param orientation either <code>SwingConstants.HORIZONTAL</code> 191 * or <code>SwingConstants.VERTICAL</code> 192 * @exception IllegalArgumentException if <code>orientation</code> 193 * is neither <code>SwingConstants.HORIZONTAL</code> 194 * nor <code>SwingConstants.VERTICAL</code> 195 * 196 * @see SwingConstants 197 * @see #getOrientation 198 * @beaninfo 199 * bound: true 200 * preferred: true 201 * enum: HORIZONTAL SwingConstants.HORIZONTAL 202 * VERTICAL SwingConstants.VERTICAL 203 * attribute: visualUpdate true 204 * description: The orientation of the separator. 205 */ 206 public void setOrientation( int orientation ) { 207 if (this.orientation == orientation) { 208 return; 209 } 210 int oldValue = this.orientation; 211 checkOrientation( orientation ); 212 this.orientation = orientation; 213 firePropertyChange("orientation", oldValue, orientation); 214 revalidate(); 215 repaint(); 216 } 217 218 private void checkOrientation( int orientation ) 219 { 220 switch ( orientation ) 221 { 222 case VERTICAL: 223 case HORIZONTAL: 224 break; 225 default: 226 throw new IllegalArgumentException( "orientation must be one of: VERTICAL, HORIZONTAL" ); 227 } 228 } 229 230 231 /** 232 * Returns a string representation of this <code>JSeparator</code>. 233 * This method 234 * is intended to be used only for debugging purposes, and the 235 * content and format of the returned string may vary between 236 * implementations. The returned string may be empty but may not 237 * be <code>null</code>. 238 * 239 * @return a string representation of this <code>JSeparator</code> 240 */ 241 protected String paramString() { 242 String orientationString = (orientation == HORIZONTAL ? 243 "HORIZONTAL" : "VERTICAL"); 244 245 return super.paramString() + 246 ",orientation=" + orientationString; 247 } 248 249 ///////////////// 250 // Accessibility support 251 //////////////// 252 253 /** 254 * Gets the AccessibleContext associated with this JSeparator. 255 * For separators, the AccessibleContext takes the form of an 256 * AccessibleJSeparator. 257 * A new AccessibleJSeparator instance is created if necessary. 258 * 259 * @return an AccessibleJSeparator that serves as the 260 * AccessibleContext of this JSeparator 261 */ 262 public AccessibleContext getAccessibleContext() { 263 if (accessibleContext == null) { 264 accessibleContext = new AccessibleJSeparator(); 265 } 266 return accessibleContext; 267 } 268 269 /** 270 * This class implements accessibility support for the 271 * <code>JSeparator</code> class. It provides an implementation of the 272 * Java Accessibility API appropriate to separator user-interface elements. 273 * <p> 274 * <strong>Warning:</strong> 275 * Serialized objects of this class will not be compatible with 276 * future Swing releases. The current serialization support is 277 * appropriate for short term storage or RMI between applications running 278 * the same version of Swing. As of 1.4, support for long term storage 279 * of all JavaBeans<sup><font size="-2">TM</font></sup> 280 * has been added to the <code>java.beans</code> package. 281 * Please see {@link java.beans.XMLEncoder}. 282 */ 283 @SuppressWarnings("serial") 284 protected class AccessibleJSeparator extends AccessibleJComponent { 285 286 /** 287 * Get the role of this object. 288 * 289 * @return an instance of AccessibleRole describing the role of the 290 * object 291 */ 292 public AccessibleRole getAccessibleRole() { 293 return AccessibleRole.SEPARATOR; 294 } 295 } 296 }