Source for javax.swing.JLabel

   1: /* JLabel.java --
   2:    Copyright (C) 2002, 2004, 2005  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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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 javax.swing;
  40: 
  41: import java.awt.Component;
  42: import java.awt.Font;
  43: import java.awt.Image;
  44: import java.awt.event.KeyEvent;
  45: 
  46: import javax.accessibility.Accessible;
  47: import javax.accessibility.AccessibleContext;
  48: import javax.swing.plaf.LabelUI;
  49: 
  50: /**
  51:  * A swing widget that displays a text message and/or an icon.
  52:  */
  53: public class JLabel extends JComponent implements Accessible, SwingConstants
  54: {
  55:   /** DOCUMENT ME! */
  56:   private static final long serialVersionUID = 5496508283662221534L;
  57: 
  58:   /**
  59:    * The Component the label will give focus to when its mnemonic is
  60:    * activated.
  61:    */
  62:   protected Component labelFor;
  63: 
  64:   /** The label's text. */
  65:   private transient String text;
  66: 
  67:   /** Where the label will be positioned horizontally. */
  68:   private transient int horizontalAlignment = LEADING;
  69: 
  70:   /** Where the label text will be placed horizontally relative to the icon. */
  71:   private transient int horizontalTextPosition = TRAILING;
  72: 
  73:   /** Where the label will be positioned vertically. */
  74:   private transient int verticalAlignment = CENTER;
  75: 
  76:   /** Where the label text will be place vertically relative to the icon. */
  77:   private transient int verticalTextPosition = CENTER;
  78: 
  79:   /** The icon painted when the label is enabled. */
  80:   private transient Icon icon;
  81: 
  82:   /** The icon painted when the label is disabled. */
  83:   private transient Icon disabledIcon;
  84: 
  85:   /** The label's mnemnonic key. */
  86:   private transient int displayedMnemonic = KeyEvent.VK_UNDEFINED;
  87: 
  88:   /** The index of the menemonic character in the text. */
  89:   private transient int displayedMnemonicIndex = -1;
  90: 
  91:   /** The gap between the icon and the text. */
  92:   private transient int iconTextGap = 4;
  93: 
  94:   /**
  95:    * Creates a new vertically centered, horizontally on the leading edge
  96:    * JLabel object with text and no icon.
  97:    */
  98:   public JLabel()
  99:   {
 100:     this(null, null, LEADING);
 101:   }
 102: 
 103:   /**
 104:    * Creates a new vertically and horizontally centered
 105:    * JLabel object with no text and the given icon.
 106:    *
 107:    * @param image The icon to use with the label.
 108:    */
 109:   public JLabel(Icon image)
 110:   {
 111:     this(null, image, CENTER);
 112:   }
 113: 
 114:   /**
 115:    * Creates a new vertically centered JLabel object with no text and the
 116:    * given icon and horizontal alignment. By default, the text is TRAILING
 117:    * the image.
 118:    *
 119:    * @param image The icon to use with the label.
 120:    * @param horizontalAlignment The horizontal alignment of the label.
 121:    */
 122:   public JLabel(Icon image, int horizontalAlignment)
 123:   {
 124:     this(null, image, horizontalAlignment);
 125:   }
 126: 
 127:   /**
 128:    * Creates a new horizontally leading and vertically centered JLabel 
 129:    * object with no icon and the given text.
 130:    *
 131:    * @param text The text to use with the label.
 132:    */
 133:   public JLabel(String text)
 134:   {
 135:     this(text, null, LEADING);
 136:   }
 137: 
 138:   /**
 139:    * Creates a new vertically centered JLabel object with no icon and the
 140:    * given text and horizontal alignment.
 141:    *
 142:    * @param text The text to use with the label.
 143:    * @param horizontalAlignment The horizontal alignment of the label.
 144:    */
 145:   public JLabel(String text, int horizontalAlignment)
 146:   {
 147:     this(text, null, horizontalAlignment);
 148:   }
 149: 
 150:   /**
 151:    * Creates a new vertically centered JLabel object with the given text,
 152:    * icon, and horizontal alignment.
 153:    *
 154:    * @param text The text to use with the label.
 155:    * @param icon The icon to use with the label.
 156:    * @param horizontalAlignment The horizontal alignment of the label.
 157:    */
 158:   public JLabel(String text, Icon icon, int horizontalAlignment)
 159:   {
 160:     this.text = text;
 161:     this.icon = icon;
 162:     this.horizontalAlignment = horizontalAlignment;
 163:     updateUI();
 164:   }
 165: 
 166:   /**
 167:    * This method returns the label's UI delegate.
 168:    *
 169:    * @return The label's UI delegate.
 170:    */
 171:   public LabelUI getUI()
 172:   {
 173:     return (LabelUI) ui;
 174:   }
 175: 
 176:   /**
 177:    * This method sets the label's UI delegate.
 178:    *
 179:    * @param ui The label's UI delegate.
 180:    */
 181:   public void setUI(LabelUI ui)
 182:   {
 183:     super.setUI(ui);
 184:   }
 185: 
 186:   /**
 187:    * This method resets the label's UI delegate to the default UI for the
 188:    * current look and feel.
 189:    */
 190:   public void updateUI()
 191:   {
 192:     setUI((LabelUI) UIManager.getUI(this));
 193:   }
 194: 
 195:   /**
 196:    * This method returns a name to identify which look and feel class will be
 197:    * the UI delegate for this label.
 198:    *
 199:    * @return The UIClass identifier. "LabelUI"
 200:    */
 201:   public String getUIClassID()
 202:   {
 203:     return "LabelUI";
 204:   }
 205: 
 206:   /**
 207:    * This method is used primarily for debugging purposes and returns a string
 208:    * that can be used to represent this label.
 209:    *
 210:    * @return A string to represent this label.
 211:    */
 212:   protected String paramString()
 213:   {
 214:     return "JLabel";
 215:   }
 216: 
 217:   /**
 218:    * This method returns the label text.
 219:    *
 220:    * @return The label text.
 221:    */
 222:   public String getText()
 223:   {
 224:     return text;
 225:   }
 226: 
 227:   /**
 228:    * This method changes the "text" property. The given text will be painted
 229:    * in the label.
 230:    *
 231:    * @param newText The label's text.
 232:    */
 233:   public void setText(String newText)
 234:   {
 235:     if (text != newText)
 236:       {
 237:     String oldText = text;
 238:     text = newText;
 239:     firePropertyChange("text", oldText, newText);
 240: 
 241:     if (text != null && text.length() <= displayedMnemonicIndex)
 242:       setDisplayedMnemonicIndex(text.length() - 1);
 243:       }
 244:   }
 245: 
 246:   /**
 247:    * This method returns the active icon. The active icon is painted when the
 248:    * label is enabled.
 249:    *
 250:    * @return The active icon.
 251:    */
 252:   public Icon getIcon()
 253:   {
 254:     return icon;
 255:   }
 256: 
 257:   /**
 258:    * This method changes the "icon" property. This icon (the active icon) will
 259:    * be the one displayed when the label is enabled.
 260:    *
 261:    * @param newIcon The active icon.
 262:    */
 263:   public void setIcon(Icon newIcon)
 264:   {
 265:     if (icon != newIcon)
 266:       {
 267:     Icon oldIcon = icon;
 268:     icon = newIcon;
 269:     firePropertyChange("icon", oldIcon, newIcon);
 270:       }
 271:   }
 272: 
 273:   /**
 274:    * This method returns the disabled icon. The disabled icon is painted when
 275:    * the label is disabled. If the disabled icon is null and the active icon
 276:    * is an ImageIcon, this method returns a grayed version of the icon. The
 277:    * grayed  version of the icon becomes the disabledIcon.
 278:    *
 279:    * @return The disabled icon.
 280:    */
 281:   public Icon getDisabledIcon()
 282:   {
 283:     if (disabledIcon == null && icon instanceof ImageIcon)
 284:       disabledIcon = new ImageIcon(GrayFilter.createDisabledImage(((ImageIcon) icon)
 285:                                                                   .getImage()));
 286: 
 287:     return disabledIcon;
 288:   }
 289: 
 290:   /**
 291:    * This method changes the "disabledIcon" property. This icon (the disabled
 292:    * icon) will be the one displayed when the label is disabled.
 293:    *
 294:    * @param newIcon The disabled icon.
 295:    */
 296:   public void setDisabledIcon(Icon newIcon)
 297:   {
 298:     if (disabledIcon != newIcon)
 299:       {
 300:     Icon oldIcon = disabledIcon;
 301:     disabledIcon = newIcon;
 302:     firePropertyChange("disabledIcon", oldIcon, newIcon);
 303:       }
 304:   }
 305: 
 306:   /**
 307:    * This method sets the keycode that will be the label's mnemonic. If the
 308:    * label is used as a label for another component, the label will give
 309:    * focus to that component when the mnemonic is activated.
 310:    *
 311:    * @param mnemonic The keycode to use for the mnemonic.
 312:    */
 313:   public void setDisplayedMnemonic(int mnemonic)
 314:   {
 315:     if (displayedMnemonic != mnemonic)
 316:       {
 317:     firePropertyChange("displayedMnemonic",
 318:                        displayedMnemonic, mnemonic);
 319:     displayedMnemonic = mnemonic;
 320: 
 321:     if (text != null)
 322:       setDisplayedMnemonicIndex(text.toUpperCase().indexOf(mnemonic));
 323:       }
 324:   }
 325: 
 326:   /**
 327:    * This method sets the character that will be the mnemonic used. If the
 328:    * label is used as a label for another component, the label will give
 329:    * focus to that component when the mnemonic is activated.
 330:    *
 331:    * @param mnemonic The character to use for the mnemonic.
 332:    */
 333:   public void setDisplayedMnemonic(char mnemonic)
 334:   {
 335:     setDisplayedMnemonic((int) Character.toUpperCase(mnemonic));
 336:   }
 337: 
 338:   /**
 339:    * This method returns the keycode that is used for the label's mnemonic.
 340:    *
 341:    * @return The keycode that is used for the label's mnemonic.
 342:    */
 343:   public int getDisplayedMnemonic()
 344:   {
 345:     return (int) displayedMnemonic;
 346:   }
 347: 
 348:   /**
 349:    * This method sets which character in the text will be the underlined
 350:    * character. If the given index is -1, then this indicates  that there is
 351:    * no mnemonic. If the index is less than -1 or if the index is equal to
 352:    * the length, this method will throw an IllegalArgumentException.
 353:    *
 354:    * @param newIndex The index of the character to underline.
 355:    *
 356:    * @throws IllegalArgumentException If index less than -1 or index equals
 357:    *         length.
 358:    */
 359:   public void setDisplayedMnemonicIndex(int newIndex)
 360:     throws IllegalArgumentException
 361:   {
 362:     if (newIndex < -1 || (text != null && newIndex >= text.length()))
 363:       throw new IllegalArgumentException();
 364: 
 365:     if (newIndex == -1
 366:         || text == null
 367:     || text.charAt(newIndex) != displayedMnemonic)
 368:       newIndex = -1;
 369: 
 370:     if (newIndex != displayedMnemonicIndex)
 371:       {
 372:     int oldIndex = displayedMnemonicIndex;
 373:     displayedMnemonicIndex = newIndex;
 374:     firePropertyChange("displayedMnemonicIndex",
 375:                        oldIndex, newIndex);
 376:       }
 377:   }
 378: 
 379:   /**
 380:    * This method returns which character in the text will be  the underlined
 381:    * character.
 382:    *
 383:    * @return The index of the character that will be underlined.
 384:    */
 385:   public int getDisplayedMnemonicIndex()
 386:   {
 387:     return displayedMnemonicIndex;
 388:   }
 389: 
 390:   /**
 391:    * This method ensures that the key is valid as a horizontal alignment.
 392:    * Valid keys are: LEFT, CENTER, RIGHT, LEADING, TRAILING
 393:    *
 394:    * @param key The key to check.
 395:    * @param message The message of the exception to be thrown if the key is
 396:    *        invalid.
 397:    *
 398:    * @return The key if it's valid.
 399:    *
 400:    * @throws IllegalArgumentException If the key is invalid.
 401:    */
 402:   protected int checkHorizontalKey(int key, String message)
 403:   {
 404:     if (key != LEFT && key != CENTER && key != RIGHT && key != LEADING
 405:         && key != TRAILING)
 406:       throw new IllegalArgumentException(message);
 407:     else
 408:       return key;
 409:   }
 410: 
 411:   /**
 412:    * This method ensures that the key is valid as a  vertical alignment. Valid
 413:    * keys are: TOP, CENTER, and BOTTOM.
 414:    *
 415:    * @param key The key to check.
 416:    * @param message The message of the exception to be thrown if the key is
 417:    *        invalid.
 418:    *
 419:    * @return The key if it's valid.
 420:    *
 421:    * @throws IllegalArgumentException If the key is invalid.
 422:    */
 423:   protected int checkVerticalKey(int key, String message)
 424:   {
 425:     if (key != TOP && key != BOTTOM && key != CENTER)
 426:       throw new IllegalArgumentException(message);
 427:     else
 428:       return key;
 429:   }
 430: 
 431:   /**
 432:    * This method returns the gap between the icon and the text.
 433:    *
 434:    * @return The gap between the icon and the text.
 435:    */
 436:   public int getIconTextGap()
 437:   {
 438:     return iconTextGap;
 439:   }
 440: 
 441:   /**
 442:    * This method changes the "iconTextGap" property. The iconTextGap
 443:    * determines how much space there is between the icon and the text.
 444:    *
 445:    * @param newGap The gap between the icon and the text.
 446:    */
 447:   public void setIconTextGap(int newGap)
 448:   {
 449:     if (iconTextGap != newGap)
 450:       {
 451:     firePropertyChange("iconTextGap", iconTextGap, newGap);
 452:     iconTextGap = newGap;
 453:       }
 454:   }
 455: 
 456:   /**
 457:    * This method returns the vertical alignment of the label.
 458:    *
 459:    * @return The vertical alignment of the label.
 460:    */
 461:   public int getVerticalAlignment()
 462:   {
 463:     return verticalAlignment;
 464:   }
 465: 
 466:   /**
 467:    * This method changes the "verticalAlignment" property of the label. The
 468:    * vertical alignment determines how where the label will be placed
 469:    * vertically. If the alignment is not valid, it will default to the
 470:    * center.
 471:    *
 472:    * @param alignment The vertical alignment of the label.
 473:    */
 474:   public void setVerticalAlignment(int alignment)
 475:   {
 476:     if (alignment == verticalAlignment)
 477:       return;
 478: 
 479:     int oldAlignment = verticalAlignment;
 480:     verticalAlignment = checkVerticalKey(alignment, "verticalAlignment");
 481:     firePropertyChange("verticalAlignment", oldAlignment, verticalAlignment);
 482:   }
 483: 
 484:   /**
 485:    * This method returns the horziontal alignment of the label.
 486:    *
 487:    * @return The horizontal alignment of the label.
 488:    */
 489:   public int getHorizontalAlignment()
 490:   {
 491:     return horizontalAlignment;
 492:   }
 493: 
 494:   /**
 495:    * This method changes the "horizontalAlignment" property. The horizontal
 496:    * alignment determines where the label will be placed horizontally.
 497:    *
 498:    * @param alignment The horizontal alignment of the label.
 499:    */
 500:   public void setHorizontalAlignment(int alignment)
 501:   {
 502:     if (horizontalAlignment == alignment)
 503:       return;
 504:     
 505:     int oldAlignment = horizontalAlignment;
 506:     horizontalAlignment = checkHorizontalKey(alignment, "horizontalAlignment");
 507:     firePropertyChange("horizontalAlignment", oldAlignment,
 508:                        horizontalAlignment);
 509:   }
 510: 
 511:   /**
 512:    * This method returns the vertical text position of the label.
 513:    *
 514:    * @return The vertical text position of the label.
 515:    */
 516:   public int getVerticalTextPosition()
 517:   {
 518:     return verticalTextPosition;
 519:   }
 520: 
 521:   /**
 522:    * This method changes the "verticalTextPosition" property of the label. The
 523:    * vertical text position determines where the text will be placed
 524:    * vertically relative to the icon.
 525:    *
 526:    * @param textPosition The vertical text position.
 527:    */
 528:   public void setVerticalTextPosition(int textPosition)
 529:   {
 530:     if (textPosition != verticalTextPosition)
 531:       {
 532:     int oldPos = verticalTextPosition;
 533:     verticalTextPosition = checkVerticalKey(textPosition,
 534:                                             "verticalTextPosition");
 535:     firePropertyChange("verticalTextPosition", oldPos,
 536:                        verticalTextPosition);
 537:       }
 538:   }
 539: 
 540:   /**
 541:    * This method returns the horizontal text position of the label.
 542:    *
 543:    * @return The horizontal text position.
 544:    */
 545:   public int getHorizontalTextPosition()
 546:   {
 547:     return horizontalTextPosition;
 548:   }
 549: 
 550:   /**
 551:    * This method changes the "horizontalTextPosition" property of the label.
 552:    * The horizontal text position determines where the text will be placed
 553:    * horizontally relative to the icon.
 554:    *
 555:    * @param textPosition The horizontal text position.
 556:    */
 557:   public void setHorizontalTextPosition(int textPosition)
 558:   {
 559:     if (textPosition != horizontalTextPosition)
 560:       {
 561:     int oldPos = horizontalTextPosition;
 562:     horizontalTextPosition = checkHorizontalKey(textPosition,
 563:                                                 "horizontalTextPosition");
 564:     firePropertyChange("horizontalTextPosition", oldPos,
 565:                        horizontalTextPosition);
 566:       }
 567:   }
 568: 
 569:   /**
 570:    * This method simply returns false if the current icon image (current  icon
 571:    * will depend on whether the label is enabled) is not equal to the passed
 572:    * in image.
 573:    *
 574:    * @param img The image to check.
 575:    * @param infoflags The bitwise inclusive OR of ABORT, ALLBITS, ERROR,
 576:    *        FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, and WIDTH
 577:    * @param x The x position
 578:    * @param y The y position
 579:    * @param w The width
 580:    * @param h The height
 581:    *
 582:    * @return Whether the current icon image is equal to the image given.
 583:    */
 584:   public boolean imageUpdate(Image img, int infoflags, int x, int y, int w,
 585:                              int h)
 586:   {
 587:     Icon currIcon = isEnabled() ? icon : disabledIcon;
 588: 
 589:     // XXX: Is this the correct way to check for image equality?
 590:     if (currIcon != null && currIcon instanceof ImageIcon)
 591:       return (((ImageIcon) currIcon).getImage() == img);
 592: 
 593:     return false;
 594:   }
 595: 
 596:   /**
 597:    * This method returns the component that the label gives focus to  when the
 598:    * mnemonic is activated.
 599:    *
 600:    * @return The component that gets focus when the label's mnemonic is
 601:    *         activated.
 602:    */
 603:   public Component getLabelFor()
 604:   {
 605:     return labelFor;
 606:   }
 607: 
 608:   /**
 609:    * This method changes the "labelFor" property. The component that the label
 610:    * is acting as a label for will request focus when the label's  mnemonic
 611:    * is activated.
 612:    *
 613:    * @param c The component that gets focus when the label's mnemonic is
 614:    *        activated.
 615:    */
 616:   public void setLabelFor(Component c)
 617:   {
 618:     if (c != labelFor)
 619:       {
 620:     Component oldLabelFor = labelFor;
 621:     labelFor = c;
 622:     firePropertyChange("labelFor", oldLabelFor, labelFor);
 623:       }
 624:   }
 625: 
 626:   /**
 627:    * This method overrides setFont so that we can call for a repaint after the
 628:    * font is changed.
 629:    *
 630:    * @param f The font for this label.
 631:    */
 632:   public void setFont(Font f)
 633:   {
 634:     super.setFont(f);
 635:     repaint();
 636:   }
 637: 
 638:   /**
 639:    * DOCUMENT ME!
 640:    *
 641:    * @return
 642:    */
 643:   public AccessibleContext getAccessibleContext()
 644:   {
 645:     return null;
 646:   }
 647: }