Source for gnu.java.awt.AWTUtilities

   1: /* AWTUtilities.java -- Common utility methods for AWT and Swing.
   2:    Copyright (C) 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: package gnu.java.awt;
  39: 
  40: import java.applet.Applet;
  41: import java.awt.Component;
  42: import java.awt.Container;
  43: import java.awt.Font;
  44: import java.awt.FontMetrics;
  45: import java.awt.Insets;
  46: import java.awt.Point;
  47: import java.awt.Rectangle;
  48: import java.awt.Toolkit;
  49: import java.awt.Window;
  50: import java.awt.event.MouseEvent;
  51: import java.util.AbstractSequentialList;
  52: import java.util.List;
  53: import java.util.ListIterator;
  54: import java.util.NoSuchElementException;
  55: import java.util.WeakHashMap;
  56: import java.lang.reflect.InvocationTargetException;
  57: 
  58: /**
  59:  * This class mirrors the javax.swing.SwingUtilities class. It 
  60:  * provides commonly needed functionalities for AWT classes without
  61:  * the need to reference classes in the javax.swing package.
  62:  */
  63: public class AWTUtilities
  64: {
  65: 
  66:   /**
  67:    * This List implementation wraps the Component[] returned by
  68:    * {@link Container#getComponents()} and iterates over the visible Components
  69:    * in that array. This class is used in {@link #getVisibleChildren}.
  70:    */
  71:   static class VisibleComponentList extends AbstractSequentialList
  72:   {
  73:     /**
  74:      * The ListIterator for this List.
  75:      */
  76:     class VisibleComponentIterator implements ListIterator
  77:     {
  78:       /** The current index in the Component[]. */
  79:       int index;
  80: 
  81:       /** The index in the List of visible Components. */
  82:       int listIndex;
  83: 
  84:       /**
  85:        * Creates a new VisibleComponentIterator that starts at the specified
  86:        * <code>listIndex</code>. The array of Components is searched from
  87:        * the beginning to find the matching array index.
  88:        *
  89:        * @param listIndex the index from where to begin iterating
  90:        */
  91:       VisibleComponentIterator(int listIndex)
  92:       {
  93:     this.listIndex = listIndex;
  94:     int visibleComponentsFound = 0;
  95:     for (index = 0; visibleComponentsFound != listIndex; index++)
  96:       {
  97:         if (components[index].isVisible())
  98:           visibleComponentsFound++;
  99:       }
 100:       }
 101: 
 102:       /**
 103:        * Returns <code>true</code> if there are more visible components in the
 104:        * array, <code>false</code> otherwise.
 105:        *
 106:        * @return <code>true</code> if there are more visible components in the
 107:        *     array, <code>false</code> otherwise
 108:        */
 109:       public boolean hasNext()
 110:       {
 111:     boolean hasNext = false;
 112:     for (int i = index; i < components.length; i++)
 113:       {
 114:         if (components[i].isVisible())
 115:           {
 116:         hasNext = true;
 117:         break;
 118:           }
 119:       }
 120:     return hasNext;
 121:       }
 122: 
 123:       /**
 124:        * Returns the next visible <code>Component</code> in the List.
 125:        *
 126:        * @return the next visible <code>Component</code> in the List
 127:        *
 128:        * @throws if there is no next element
 129:        */
 130:       public Object next()
 131:       {
 132:     Object o = null;
 133:     for (; index < components.length; index++)
 134:       {
 135:         if (components[index].isVisible())
 136:           {
 137:         o = components[index];
 138:         break;
 139:           }
 140:       }
 141:     if (o != null)
 142:       {
 143:         index++;
 144:         listIndex++;
 145:         return o;
 146:       }
 147:     else
 148:       throw new NoSuchElementException();
 149:       }
 150: 
 151:       /**
 152:        * Returns <code>true</code> if there are more visible components in the
 153:        * array in the reverse direction, <code>false</code> otherwise.
 154:        *
 155:        * @return <code>true</code> if there are more visible components in the
 156:        *     array in the reverse direction, <code>false</code> otherwise
 157:        */
 158:       public boolean hasPrevious()
 159:       {
 160:     boolean hasPrevious = false;
 161:     for (int i = index - 1; i >= 0; i--)
 162:       {
 163:         if (components[i].isVisible())
 164:           {
 165:         hasPrevious = true;
 166:         break;
 167:           }
 168:       }
 169:     return hasPrevious;
 170:       }
 171: 
 172:       /**
 173:        * Returns the previous visible <code>Component</code> in the List.
 174:        *
 175:        * @return the previous visible <code>Component</code> in the List
 176:        *
 177:        * @throws NoSuchElementException if there is no previous element
 178:        */
 179:       public Object previous()
 180:       {
 181:     Object o = null;
 182:     for (index--; index >= 0; index--)
 183:       {
 184:         if (components[index].isVisible())
 185:           {
 186:         o = components[index];
 187:         break;
 188:           }
 189:       }
 190:     if (o != null)
 191:       {
 192:         listIndex--;
 193:         return o;
 194:       }
 195:     else
 196:       throw new NoSuchElementException();
 197:       }
 198: 
 199:       /**
 200:        * Returns the index of the next element in the List.
 201:        *
 202:        * @return the index of the next element in the List
 203:        */
 204:       public int nextIndex()
 205:       {
 206:     return listIndex + 1;
 207:       }
 208: 
 209:       /**
 210:        * Returns the index of the previous element in the List.
 211:        *
 212:        * @return the index of the previous element in the List
 213:        */
 214:       public int previousIndex()
 215:       {
 216:     return listIndex - 1;
 217:       }
 218: 
 219:       /**
 220:        * This operation is not supported because the List is immutable.
 221:        *
 222:        * @throws UnsupportedOperationException because the List is immutable
 223:        */
 224:       public void remove()
 225:       {
 226:     throw new UnsupportedOperationException
 227:       ("VisibleComponentList is immutable");
 228:       }
 229: 
 230:       /**
 231:        * This operation is not supported because the List is immutable.
 232:        *
 233:        * @param o not used here
 234:        *
 235:        * @throws UnsupportedOperationException because the List is immutable
 236:        */
 237:       public void set(Object o)
 238:       {
 239:     throw new UnsupportedOperationException
 240:       ("VisibleComponentList is immutable");
 241:       }
 242: 
 243:       /**
 244:        * This operation is not supported because the List is immutable.
 245:        *
 246:        * @param o not used here
 247:        *
 248:        * @throws UnsupportedOperationException because the List is immutable
 249:        */
 250:       public void add(Object o)
 251:       {
 252:     throw new UnsupportedOperationException
 253:       ("VisibleComponentList is immutable");
 254:       }
 255:     }
 256: 
 257:     /**
 258:      * The components over which we iterate. Only the visible components
 259:      * are returned by this List.
 260:      */
 261:     Component[] components;
 262: 
 263:     /**
 264:      * Creates a new instance of VisibleComponentList that wraps the specified
 265:      * <code>Component[]</code>.
 266:      *
 267:      * @param c the <code>Component[]</code> to be wrapped.
 268:      */
 269:     VisibleComponentList(Component[] c)
 270:     {
 271:       components = c;
 272:     }
 273: 
 274:     /**
 275:      * Returns a {@link ListIterator} for iterating over this List.
 276:      *
 277:      * @return a {@link ListIterator} for iterating over this List
 278:      */
 279:     public ListIterator listIterator(int index)
 280:     {
 281:       return new VisibleComponentIterator(index);
 282:     }
 283: 
 284:     /**
 285:      * Returns the number of visible components in the wrapped Component[].
 286:      *
 287:      * @return the number of visible components
 288:      */
 289:     public int size()
 290:     {
 291:       int visibleComponents = 0;
 292:       for (int i = 0; i < components.length; i++)
 293:     if (components[i].isVisible())
 294:       visibleComponents++;
 295:       return visibleComponents;
 296:     }
 297:   }
 298: 
 299:   /**
 300:    * The cache for our List instances. We try to hold one instance of
 301:    * VisibleComponentList for each Component[] that is requested. Note
 302:    * that we use a WeakHashMap for caching, so that the cache itself
 303:    * does not keep the array or the List from beeing garbage collected
 304:    * if no other objects hold references to it.
 305:    */
 306:   static WeakHashMap visibleChildrenCache = new WeakHashMap();
 307: 
 308:   /**
 309:    * Returns the visible children of a {@link Container}. This method is
 310:    * commonly needed in LayoutManagers, because they only have to layout
 311:    * the visible children of a Container.
 312:    *
 313:    * @param c the Container from which to extract the visible children
 314:    *
 315:    * @return the visible children of <code>c</code>
 316:    */
 317:   public static List getVisibleChildren(Container c)
 318:   {
 319:     Component[] children = c.getComponents();
 320:     Object o = visibleChildrenCache.get(children);
 321:     VisibleComponentList visibleChildren = null;
 322:     if (o == null)
 323:       {
 324:     visibleChildren = new VisibleComponentList(children);
 325:     visibleChildrenCache.put(children, visibleChildren);
 326:       }
 327:     else
 328:       visibleChildren = (VisibleComponentList) o;
 329: 
 330:     return visibleChildren;
 331:   }
 332: 
 333:   /**
 334:    * Calculates the portion of the base rectangle which is inside the
 335:    * insets.
 336:    *
 337:    * @param base The rectangle to apply the insets to
 338:    * @param insets The insets to apply to the base rectangle
 339:    * @param ret A rectangle to use for storing the return value, or
 340:    * <code>null</code>
 341:    *
 342:    * @return The calculated area inside the base rectangle and its insets,
 343:    * either stored in ret or a new Rectangle if ret is <code>null</code>
 344:    *
 345:    * @see #calculateInnerArea
 346:    */
 347:   public static Rectangle calculateInsetArea(Rectangle base, Insets insets,
 348:                                              Rectangle ret)
 349:   {
 350:     if (ret == null)
 351:       ret = new Rectangle();
 352:     ret.setBounds(base.x + insets.left, base.y + insets.top,
 353:         base.width - (insets.left + insets.right),
 354:         base.height - (insets.top + insets.bottom));
 355:     return ret;
 356:   }
 357: 
 358:   /**
 359:    * Calculates the bounds of a component in the component's own coordinate
 360:    * space. The result has the same height and width as the component's
 361:    * bounds, but its location is set to (0,0).
 362:    *
 363:    * @param aComponent The component to measure
 364:    *
 365:    * @return The component's bounds in its local coordinate space
 366:    */
 367:   public static Rectangle getLocalBounds(Component aComponent)
 368:   {
 369:     Rectangle bounds = aComponent.getBounds();
 370:     return new Rectangle(0, 0, bounds.width, bounds.height);
 371:   }
 372: 
 373:   /**
 374:    * Returns the font metrics object for a given font. The metrics can be
 375:    * used to calculate crude bounding boxes and positioning information,
 376:    * for laying out components with textual elements.
 377:    *
 378:    * @param font The font to get metrics for
 379:    *
 380:    * @return The font's metrics
 381:    *
 382:    * @see java.awt.font.GlyphMetrics
 383:    */
 384:   public static FontMetrics getFontMetrics(Font font)
 385:   {
 386:     return Toolkit.getDefaultToolkit().getFontMetrics(font);
 387:   }
 388: 
 389:   /**
 390:    * Returns the least ancestor of <code>comp</code> which has the
 391:    * specified name.
 392:    *
 393:    * @param name The name to search for
 394:    * @param comp The component to search the ancestors of
 395:    *
 396:    * @return The nearest ancestor of <code>comp</code> with the given
 397:    * name, or <code>null</code> if no such ancestor exists
 398:    *
 399:    * @see java.awt.Component#getName
 400:    * @see #getAncestorOfClass
 401:    */
 402:   public static Container getAncestorNamed(String name, Component comp)
 403:   {
 404:     while (comp != null && (comp.getName() != name))
 405:       comp = comp.getParent();
 406:     return (Container) comp;
 407:   }
 408: 
 409:   /**
 410:    * Returns the least ancestor of <code>comp</code> which is an instance
 411:    * of the specified class.
 412:    *
 413:    * @param c The class to search for
 414:    * @param comp The component to search the ancestors of
 415:    *
 416:    * @return The nearest ancestor of <code>comp</code> which is an instance
 417:    * of the given class, or <code>null</code> if no such ancestor exists
 418:    *
 419:    * @see #getAncestorOfClass
 420:    * @see #windowForComponent
 421:    * @see 
 422:    * 
 423:    */
 424:   public static Container getAncestorOfClass(Class c, Component comp)
 425:   {
 426:     while (comp != null && (! c.isInstance(comp)))
 427:       comp = comp.getParent();
 428:     return (Container) comp;
 429:   }
 430: 
 431:   /**
 432:    * Equivalent to calling <code>getAncestorOfClass(Window, comp)</code>.
 433:    *
 434:    * @param comp The component to search for an ancestor window 
 435:    *
 436:    * @return An ancestral window, or <code>null</code> if none exists
 437:    */
 438:   public static Window windowForComponent(Component comp)
 439:   {
 440:     return (Window) getAncestorOfClass(Window.class, comp);
 441:   }
 442: 
 443:   /**
 444:    * Returns the "root" of the component tree containint <code>comp</code>
 445:    * The root is defined as either the <em>least</em> ancestor of
 446:    * <code>comp</code> which is a {@link Window}, or the <em>greatest</em>
 447:    * ancestor of <code>comp</code> which is a {@link Applet} if no {@link
 448:    * Window} ancestors are found.
 449:    *
 450:    * @param comp The component to search for a root
 451:    *
 452:    * @return The root of the component's tree, or <code>null</code>
 453:    */
 454:   public static Component getRoot(Component comp)
 455:   {
 456:     Applet app = null;
 457:     Window win = null;
 458: 
 459:     while (comp != null)
 460:      {
 461:       if (win == null && comp instanceof Window)
 462:         win = (Window) comp;
 463:       else if (comp instanceof Applet)
 464:         app = (Applet) comp;
 465:       comp = comp.getParent();
 466:     }
 467: 
 468:     if (win != null)
 469:       return win;
 470:     else
 471:       return app;
 472:   }
 473: 
 474:   /**
 475:    * Return true if a descends from b, in other words if b is an
 476:    * ancestor of a.
 477:    *
 478:    * @param a The child to search the ancestry of
 479:    * @param b The potential ancestor to search for
 480:    *
 481:    * @return true if a is a descendent of b, false otherwise
 482:    */
 483:   public static boolean isDescendingFrom(Component a, Component b)
 484:   {
 485:     while (true)
 486:      {
 487:       if (a == null || b == null)
 488:         return false;
 489:       if (a == b)
 490:         return true;
 491:       a = a.getParent();
 492:     }
 493:   }
 494: 
 495:   /**
 496:    * Returns the deepest descendent of parent which is both visible and
 497:    * contains the point <code>(x,y)</code>. Returns parent when either
 498:    * parent is not a container, or has no children which contain
 499:    * <code>(x,y)</code>. Returns <code>null</code> when either
 500:    * <code>(x,y)</code> is outside the bounds of parent, or parent is
 501:    * <code>null</code>.
 502:    * 
 503:    * @param parent The component to search the descendents of
 504:    * @param x Horizontal coordinate to search for
 505:    * @param y Vertical coordinate to search for
 506:    *
 507:    * @return A component containing <code>(x,y)</code>, or
 508:    * <code>null</code>
 509:    *
 510:    * @see java.awt.Container#findComponentAt
 511:    */
 512:   public static Component getDeepestComponentAt(Component parent, int x, int y)
 513:   {
 514:     if (parent == null || (! parent.contains(x, y)))
 515:       return null;
 516: 
 517:     if (! (parent instanceof Container))
 518:       return parent;
 519: 
 520:     Container c = (Container) parent;
 521:     return c.findComponentAt(x, y);
 522:   }
 523: 
 524:   /**
 525:    * Converts a point from a component's local coordinate space to "screen"
 526:    * coordinates (such as the coordinate space mouse events are delivered
 527:    * in). This operation is equivalent to translating the point by the
 528:    * location of the component (which is the origin of its coordinate
 529:    * space).
 530:    *
 531:    * @param p The point to convert
 532:    * @param c The component which the point is expressed in terms of
 533:    *
 534:    * @see convertPointFromScreen
 535:    */
 536:   public static void convertPointToScreen(Point p, Component c)
 537:   {
 538:     Point c0 = c.getLocationOnScreen();
 539:     p.translate(c0.x, c0.y);
 540:   }
 541: 
 542:   /**
 543:    * Converts a point from "screen" coordinates (such as the coordinate
 544:    * space mouse events are delivered in) to a component's local coordinate
 545:    * space. This operation is equivalent to translating the point by the
 546:    * negation of the component's location (which is the origin of its
 547:    * coordinate space).
 548:    *
 549:    * @param p The point to convert
 550:    * @param c The component which the point should be expressed in terms of
 551:    */
 552:   public static void convertPointFromScreen(Point p, Component c)
 553:   {
 554:     Point c0 = c.getLocationOnScreen();
 555:     p.translate(-c0.x, -c0.y);
 556:   }
 557: 
 558:   /**
 559:    * Converts a point <code>(x,y)</code> from the coordinate space of one
 560:    * component to another. This is equivalent to converting the point from
 561:    * <code>source</code> space to screen space, then back from screen space
 562:    * to <code>destination</code> space. If exactly one of the two
 563:    * Components is <code>null</code>, it is taken to refer to the root
 564:    * ancestor of the other component. If both are <code>null</code>, no
 565:    * transformation is done.
 566:    *
 567:    * @param source The component which the point is expressed in terms of
 568:    * @param x Horizontal coordinate of point to transform
 569:    * @param y Vertical coordinate of point to transform
 570:    * @param destination The component which the return value will be
 571:    * expressed in terms of
 572:    *
 573:    * @return The point <code>(x,y)</code> converted from the coordinate
 574:    *         space of the
 575:    * source component to the coordinate space of the destination component
 576:    *
 577:    * @see #convertPointToScreen
 578:    * @see #convertPointFromScreen
 579:    * @see #convertRectangle
 580:    * @see #getRoot
 581:    */
 582:   public static Point convertPoint(Component source, int x, int y,
 583:                                    Component destination)
 584:   {
 585:     Point pt = new Point(x, y);
 586: 
 587:     if (source == null && destination == null)
 588:       return pt;
 589: 
 590:     if (source == null)
 591:       source = getRoot(destination);
 592: 
 593:     if (destination == null)
 594:       destination = getRoot(source);
 595:     
 596:     if (source.isShowing() && destination.isShowing())
 597:       {
 598:         convertPointToScreen(pt, source);
 599:         convertPointFromScreen(pt, destination);
 600:       }
 601: 
 602:     return pt;
 603:   }
 604: 
 605:   
 606:   /**
 607:    * Converts a rectangle from the coordinate space of one component to
 608:    * another. This is equivalent to converting the rectangle from
 609:    * <code>source</code> space to screen space, then back from screen space
 610:    * to <code>destination</code> space. If exactly one of the two
 611:    * Components is <code>null</code>, it is taken to refer to the root
 612:    * ancestor of the other component. If both are <code>null</code>, no
 613:    * transformation is done.
 614:    *
 615:    * @param source The component which the rectangle is expressed in terms of
 616:    * @param rect The rectangle to convert
 617:    * @param destination The component which the return value will be
 618:    * expressed in terms of
 619:    *
 620:    * @return A new rectangle, equal in size to the input rectangle, but
 621:    * with its position converted from the coordinate space of the source
 622:    * component to the coordinate space of the destination component
 623:    *
 624:    * @see #convertPointToScreen
 625:    * @see #convertPointFromScreen
 626:    * @see #convertPoint
 627:    * @see #getRoot
 628:    */
 629:   public static Rectangle convertRectangle(Component source, Rectangle rect,
 630:                                            Component destination)
 631:   {
 632:     Point pt = convertPoint(source, rect.x, rect.y, destination);
 633:     return new Rectangle(pt.x, pt.y, rect.width, rect.height);
 634:   }
 635: 
 636:   /**
 637:    * Convert a mouse event which refrers to one component to another.  This
 638:    * includes changing the mouse event's coordinate space, as well as the
 639:    * source property of the event. If <code>source</code> is
 640:    * <code>null</code>, it is taken to refer to <code>destination</code>'s
 641:    * root component. If <code>destination</code> is <code>null</code>, the
 642:    * new event will remain expressed in <code>source</code>'s coordinate
 643:    * system.
 644:    *
 645:    * @param source The component the mouse event currently refers to
 646:    * @param sourceEvent The mouse event to convert
 647:    * @param destination The component the new mouse event should refer to
 648:    *
 649:    * @return A new mouse event expressed in terms of the destination
 650:    * component's coordinate space, and with the destination component as
 651:    * its source
 652:    *
 653:    * @see #convertPoint
 654:    */
 655:   public static MouseEvent convertMouseEvent(Component source,
 656:                                              MouseEvent sourceEvent,
 657:                                              Component destination)
 658:   {
 659:     Point newpt = convertPoint(source, sourceEvent.getX(), sourceEvent.getY(),
 660:                                destination);
 661: 
 662:     return new MouseEvent(destination, sourceEvent.getID(),
 663:                           sourceEvent.getWhen(), sourceEvent.getModifiers(),
 664:                           newpt.x, newpt.y, sourceEvent.getClickCount(),
 665:                           sourceEvent.isPopupTrigger(),
 666:                           sourceEvent.getButton());
 667:   }
 668: 
 669: 
 670:   /** 
 671:    * Calls {@link java.awt.EventQueue.invokeLater} with the
 672:    * specified {@link Runnable}. 
 673:    */
 674:   public static void invokeLater(Runnable doRun)
 675:   {
 676:     java.awt.EventQueue.invokeLater(doRun);
 677:   }
 678: 
 679:   /** 
 680:    * Calls {@link java.awt.EventQueue.invokeAndWait} with the
 681:    * specified {@link Runnable}. 
 682:    */
 683:   public static void invokeAndWait(Runnable doRun)
 684:   throws InterruptedException,
 685:   InvocationTargetException
 686:   {
 687:     java.awt.EventQueue.invokeAndWait(doRun);
 688:   }
 689: 
 690:   /** 
 691:    * Calls {@link java.awt.EventQueue.isEventDispatchThread}.
 692:    */
 693:   public static boolean isEventDispatchThread()
 694:   {
 695:     return java.awt.EventQueue.isDispatchThread();
 696:   }
 697: }