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