libjava/java/awt/TextComponent.java

   1 /* TextComponent.java -- Widgets for entering text
   2    Copyright (C) 1999, 2002 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.awt;
  40
  41 import java.awt.event.TextEvent;
  42 import java.awt.event.TextListener;
  43 import java.awt.peer.TextComponentPeer;
  44 import java.awt.peer.ComponentPeer;
  45
  46 /**
  47   * This class provides common functionality for widgets than
  48   * contain text.
  49   *
  50   * @author Aaron M. Renn (arenn@urbanophile.com)
  51   */
  52 public class TextComponent extends Component implements java.io.Serializable
  53 {
  54
  55 /*
  56  * Static Variables
  57  */
  58
  59 // Constant for serialization
  60 private static final long serialVersionUID = -2214773872412987419L;
  61
  62 /*
  63  * Instance Variables
  64  */
  65
  66 /**
  67   * @serial Indicates whether or not this component is editable.
  68   */
  69 private boolean editable;
  70
  71 /**
  72   * @serial The starting position of the selected text region.
  73   */
  74 private int selectionStart;
  75
  76 /**
  77   * @serial The ending position of the selected text region.
  78   */
  79 private int selectionEnd;
  80
  81 /**
  82   * @serial The text in the component
  83   */
  84 private String text;
  85
  86 /**
  87   * A list of listeners that will receive events from this object.
  88   */
  89 protected transient TextListener textListener;
  90
  91 /*************************************************************************/
  92
  93 /*
  94  * Constructors
  95  */
  96
  97 TextComponent(String text)
  98 {
  99   this.text = text;
 100   this.editable = true;
 101 }
 102
 103 /*************************************************************************/
 104
 105 /*
 106  * Instance Methods
 107  */
 108
 109 /**
 110   * Returns the text in this component
 111   *
 112   * @return The text in this component.
 113   */
 114 public synchronized String
 115 getText()
 116 {
 117   TextComponentPeer tcp = (TextComponentPeer)getPeer();
 118   if (tcp != null)
 119     text = tcp.getText();
 120
 121   return(text);
 122 }
 123
 124 /*************************************************************************/
 125
 126 /**
 127   * Sets the text in this component to the specified string.
 128   *
 129   * @param text The new text for this component.
 130   */
 131 public synchronized void
 132 setText(String text)
 133 {
 134   if (text == null)
 135     text = "";
 136
 137   this.text = text;
 138
 139   TextComponentPeer tcp = (TextComponentPeer)getPeer();
 140   if (tcp != null)
 141     tcp.setText(text);
 142 }
 143
 144 /*************************************************************************/
 145
 146 /**
 147   * Returns a string that contains the text that is currently selected.
 148   *
 149   * @return The currently selected text region.
 150   */
 151 public synchronized String
 152 getSelectedText()
 153 {
 154   String alltext = getText();
 155   int start = getSelectionStart();
 156   int end = getSelectionEnd();
 157
 158   return(alltext.substring(start, end));
 159 }
 160
 161 /*************************************************************************/
 162
 163 /**
 164   * Returns the starting position of the selected text region.
 165   * // FIXME: What is returned if there is no selected text?
 166   *
 167   * @return The starting position of the selected text region.
 168   */
 169 public synchronized int
 170 getSelectionStart()
 171 {
 172   TextComponentPeer tcp = (TextComponentPeer)getPeer();
 173   if (tcp != null)
 174     selectionStart = tcp.getSelectionStart();
 175
 176   return(selectionStart);
 177 }
 178
 179 /*************************************************************************/
 180
 181 /**
 182   * Sets the starting position of the selected region to the
 183   * specified value.  If the specified value is out of range, then it
 184   * will be silently changed to the nearest legal value.
 185   *
 186   * @param selectionStart The new start position for selected text.
 187   */
 188 public synchronized void
 189 setSelectionStart(int selectionStart)
 190 {
 191   select(selectionStart, getSelectionEnd());
 192 }
 193
 194 /*************************************************************************/
 195
 196 /**
 197   * Returns the ending position of the selected text region.
 198   * // FIXME: What is returned if there is no selected text.
 199   *
 200   * @return The ending position of the selected text region.
 201   */
 202 public synchronized int
 203 getSelectionEnd()
 204 {
 205   TextComponentPeer tcp = (TextComponentPeer)getPeer();
 206   if (tcp != null)
 207     selectionEnd = tcp.getSelectionEnd();
 208
 209   return(selectionEnd);
 210 }
 211
 212 /*************************************************************************/
 213
 214 /**
 215   * Sets the ending position of the selected region to the
 216   * specified value.  If the specified value is out of range, then it
 217   * will be silently changed to the nearest legal value.
 218   *
 219   * @param selectionEnd The new start position for selected text.
 220   */
 221 public synchronized void
 222 setSelectionEnd(int selectionEnd)
 223 {
 224   select(getSelectionStart(), selectionEnd);
 225 }
 226
 227 /*************************************************************************/
 228
 229 /**
 230   * This method sets the selected text range to the text between the
 231   * specified start and end positions.  Illegal values for these
 232   * positions are silently fixed.
 233   *
 234   * @param startSelection The new start position for the selected text.
 235   * @param endSelection The new end position for the selected text.
 236   */
 237 public synchronized void
 238 select(int selectionStart, int endSelection)
 239 {
 240   if (selectionStart < 0)
 241     selectionStart = 0;
 242
 243   if (selectionStart > getText().length())
 244     selectionStart = text.length();
 245
 246   if (selectionEnd > text.length())
 247     selectionEnd = text.length();
 248
 249   if (selectionStart > getSelectionEnd())
 250     selectionStart = selectionEnd;
 251
 252   this.selectionStart = selectionStart;
 253   this.selectionEnd = selectionEnd;
 254
 255   TextComponentPeer tcp = (TextComponentPeer)getPeer();
 256   if (tcp != null)
 257     tcp.select(selectionStart, selectionEnd);
 258 }
 259
 260 /*************************************************************************/
 261
 262 /**
 263   * Selects all of the text in the component.
 264   */
 265 public synchronized void
 266 selectAll()
 267 {
 268   select(0, getText().length());
 269 }
 270
 271 /*************************************************************************/
 272
 273 /**
 274   * Returns the current caret position in the text.
 275   *
 276   * @return The caret position in the text.
 277   */
 278 public synchronized int
 279 getCaretPosition()
 280 {
 281   TextComponentPeer tcp = (TextComponentPeer)getPeer();
 282   if (tcp != null)
 283     return(tcp.getCaretPosition());
 284   else
 285     return(0);
 286 }
 287
 288 /*************************************************************************/
 289
 290 /**
 291   * Sets the caret position to the specified value.
 292   *
 293   * @param caretPosition The new caret position.
 294   *
 295   * @exception IllegalArgumentException If the value supplied for position
 296   * is less than zero.
 297   *
 298   * @since 1.1
 299   */
 300 public synchronized void
 301 setCaretPosition(int caretPosition)
 302 {
 303   if (caretPosition < 0)
 304     throw new IllegalArgumentException ();
 305
 306   TextComponentPeer tcp = (TextComponentPeer)getPeer();
 307   if (tcp != null)
 308     tcp.setCaretPosition(caretPosition);
 309 }
 310
 311 /*************************************************************************/
 312
 313 /**
 314   * Tests whether or not this component's text can be edited.
 315   *
 316   * @return <code>true</code> if the text can be edited, <code>false</code>
 317   * otherwise.
 318   */
 319 public boolean
 320 isEditable()
 321 {
 322   return(editable);
 323 }
 324
 325 /*************************************************************************/
 326
 327 /**
 328   * Sets whether or not this component's text can be edited.
 329   *
 330   * @param editable <code>true</code> to enable editing of the text,
 331   * <code>false</code> to disable it.
 332   */
 333 public synchronized void
 334 setEditable(boolean editable)
 335 {
 336   this.editable = editable;
 337
 338   TextComponentPeer tcp = (TextComponentPeer)getPeer();
 339   if (tcp != null)
 340     tcp.setEditable(editable);
 341 }
 342
 343 /*************************************************************************/
 344
 345 /**
 346   * Notifies the component that it should destroy its native peer.
 347   */
 348 public void
 349 removeNotify()
 350 {
 351   super.removeNotify();
 352 }
 353
 354 /*************************************************************************/
 355
 356 /**
 357   * Adds a new listener to the list of text listeners for this
 358   * component.
 359   *
 360   * @param listener The listener to be added.
 361   */
 362 public synchronized void
 363 addTextListener(TextListener listener)
 364 {
 365   textListener = AWTEventMulticaster.add(textListener, listener);
 366
 367   enableEvents(AWTEvent.TEXT_EVENT_MASK);
 368 }
 369
 370 /*************************************************************************/
 371
 372 /**
 373   * Removes the specified listener from the list of listeners
 374   * for this component.
 375   *
 376   * @param listener The listener to remove.
 377   */
 378 public synchronized void
 379 removeTextListener(TextListener listener)
 380 {
 381   textListener = AWTEventMulticaster.remove(textListener, listener);
 382 }
 383
 384 /*************************************************************************/
 385
 386 /**
 387   * Processes the specified event for this component.  Text events are
 388   * processed by calling the <code>processTextEvent()</code> method.
 389   * All other events are passed to the superclass method.
 390   *
 391   * @param event The event to process.
 392   */
 393 protected void
 394 processEvent(AWTEvent event)
 395 {
 396   if (event instanceof TextEvent)
 397     processTextEvent((TextEvent)event);
 398   else
 399     super.processEvent(event);
 400 }
 401
 402 /*************************************************************************/
 403
 404 /**
 405   * Processes the specified text event by dispatching it to any listeners
 406   * that are registered.  Note that this method will only be called
 407   * if text event's are enabled.  This will be true if there are any
 408   * registered listeners, or if the event has been specifically
 409   * enabled using <code>enableEvents()</code>.
 410   *
 411   * @param event The text event to process.
 412   */
 413 protected void
 414 processTextEvent(TextEvent event)
 415 {
 416   if (textListener != null)
 417     textListener.textValueChanged(event);
 418 }
 419
 420 void
 421 dispatchEventImpl(AWTEvent e)
 422 {
 423   if (e.id <= TextEvent.TEXT_LAST
 424       && e.id >= TextEvent.TEXT_FIRST
 425       && (textListener != null
 426           || (eventMask & AWTEvent.TEXT_EVENT_MASK) != 0))
 427     processEvent(e);
 428   else
 429     super.dispatchEventImpl(e);
 430 }
 431
 432 /*************************************************************************/
 433
 434 /**
 435   * Returns a debugging string.
 436   *
 437   * @return A debugging string.
 438   */
 439 protected String
 440 paramString()
 441 {
 442   return(getClass().getName() + "(text=" + getText() + ")");
 443 }
 444
 445 } // class TextComponent
 446