001 /*
002 * Copyright 1995-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package java.awt;
026
027 import java.awt.peer.LabelPeer;
028 import java.io.IOException;
029 import java.io.ObjectInputStream;
030 import javax.accessibility.*;
031
032 /**
033 * A <code>Label</code> object is a component for placing text in a
034 * container. A label displays a single line of read-only text.
035 * The text can be changed by the application, but a user cannot edit it
036 * directly.
037 * <p>
038 * For example, the code . . .
039 * <p>
040 * <hr><blockquote><pre>
041 * setLayout(new FlowLayout(FlowLayout.CENTER, 10, 10));
042 * add(new Label("Hi There!"));
043 * add(new Label("Another Label"));
044 * </pre></blockquote><hr>
045 * <p>
046 * produces the following labels:
047 * <p>
048 * <img src="doc-files/Label-1.gif" alt="Two labels: 'Hi There!' and 'Another label'"
049 * ALIGN=center HSPACE=10 VSPACE=7>
050 *
051 * @version 1.66, 05/05/07
052 * @author Sami Shaio
053 * @since JDK1.0
054 */
055 public class Label extends Component implements Accessible {
056
057 static {
058 /* ensure that the necessary native libraries are loaded */
059 Toolkit.loadLibraries();
060 if (!GraphicsEnvironment.isHeadless()) {
061 initIDs();
062 }
063 }
064
065 /**
066 * Indicates that the label should be left justified.
067 */
068 public static final int LEFT = 0;
069
070 /**
071 * Indicates that the label should be centered.
072 */
073 public static final int CENTER = 1;
074
075 /**
076 * Indicates that the label should be right justified.
077 * @since JDK1.0t.
078 */
079 public static final int RIGHT = 2;
080
081 /**
082 * The text of this label.
083 * This text can be modified by the program
084 * but never by the user.
085 *
086 * @serial
087 * @see #getText()
088 * @see #setText(String)
089 */
090 String text;
091
092 /**
093 * The label's alignment. The default alignment is set
094 * to be left justified.
095 *
096 * @serial
097 * @see #getAlignment()
098 * @see #setAlignment(int)
099 */
100 int alignment = LEFT;
101
102 private static final String base = "label";
103 private static int nameCounter = 0;
104
105 /*
106 * JDK 1.1 serialVersionUID
107 */
108 private static final long serialVersionUID = 3094126758329070636L;
109
110 /**
111 * Constructs an empty label.
112 * The text of the label is the empty string <code>""</code>.
113 * @exception HeadlessException if GraphicsEnvironment.isHeadless()
114 * returns true.
115 * @see java.awt.GraphicsEnvironment#isHeadless
116 */
117 public Label() throws HeadlessException {
118 this ("", LEFT);
119 }
120
121 /**
122 * Constructs a new label with the specified string of text,
123 * left justified.
124 * @param text the string that the label presents.
125 * A <code>null</code> value
126 * will be accepted without causing a NullPointerException
127 * to be thrown.
128 * @exception HeadlessException if GraphicsEnvironment.isHeadless()
129 * returns true.
130 * @see java.awt.GraphicsEnvironment#isHeadless
131 */
132 public Label(String text) throws HeadlessException {
133 this (text, LEFT);
134 }
135
136 /**
137 * Constructs a new label that presents the specified string of
138 * text with the specified alignment.
139 * Possible values for <code>alignment</code> are <code>Label.LEFT</code>,
140 * <code>Label.RIGHT</code>, and <code>Label.CENTER</code>.
141 * @param text the string that the label presents.
142 * A <code>null</code> value
143 * will be accepted without causing a NullPointerException
144 * to be thrown.
145 * @param alignment the alignment value.
146 * @exception HeadlessException if GraphicsEnvironment.isHeadless()
147 * returns true.
148 * @see java.awt.GraphicsEnvironment#isHeadless
149 */
150 public Label(String text, int alignment) throws HeadlessException {
151 GraphicsEnvironment.checkHeadless();
152 this .text = text;
153 setAlignment(alignment);
154 }
155
156 /**
157 * Read a label from an object input stream.
158 * @exception HeadlessException if
159 * <code>GraphicsEnvironment.isHeadless()</code> returns
160 * <code>true</code>
161 * @serial
162 * @since 1.4
163 * @see java.awt.GraphicsEnvironment#isHeadless
164 */
165 private void readObject(ObjectInputStream s)
166 throws ClassNotFoundException, IOException,
167 HeadlessException {
168 GraphicsEnvironment.checkHeadless();
169 s.defaultReadObject();
170 }
171
172 /**
173 * Construct a name for this component. Called by getName() when the
174 * name is <code>null</code>.
175 */
176 String constructComponentName() {
177 synchronized (Label.class) {
178 return base + nameCounter++;
179 }
180 }
181
182 /**
183 * Creates the peer for this label. The peer allows us to
184 * modify the appearance of the label without changing its
185 * functionality.
186 */
187 public void addNotify() {
188 synchronized (getTreeLock()) {
189 if (peer == null)
190 peer = getToolkit().createLabel(this );
191 super .addNotify();
192 }
193 }
194
195 /**
196 * Gets the current alignment of this label. Possible values are
197 * <code>Label.LEFT</code>, <code>Label.RIGHT</code>, and
198 * <code>Label.CENTER</code>.
199 * @see java.awt.Label#setAlignment
200 */
201 public int getAlignment() {
202 return alignment;
203 }
204
205 /**
206 * Sets the alignment for this label to the specified alignment.
207 * Possible values are <code>Label.LEFT</code>,
208 * <code>Label.RIGHT</code>, and <code>Label.CENTER</code>.
209 * @param alignment the alignment to be set.
210 * @exception IllegalArgumentException if an improper value for
211 * <code>alignment</code> is given.
212 * @see java.awt.Label#getAlignment
213 */
214 public synchronized void setAlignment(int alignment) {
215 switch (alignment) {
216 case LEFT:
217 case CENTER:
218 case RIGHT:
219 this .alignment = alignment;
220 LabelPeer peer = (LabelPeer) this .peer;
221 if (peer != null) {
222 peer.setAlignment(alignment);
223 }
224 return;
225 }
226 throw new IllegalArgumentException("improper alignment: "
227 + alignment);
228 }
229
230 /**
231 * Gets the text of this label.
232 * @return the text of this label, or <code>null</code> if
233 * the text has been set to <code>null</code>.
234 * @see java.awt.Label#setText
235 */
236 public String getText() {
237 return text;
238 }
239
240 /**
241 * Sets the text for this label to the specified text.
242 * @param text the text that this label displays. If
243 * <code>text</code> is <code>null</code>, it is
244 * treated for display purposes like an empty
245 * string <code>""</code>.
246 * @see java.awt.Label#getText
247 */
248 public void setText(String text) {
249 boolean testvalid = false;
250 synchronized (this ) {
251 if (text != this .text
252 && (this .text == null || !this .text.equals(text))) {
253 this .text = text;
254 LabelPeer peer = (LabelPeer) this .peer;
255 if (peer != null) {
256 peer.setText(text);
257 }
258 testvalid = true;
259 }
260 }
261
262 // This could change the preferred size of the Component.
263 if (testvalid && valid) {
264 invalidate();
265 }
266 }
267
268 /**
269 * Returns a string representing the state of this <code>Label</code>.
270 * This method is intended to be used only for debugging purposes, and the
271 * content and format of the returned string may vary between
272 * implementations. The returned string may be empty but may not be
273 * <code>null</code>.
274 *
275 * @return the parameter string of this label
276 */
277 protected String paramString() {
278 String str = ",align=";
279 switch (alignment) {
280 case LEFT:
281 str += "left";
282 break;
283 case CENTER:
284 str += "center";
285 break;
286 case RIGHT:
287 str += "right";
288 break;
289 }
290 return super .paramString() + str + ",text=" + text;
291 }
292
293 /**
294 * Initialize JNI field and method IDs
295 */
296 private static native void initIDs();
297
298 /////////////////
299 // Accessibility support
300 ////////////////
301
302 /**
303 * Gets the AccessibleContext associated with this Label.
304 * For labels, the AccessibleContext takes the form of an
305 * AccessibleAWTLabel.
306 * A new AccessibleAWTLabel instance is created if necessary.
307 *
308 * @return an AccessibleAWTLabel that serves as the
309 * AccessibleContext of this Label
310 * @since 1.3
311 */
312 public AccessibleContext getAccessibleContext() {
313 if (accessibleContext == null) {
314 accessibleContext = new AccessibleAWTLabel();
315 }
316 return accessibleContext;
317 }
318
319 /**
320 * This class implements accessibility support for the
321 * <code>Label</code> class. It provides an implementation of the
322 * Java Accessibility API appropriate to label user-interface elements.
323 * @since 1.3
324 */
325 protected class AccessibleAWTLabel extends AccessibleAWTComponent {
326 /*
327 * JDK 1.3 serialVersionUID
328 */
329 private static final long serialVersionUID = -3568967560160480438L;
330
331 public AccessibleAWTLabel() {
332 super ();
333 }
334
335 /**
336 * Get the accessible name of this object.
337 *
338 * @return the localized name of the object -- can be null if this
339 * object does not have a name
340 * @see AccessibleContext#setAccessibleName
341 */
342 public String getAccessibleName() {
343 if (accessibleName != null) {
344 return accessibleName;
345 } else {
346 if (getText() == null) {
347 return super .getAccessibleName();
348 } else {
349 return getText();
350 }
351 }
352 }
353
354 /**
355 * Get the role of this object.
356 *
357 * @return an instance of AccessibleRole describing the role of the object
358 * @see AccessibleRole
359 */
360 public AccessibleRole getAccessibleRole() {
361 return AccessibleRole.LABEL;
362 }
363
364 } // inner class AccessibleAWTLabel
365
366 }
|