1 /* 2 * Copyright (c) 1995, 2014, 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 java.awt; 26 27 import java.awt.peer.LabelPeer; 28 import java.io.IOException; 29 import java.io.ObjectInputStream; 30 import javax.accessibility.*; 31 32 /** 33 * A <code>Label</code> object is a component for placing text in a 34 * container. A label displays a single line of read-only text. 35 * The text can be changed by the application, but a user cannot edit it 36 * directly. 37 * <p> 38 * For example, the code . . . 39 * 40 * <hr><blockquote><pre> 41 * setLayout(new FlowLayout(FlowLayout.CENTER, 10, 10)); 42 * add(new Label("Hi There!")); 43 * add(new Label("Another Label")); 44 * </pre></blockquote><hr> 45 * <p> 46 * produces the following labels: 47 * <p> 48 * <img src="doc-files/Label-1.gif" alt="Two labels: 'Hi There!' and 'Another label'" 49 * style="float:center; margin: 7px 10px;"> 50 * 51 * @author Sami Shaio 52 * @since 1.0 53 */ 54 public class Label extends Component implements Accessible { 55 56 static { 57 /* ensure that the necessary native libraries are loaded */ 58 Toolkit.loadLibraries(); 59 if (!GraphicsEnvironment.isHeadless()) { 60 initIDs(); 61 } 62 } 63 64 /** 65 * Indicates that the label should be left justified. 66 */ 67 public static final int LEFT = 0; 68 69 /** 70 * Indicates that the label should be centered. 71 */ 72 public static final int CENTER = 1; 73 74 /** 75 * Indicates that the label should be right justified. 76 */ 77 public static final int RIGHT = 2; 78 79 /** 80 * The text of this label. 81 * This text can be modified by the program 82 * but never by the user. 83 * 84 * @serial 85 * @see #getText() 86 * @see #setText(String) 87 */ 88 String text; 89 90 /** 91 * The label's alignment. The default alignment is set 92 * to be left justified. 93 * 94 * @serial 95 * @see #getAlignment() 96 * @see #setAlignment(int) 97 */ 98 int alignment = LEFT; 99 100 private static final String base = "label"; 101 private static int nameCounter = 0; 102 103 /* 104 * JDK 1.1 serialVersionUID 105 */ 106 private static final long serialVersionUID = 3094126758329070636L; 107 108 /** 109 * Constructs an empty label. 110 * The text of the label is the empty string <code>""</code>. 111 * @exception HeadlessException if GraphicsEnvironment.isHeadless() 112 * returns true. 113 * @see java.awt.GraphicsEnvironment#isHeadless 114 */ 115 public Label() throws HeadlessException { 116 this("", LEFT); 117 } 118 119 /** 120 * Constructs a new label with the specified string of text, 121 * left justified. 122 * @param text the string that the label presents. 123 * A <code>null</code> value 124 * will be accepted without causing a NullPointerException 125 * to be thrown. 126 * @exception HeadlessException if GraphicsEnvironment.isHeadless() 127 * returns true. 128 * @see java.awt.GraphicsEnvironment#isHeadless 129 */ 130 public Label(String text) throws HeadlessException { 131 this(text, LEFT); 132 } 133 134 /** 135 * Constructs a new label that presents the specified string of 136 * text with the specified alignment. 137 * Possible values for <code>alignment</code> are <code>Label.LEFT</code>, 138 * <code>Label.RIGHT</code>, and <code>Label.CENTER</code>. 139 * @param text the string that the label presents. 140 * A <code>null</code> value 141 * will be accepted without causing a NullPointerException 142 * to be thrown. 143 * @param alignment the alignment value. 144 * @exception HeadlessException if GraphicsEnvironment.isHeadless() 145 * returns true. 146 * @see java.awt.GraphicsEnvironment#isHeadless 147 */ 148 public Label(String text, int alignment) throws HeadlessException { 149 GraphicsEnvironment.checkHeadless(); 150 this.text = text; 151 setAlignment(alignment); 152 } 153 154 /** 155 * Read a label from an object input stream. 156 * @exception HeadlessException if 157 * <code>GraphicsEnvironment.isHeadless()</code> returns 158 * <code>true</code> 159 * @serial 160 * @since 1.4 161 * @see java.awt.GraphicsEnvironment#isHeadless 162 */ 163 private void readObject(ObjectInputStream s) 164 throws ClassNotFoundException, IOException, HeadlessException { 165 GraphicsEnvironment.checkHeadless(); 166 s.defaultReadObject(); 167 } 168 169 /** 170 * Construct a name for this component. Called by getName() when the 171 * name is <code>null</code>. 172 */ 173 String constructComponentName() { 174 synchronized (Label.class) { 175 return base + nameCounter++; 176 } 177 } 178 179 /** 180 * Creates the peer for this label. The peer allows us to 181 * modify the appearance of the label without changing its 182 * functionality. 183 */ 184 public void addNotify() { 185 synchronized (getTreeLock()) { 186 if (peer == null) 187 peer = getToolkit().createLabel(this); 188 super.addNotify(); 189 } 190 } 191 192 /** 193 * Gets the current alignment of this label. Possible values are 194 * <code>Label.LEFT</code>, <code>Label.RIGHT</code>, and 195 * <code>Label.CENTER</code>. 196 * @see java.awt.Label#setAlignment 197 */ 198 public int getAlignment() { 199 return alignment; 200 } 201 202 /** 203 * Sets the alignment for this label to the specified alignment. 204 * Possible values are <code>Label.LEFT</code>, 205 * <code>Label.RIGHT</code>, and <code>Label.CENTER</code>. 206 * @param alignment the alignment to be set. 207 * @exception IllegalArgumentException if an improper value for 208 * <code>alignment</code> is given. 209 * @see java.awt.Label#getAlignment 210 */ 211 public synchronized void setAlignment(int alignment) { 212 switch (alignment) { 213 case LEFT: 214 case CENTER: 215 case RIGHT: 216 this.alignment = alignment; 217 LabelPeer peer = (LabelPeer)this.peer; 218 if (peer != null) { 219 peer.setAlignment(alignment); 220 } 221 return; 222 } 223 throw new IllegalArgumentException("improper alignment: " + alignment); 224 } 225 226 /** 227 * Gets the text of this label. 228 * @return the text of this label, or <code>null</code> if 229 * the text has been set to <code>null</code>. 230 * @see java.awt.Label#setText 231 */ 232 public String getText() { 233 return text; 234 } 235 236 /** 237 * Sets the text for this label to the specified text. 238 * @param text the text that this label displays. If 239 * <code>text</code> is <code>null</code>, it is 240 * treated for display purposes like an empty 241 * string <code>""</code>. 242 * @see java.awt.Label#getText 243 */ 244 public void setText(String text) { 245 boolean testvalid = false; 246 synchronized (this) { 247 if (text != this.text && (this.text == null || 248 !this.text.equals(text))) { 249 this.text = text; 250 LabelPeer peer = (LabelPeer)this.peer; 251 if (peer != null) { 252 peer.setText(text); 253 } 254 testvalid = true; 255 } 256 } 257 258 // This could change the preferred size of the Component. 259 if (testvalid) { 260 invalidateIfValid(); 261 } 262 } 263 264 /** 265 * Returns a string representing the state of this <code>Label</code>. 266 * This method is intended to be used only for debugging purposes, and the 267 * content and format of the returned string may vary between 268 * implementations. The returned string may be empty but may not be 269 * <code>null</code>. 270 * 271 * @return the parameter string of this label 272 */ 273 protected String paramString() { 274 String align = ""; 275 switch (alignment) { 276 case LEFT: align = "left"; break; 277 case CENTER: align = "center"; break; 278 case RIGHT: align = "right"; break; 279 } 280 return super.paramString() + ",align=" + align + ",text=" + text; 281 } 282 283 /** 284 * Initialize JNI field and method IDs 285 */ 286 private static native void initIDs(); 287 288 289 ///////////////// 290 // Accessibility support 291 //////////////// 292 293 294 /** 295 * Gets the AccessibleContext associated with this Label. 296 * For labels, the AccessibleContext takes the form of an 297 * AccessibleAWTLabel. 298 * A new AccessibleAWTLabel instance is created if necessary. 299 * 300 * @return an AccessibleAWTLabel that serves as the 301 * AccessibleContext of this Label 302 * @since 1.3 303 */ 304 public AccessibleContext getAccessibleContext() { 305 if (accessibleContext == null) { 306 accessibleContext = new AccessibleAWTLabel(); 307 } 308 return accessibleContext; 309 } 310 311 /** 312 * This class implements accessibility support for the 313 * <code>Label</code> class. It provides an implementation of the 314 * Java Accessibility API appropriate to label user-interface elements. 315 * @since 1.3 316 */ 317 protected class AccessibleAWTLabel extends AccessibleAWTComponent 318 { 319 /* 320 * JDK 1.3 serialVersionUID 321 */ 322 private static final long serialVersionUID = -3568967560160480438L; 323 324 public AccessibleAWTLabel() { 325 super(); 326 } 327 328 /** 329 * Get the accessible name of this object. 330 * 331 * @return the localized name of the object -- can be null if this 332 * object does not have a name 333 * @see AccessibleContext#setAccessibleName 334 */ 335 public String getAccessibleName() { 336 if (accessibleName != null) { 337 return accessibleName; 338 } else { 339 if (getText() == null) { 340 return super.getAccessibleName(); 341 } else { 342 return getText(); 343 } 344 } 345 } 346 347 /** 348 * Get the role of this object. 349 * 350 * @return an instance of AccessibleRole describing the role of the object 351 * @see AccessibleRole 352 */ 353 public AccessibleRole getAccessibleRole() { 354 return AccessibleRole.LABEL; 355 } 356 357 } // inner class AccessibleAWTLabel 358 359 }