38 import sun.awt.InputMethodSupport;
39
40 /**
41 * The <code>TextComponent</code> class is the superclass of
42 * any component that allows the editing of some text.
43 * <p>
44 * A text component embodies a string of text. The
45 * <code>TextComponent</code> class defines a set of methods
46 * that determine whether or not this text is editable. If the
47 * component is editable, it defines another set of methods
48 * that supports a text insertion caret.
49 * <p>
50 * In addition, the class defines methods that are used
51 * to maintain a current <em>selection</em> from the text.
52 * The text selection, a substring of the component's text,
53 * is the target of editing operations. It is also referred
54 * to as the <em>selected text</em>.
55 *
56 * @author Sami Shaio
57 * @author Arthur van Hoff
58 * @since JDK1.0
59 */
60 public class TextComponent extends Component implements Accessible {
61
62 /**
63 * The value of the text.
64 * A <code>null</code> value is the same as "".
65 *
66 * @serial
67 * @see #setText(String)
68 * @see #getText()
69 */
70 String text;
71
72 /**
73 * A boolean indicating whether or not this
74 * <code>TextComponent</code> is editable.
75 * It will be <code>true</code> if the text component
76 * is editable and <code>false</code> if not.
77 *
78 * @serial
251 text = peer.getText();
252 }
253 return text;
254 }
255
256 /**
257 * Returns the selected text from the text that is
258 * presented by this text component.
259 * @return the selected text of this text component
260 * @see java.awt.TextComponent#select
261 */
262 public synchronized String getSelectedText() {
263 return getText().substring(getSelectionStart(), getSelectionEnd());
264 }
265
266 /**
267 * Indicates whether or not this text component is editable.
268 * @return <code>true</code> if this text component is
269 * editable; <code>false</code> otherwise.
270 * @see java.awt.TextComponent#setEditable
271 * @since JDK1.0
272 */
273 public boolean isEditable() {
274 return editable;
275 }
276
277 /**
278 * Sets the flag that determines whether or not this
279 * text component is editable.
280 * <p>
281 * If the flag is set to <code>true</code>, this text component
282 * becomes user editable. If the flag is set to <code>false</code>,
283 * the user cannot change the text of this text component.
284 * By default, non-editable text components have a background color
285 * of SystemColor.control. This default can be overridden by
286 * calling setBackground.
287 *
288 * @param b a flag indicating whether this text component
289 * is user editable.
290 * @see java.awt.TextComponent#isEditable
291 * @since JDK1.0
292 */
293 public synchronized void setEditable(boolean b) {
294 if (editable == b) {
295 return;
296 }
297
298 editable = b;
299 TextComponentPeer peer = (TextComponentPeer)this.peer;
300 if (peer != null) {
301 peer.setEditable(b);
302 }
303 }
304
305 /**
306 * Gets the background color of this text component.
307 *
308 * By default, non-editable text components have a background color
309 * of SystemColor.control. This default can be overridden by
310 * calling setBackground.
311 *
312 * @return This text component's background color.
313 * If this text component does not have a background color,
314 * the background color of its parent is returned.
315 * @see #setBackground(Color)
316 * @since JDK1.0
317 */
318 public Color getBackground() {
319 if (!editable && !backgroundSetByClientCode) {
320 return SystemColor.control;
321 }
322
323 return super.getBackground();
324 }
325
326 /**
327 * Sets the background color of this text component.
328 *
329 * @param c The color to become this text component's color.
330 * If this parameter is null then this text component
331 * will inherit the background color of its parent.
332 * @see #getBackground()
333 * @since JDK1.0
334 */
335 public void setBackground(Color c) {
336 backgroundSetByClientCode = true;
337 super.setBackground(c);
338 }
339
340 /**
341 * Gets the start position of the selected text in
342 * this text component.
343 * @return the start position of the selected text
344 * @see java.awt.TextComponent#setSelectionStart
345 * @see java.awt.TextComponent#getSelectionEnd
346 */
347 public synchronized int getSelectionStart() {
348 TextComponentPeer peer = (TextComponentPeer)this.peer;
349 if (peer != null) {
350 selectionStart = peer.getSelectionStart();
351 }
352 return selectionStart;
353 }
354
355 /**
356 * Sets the selection start for this text component to
357 * the specified position. The new start point is constrained
358 * to be at or before the current selection end. It also
359 * cannot be set to less than zero, the beginning of the
360 * component's text.
361 * If the caller supplies a value for <code>selectionStart</code>
362 * that is out of bounds, the method enforces these constraints
363 * silently, and without failure.
364 * @param selectionStart the start position of the
365 * selected text
366 * @see java.awt.TextComponent#getSelectionStart
367 * @see java.awt.TextComponent#setSelectionEnd
368 * @since JDK1.1
369 */
370 public synchronized void setSelectionStart(int selectionStart) {
371 /* Route through select method to enforce consistent policy
372 * between selectionStart and selectionEnd.
373 */
374 select(selectionStart, getSelectionEnd());
375 }
376
377 /**
378 * Gets the end position of the selected text in
379 * this text component.
380 * @return the end position of the selected text
381 * @see java.awt.TextComponent#setSelectionEnd
382 * @see java.awt.TextComponent#getSelectionStart
383 */
384 public synchronized int getSelectionEnd() {
385 TextComponentPeer peer = (TextComponentPeer)this.peer;
386 if (peer != null) {
387 selectionEnd = peer.getSelectionEnd();
388 }
389 return selectionEnd;
390 }
391
392 /**
393 * Sets the selection end for this text component to
394 * the specified position. The new end point is constrained
395 * to be at or after the current selection start. It also
396 * cannot be set beyond the end of the component's text.
397 * If the caller supplies a value for <code>selectionEnd</code>
398 * that is out of bounds, the method enforces these constraints
399 * silently, and without failure.
400 * @param selectionEnd the end position of the
401 * selected text
402 * @see java.awt.TextComponent#getSelectionEnd
403 * @see java.awt.TextComponent#setSelectionStart
404 * @since JDK1.1
405 */
406 public synchronized void setSelectionEnd(int selectionEnd) {
407 /* Route through select method to enforce consistent policy
408 * between selectionStart and selectionEnd.
409 */
410 select(getSelectionStart(), selectionEnd);
411 }
412
413 /**
414 * Selects the text between the specified start and end positions.
415 * <p>
416 * This method sets the start and end positions of the
417 * selected text, enforcing the restriction that the start position
418 * must be greater than or equal to zero. The end position must be
419 * greater than or equal to the start position, and less than or
420 * equal to the length of the text component's text. The
421 * character positions are indexed starting with zero.
422 * The length of the selection is
423 * <code>endPosition</code> - <code>startPosition</code>, so the
424 * character at <code>endPosition</code> is not selected.
477 TextComponentPeer peer = (TextComponentPeer)this.peer;
478 if (peer != null) {
479 peer.select(selectionStart, selectionEnd);
480 }
481 }
482
483 /**
484 * Sets the position of the text insertion caret.
485 * The caret position is constrained to be between 0
486 * and the last character of the text, inclusive.
487 * If the passed-in value is greater than this range,
488 * the value is set to the last character (or 0 if
489 * the <code>TextComponent</code> contains no text)
490 * and no error is returned. If the passed-in value is
491 * less than 0, an <code>IllegalArgumentException</code>
492 * is thrown.
493 *
494 * @param position the position of the text insertion caret
495 * @exception IllegalArgumentException if <code>position</code>
496 * is less than zero
497 * @since JDK1.1
498 */
499 public synchronized void setCaretPosition(int position) {
500 if (position < 0) {
501 throw new IllegalArgumentException("position less than zero.");
502 }
503
504 int maxposition = getText().length();
505 if (position > maxposition) {
506 position = maxposition;
507 }
508
509 TextComponentPeer peer = (TextComponentPeer)this.peer;
510 if (peer != null) {
511 peer.setCaretPosition(position);
512 } else {
513 select(position, position);
514 }
515 }
516
517 /**
518 * Returns the position of the text insertion caret.
519 * The caret position is constrained to be between 0
520 * and the last character of the text, inclusive.
521 * If the text or caret have not been set, the default
522 * caret position is 0.
523 *
524 * @return the position of the text insertion caret
525 * @see #setCaretPosition(int)
526 * @since JDK1.1
527 */
528 public synchronized int getCaretPosition() {
529 TextComponentPeer peer = (TextComponentPeer)this.peer;
530 int position = 0;
531
532 if (peer != null) {
533 position = peer.getCaretPosition();
534 } else {
535 position = selectionStart;
536 }
537 int maxposition = getText().length();
538 if (position > maxposition) {
539 position = maxposition;
540 }
541 return position;
542 }
543
544 /**
545 * Adds the specified text event listener to receive text events
546 * from this text component.
557 public synchronized void addTextListener(TextListener l) {
558 if (l == null) {
559 return;
560 }
561 textListener = AWTEventMulticaster.add(textListener, l);
562 newEventsOnly = true;
563 }
564
565 /**
566 * Removes the specified text event listener so that it no longer
567 * receives text events from this text component
568 * If <code>l</code> is <code>null</code>, no exception is
569 * thrown and no action is performed.
570 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
571 * >AWT Threading Issues</a> for details on AWT's threading model.
572 *
573 * @param l the text listener
574 * @see #addTextListener
575 * @see #getTextListeners
576 * @see java.awt.event.TextListener
577 * @since JDK1.1
578 */
579 public synchronized void removeTextListener(TextListener l) {
580 if (l == null) {
581 return;
582 }
583 textListener = AWTEventMulticaster.remove(textListener, l);
584 }
585
586 /**
587 * Returns an array of all the text listeners
588 * registered on this text component.
589 *
590 * @return all of this text component's <code>TextListener</code>s
591 * or an empty array if no text
592 * listeners are currently registered
593 *
594 *
595 * @see #addTextListener
596 * @see #removeTextListener
597 * @since 1.4
|
38 import sun.awt.InputMethodSupport;
39
40 /**
41 * The <code>TextComponent</code> class is the superclass of
42 * any component that allows the editing of some text.
43 * <p>
44 * A text component embodies a string of text. The
45 * <code>TextComponent</code> class defines a set of methods
46 * that determine whether or not this text is editable. If the
47 * component is editable, it defines another set of methods
48 * that supports a text insertion caret.
49 * <p>
50 * In addition, the class defines methods that are used
51 * to maintain a current <em>selection</em> from the text.
52 * The text selection, a substring of the component's text,
53 * is the target of editing operations. It is also referred
54 * to as the <em>selected text</em>.
55 *
56 * @author Sami Shaio
57 * @author Arthur van Hoff
58 * @since 1.0
59 */
60 public class TextComponent extends Component implements Accessible {
61
62 /**
63 * The value of the text.
64 * A <code>null</code> value is the same as "".
65 *
66 * @serial
67 * @see #setText(String)
68 * @see #getText()
69 */
70 String text;
71
72 /**
73 * A boolean indicating whether or not this
74 * <code>TextComponent</code> is editable.
75 * It will be <code>true</code> if the text component
76 * is editable and <code>false</code> if not.
77 *
78 * @serial
251 text = peer.getText();
252 }
253 return text;
254 }
255
256 /**
257 * Returns the selected text from the text that is
258 * presented by this text component.
259 * @return the selected text of this text component
260 * @see java.awt.TextComponent#select
261 */
262 public synchronized String getSelectedText() {
263 return getText().substring(getSelectionStart(), getSelectionEnd());
264 }
265
266 /**
267 * Indicates whether or not this text component is editable.
268 * @return <code>true</code> if this text component is
269 * editable; <code>false</code> otherwise.
270 * @see java.awt.TextComponent#setEditable
271 * @since 1.0
272 */
273 public boolean isEditable() {
274 return editable;
275 }
276
277 /**
278 * Sets the flag that determines whether or not this
279 * text component is editable.
280 * <p>
281 * If the flag is set to <code>true</code>, this text component
282 * becomes user editable. If the flag is set to <code>false</code>,
283 * the user cannot change the text of this text component.
284 * By default, non-editable text components have a background color
285 * of SystemColor.control. This default can be overridden by
286 * calling setBackground.
287 *
288 * @param b a flag indicating whether this text component
289 * is user editable.
290 * @see java.awt.TextComponent#isEditable
291 * @since 1.0
292 */
293 public synchronized void setEditable(boolean b) {
294 if (editable == b) {
295 return;
296 }
297
298 editable = b;
299 TextComponentPeer peer = (TextComponentPeer)this.peer;
300 if (peer != null) {
301 peer.setEditable(b);
302 }
303 }
304
305 /**
306 * Gets the background color of this text component.
307 *
308 * By default, non-editable text components have a background color
309 * of SystemColor.control. This default can be overridden by
310 * calling setBackground.
311 *
312 * @return This text component's background color.
313 * If this text component does not have a background color,
314 * the background color of its parent is returned.
315 * @see #setBackground(Color)
316 * @since 1.0
317 */
318 public Color getBackground() {
319 if (!editable && !backgroundSetByClientCode) {
320 return SystemColor.control;
321 }
322
323 return super.getBackground();
324 }
325
326 /**
327 * Sets the background color of this text component.
328 *
329 * @param c The color to become this text component's color.
330 * If this parameter is null then this text component
331 * will inherit the background color of its parent.
332 * @see #getBackground()
333 * @since 1.0
334 */
335 public void setBackground(Color c) {
336 backgroundSetByClientCode = true;
337 super.setBackground(c);
338 }
339
340 /**
341 * Gets the start position of the selected text in
342 * this text component.
343 * @return the start position of the selected text
344 * @see java.awt.TextComponent#setSelectionStart
345 * @see java.awt.TextComponent#getSelectionEnd
346 */
347 public synchronized int getSelectionStart() {
348 TextComponentPeer peer = (TextComponentPeer)this.peer;
349 if (peer != null) {
350 selectionStart = peer.getSelectionStart();
351 }
352 return selectionStart;
353 }
354
355 /**
356 * Sets the selection start for this text component to
357 * the specified position. The new start point is constrained
358 * to be at or before the current selection end. It also
359 * cannot be set to less than zero, the beginning of the
360 * component's text.
361 * If the caller supplies a value for <code>selectionStart</code>
362 * that is out of bounds, the method enforces these constraints
363 * silently, and without failure.
364 * @param selectionStart the start position of the
365 * selected text
366 * @see java.awt.TextComponent#getSelectionStart
367 * @see java.awt.TextComponent#setSelectionEnd
368 * @since 1.1
369 */
370 public synchronized void setSelectionStart(int selectionStart) {
371 /* Route through select method to enforce consistent policy
372 * between selectionStart and selectionEnd.
373 */
374 select(selectionStart, getSelectionEnd());
375 }
376
377 /**
378 * Gets the end position of the selected text in
379 * this text component.
380 * @return the end position of the selected text
381 * @see java.awt.TextComponent#setSelectionEnd
382 * @see java.awt.TextComponent#getSelectionStart
383 */
384 public synchronized int getSelectionEnd() {
385 TextComponentPeer peer = (TextComponentPeer)this.peer;
386 if (peer != null) {
387 selectionEnd = peer.getSelectionEnd();
388 }
389 return selectionEnd;
390 }
391
392 /**
393 * Sets the selection end for this text component to
394 * the specified position. The new end point is constrained
395 * to be at or after the current selection start. It also
396 * cannot be set beyond the end of the component's text.
397 * If the caller supplies a value for <code>selectionEnd</code>
398 * that is out of bounds, the method enforces these constraints
399 * silently, and without failure.
400 * @param selectionEnd the end position of the
401 * selected text
402 * @see java.awt.TextComponent#getSelectionEnd
403 * @see java.awt.TextComponent#setSelectionStart
404 * @since 1.1
405 */
406 public synchronized void setSelectionEnd(int selectionEnd) {
407 /* Route through select method to enforce consistent policy
408 * between selectionStart and selectionEnd.
409 */
410 select(getSelectionStart(), selectionEnd);
411 }
412
413 /**
414 * Selects the text between the specified start and end positions.
415 * <p>
416 * This method sets the start and end positions of the
417 * selected text, enforcing the restriction that the start position
418 * must be greater than or equal to zero. The end position must be
419 * greater than or equal to the start position, and less than or
420 * equal to the length of the text component's text. The
421 * character positions are indexed starting with zero.
422 * The length of the selection is
423 * <code>endPosition</code> - <code>startPosition</code>, so the
424 * character at <code>endPosition</code> is not selected.
477 TextComponentPeer peer = (TextComponentPeer)this.peer;
478 if (peer != null) {
479 peer.select(selectionStart, selectionEnd);
480 }
481 }
482
483 /**
484 * Sets the position of the text insertion caret.
485 * The caret position is constrained to be between 0
486 * and the last character of the text, inclusive.
487 * If the passed-in value is greater than this range,
488 * the value is set to the last character (or 0 if
489 * the <code>TextComponent</code> contains no text)
490 * and no error is returned. If the passed-in value is
491 * less than 0, an <code>IllegalArgumentException</code>
492 * is thrown.
493 *
494 * @param position the position of the text insertion caret
495 * @exception IllegalArgumentException if <code>position</code>
496 * is less than zero
497 * @since 1.1
498 */
499 public synchronized void setCaretPosition(int position) {
500 if (position < 0) {
501 throw new IllegalArgumentException("position less than zero.");
502 }
503
504 int maxposition = getText().length();
505 if (position > maxposition) {
506 position = maxposition;
507 }
508
509 TextComponentPeer peer = (TextComponentPeer)this.peer;
510 if (peer != null) {
511 peer.setCaretPosition(position);
512 } else {
513 select(position, position);
514 }
515 }
516
517 /**
518 * Returns the position of the text insertion caret.
519 * The caret position is constrained to be between 0
520 * and the last character of the text, inclusive.
521 * If the text or caret have not been set, the default
522 * caret position is 0.
523 *
524 * @return the position of the text insertion caret
525 * @see #setCaretPosition(int)
526 * @since 1.1
527 */
528 public synchronized int getCaretPosition() {
529 TextComponentPeer peer = (TextComponentPeer)this.peer;
530 int position = 0;
531
532 if (peer != null) {
533 position = peer.getCaretPosition();
534 } else {
535 position = selectionStart;
536 }
537 int maxposition = getText().length();
538 if (position > maxposition) {
539 position = maxposition;
540 }
541 return position;
542 }
543
544 /**
545 * Adds the specified text event listener to receive text events
546 * from this text component.
557 public synchronized void addTextListener(TextListener l) {
558 if (l == null) {
559 return;
560 }
561 textListener = AWTEventMulticaster.add(textListener, l);
562 newEventsOnly = true;
563 }
564
565 /**
566 * Removes the specified text event listener so that it no longer
567 * receives text events from this text component
568 * If <code>l</code> is <code>null</code>, no exception is
569 * thrown and no action is performed.
570 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
571 * >AWT Threading Issues</a> for details on AWT's threading model.
572 *
573 * @param l the text listener
574 * @see #addTextListener
575 * @see #getTextListeners
576 * @see java.awt.event.TextListener
577 * @since 1.1
578 */
579 public synchronized void removeTextListener(TextListener l) {
580 if (l == null) {
581 return;
582 }
583 textListener = AWTEventMulticaster.remove(textListener, l);
584 }
585
586 /**
587 * Returns an array of all the text listeners
588 * registered on this text component.
589 *
590 * @return all of this text component's <code>TextListener</code>s
591 * or an empty array if no text
592 * listeners are currently registered
593 *
594 *
595 * @see #addTextListener
596 * @see #removeTextListener
597 * @since 1.4
|