libjava/javax/swing/JLayeredPane.java

   1 /* JLayeredPane.java --
   2    Copyright (C) 2002, 2004 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 package javax.swing;
  39
  40 import java.awt.Component;
  41 import java.util.Hashtable;
  42 import java.util.Iterator;
  43 import java.util.Map;
  44 import java.util.TreeMap;
  45 import javax.accessibility.Accessible;
  46
  47 /**
  48  * <p>The "Layered Pane" is a container which divides its children into 6 (or
  49  * more) disjoint sets. the pre-defined sets are:</p>
  50  *
  51  *  <ul>
  52  *    <li>"Frame Content"</li>
  53  *    <li>"Default"</li>
  54  *    <li>"Palette"</li>
  55  *    <li>"Modal"</li>
  56  *    <li>"Popup"</li>
  57  *    <li>"Drag"</li>
  58  *  </ul>
  59  *
  60  * <p>A child is in exactly one of these layers at any time, though there may
  61  * be other layers if someone creates them.</p>
  62  *
  63  * <p>The purpose of this class is to translate this view of "layers" into a
  64  * contiguous array of components: the one held in our ancestor,
  65  * {@link java.awt.Container}.</p>
  66  *
  67  * <p>There is a precise set of words we will use to refer to numbers within
  68  * this class:</p>
  69  *
  70  * <dl>
  71  * <dt>Component Index:</dt>
  72  * <dd>An offset into the <code>component</code> array held in our ancestor,
  73  * {@link java.awt.Container}, from <code>[0 .. component.length)</code>. The drawing
  74  * rule with indices is that 0 is drawn last.</dd>
  75  *
  76  * <dt>Layer Number:</dt>
  77  * <dd>A general <code>int</code> specifying a layer within this component.  Negative
  78  * numbers are drawn first, then layer 0, then positive numbered layers, in
  79  * ascending order.</dd>
  80  *
  81  * <dt>Position:</dt>
  82  * <dd>An offset into a layer's "logical drawing order". Layer position 0
  83  * is drawn last. Layer position -1 is a synonym for the first layer
  84  * position (the logical "bottom").</dd>
  85  * </dl>
  86  *
  87  * <p><b>Note:</b> the layer numbering order is the <em>reverse</em> of the
  88  * component indexing and position order</p>
  89  *
  90  * @author Graydon Hoare <graydon@redhat.com>
  91  */
  92 public class JLayeredPane extends JComponent implements Accessible
  93 {
  94   private static final long serialVersionUID = 5534920399324590459L;
  95
  96   public static final String LAYER_PROPERTY = "layeredContainerLayer";
  97
  98   public static Integer FRAME_CONTENT_LAYER = new Integer (-30000);
  99
 100   public static Integer DEFAULT_LAYER = new Integer (0);
 101   public static Integer PALETTE_LAYER = new Integer (100);
 102   public static Integer MODAL_LAYER   = new Integer (200);
 103   public static Integer POPUP_LAYER   = new Integer (300);
 104   public static Integer DRAG_LAYER    = new Integer (400);
 105
 106   TreeMap layers;               // Layer Number (Integer) -> Layer Size (Integer)
 107   Hashtable componentToLayer;   // Component -> Layer Number (Integer)
 108
 109   public JLayeredPane()
 110   {
 111     layers = new TreeMap ();
 112     componentToLayer = new Hashtable ();
 113   }
 114
 115
 116   /**
 117    * Looks up the layer a child component is currently assigned to.
 118    *
 119    * @param c the component to look up.
 120    * @return the layer the component is currently assigned to, in this container.
 121    * @throws IllegalArgumentException if the component is not a child of this container.
 122    */
 123
 124   protected Integer getLayer (Component c)
 125   {
 126     if (! componentToLayer.containsKey (c))
 127             throw new IllegalArgumentException ();
 128     return (Integer) componentToLayer.get (c);
 129   }
 130
 131   /**
 132    * <p>Returns a pair of ints representing a half-open interval
 133    * <code>[top, bottom)</code>, which is the range of component indices
 134    * the provided layer number corresponds to.</p>
 135    *
 136    * <p>Note that "bottom" is <em>not</em> included in the interval of
 137    * component indices in this layer: a layer with 0 elements in it has
 138    * <code>ret[0] == ret[1]</code>.</p>
 139    *
 140    * @param layer the layer to look up.
 141    * @return the half-open range of indices this layer spans.
 142    * @throws IllegalArgumentException if layer does not refer to an active layer
 143    * in this container.
 144    */
 145
 146   protected int[] layerToRange (Integer layer)
 147   {
 148     int[] ret = new int[2];
 149     ret[1] = getComponents ().length;
 150     Iterator i = layers.entrySet ().iterator ();
 151     while (i.hasNext())
 152             {
 153         Map.Entry pair = (Map.Entry) i.next();
 154         Integer layerNum = (Integer) pair.getKey ();
 155         Integer layerSz = (Integer) pair.getValue ();
 156         if (layerNum.intValue() == layer.intValue())
 157           {
 158             ret[0] = ret[1] - layerSz.intValue ();
 159             return ret;
 160           }
 161         else
 162           {
 163             ret[1] -= layerSz.intValue ();
 164           }
 165             }
 166     // should have found the layer during iteration
 167     throw new IllegalArgumentException ();
 168   }
 169
 170   /**
 171    * Increments the recorded size of a given layer.
 172    *
 173    * @param layer the layer number to increment.
 174    * @see #incrLayer()
 175    */
 176
 177   protected void incrLayer(Integer layer)
 178   {
 179     int sz = 1;
 180     if (layers.containsKey (layer))
 181             sz += ((Integer)(layers.get (layer))).intValue ();
 182     layers.put (layer, new Integer(sz));
 183   }
 184
 185   /**
 186    * Decrements the recorded size of a given layer.
 187    *
 188    * @param layer the layer number to decrement.
 189    * @see #decrLayer()
 190    */
 191
 192   protected void decrLayer(Integer layer)
 193   {
 194     int sz = 0;
 195     if (layers.containsKey (layer))
 196             sz = ((Integer)(layers.get (layer))).intValue () - 1;
 197     layers.put (layer, new Integer(sz));
 198   }
 199
 200   /**
 201    * Return the greatest layer number currently in use, in this container.
 202    * This number may legally be positive <em>or</em> negative.
 203    *
 204    * @return the least layer number.
 205    * @see #lowestLayer()
 206    */
 207
 208   public int highestLayer()
 209   {
 210     if (layers.size() == 0)
 211             return 0;
 212     return ((Integer)(layers.lastKey ())).intValue ();
 213   }
 214
 215   /**
 216    * Return the least layer number currently in use, in this container.
 217    * This number may legally be positive <em>or</em> negative.
 218    *
 219    * @return the least layer number.
 220    * @see #highestLayer()
 221    */
 222
 223   public int lowestLayer()
 224   {
 225     if (layers.size() == 0)
 226             return 0;
 227     return ((Integer)(layers.firstKey ())).intValue ();
 228   }
 229
 230   /**
 231    * Moves a component to the "front" of its layer. The "front" is a
 232    * synonym for position 0, which is also the last position drawn in each
 233    * layer, so is usually the component which occludes the most other
 234    * components in its layer.
 235    *
 236    * @param c the component to move to the front of its layer.
 237    * @throws IllegalArgumentException if the component is not a child of
 238    * this container.
 239    * @see #moveToBack()
 240    */
 241
 242   public void moveToFront(Component c)
 243   {
 244     setPosition (c, 0);
 245   }
 246
 247   /**
 248    * <p>Moves a component to the "back" of its layer. The "back" is a
 249    * synonym for position N-1 (also known as position -1), where N is the
 250    * size of the layer.</p>
 251    *
 252    * <p>The "back" of a layer is the first position drawn, so the component at
 253    * the "back" is usually the component which is occluded by the most
 254    * other components in its layer.</p>
 255    *
 256    * @param c the component to move to the back of its layer.
 257    * @throws IllegalArgumentException if the component is not a child of
 258    * this container.
 259    * @see #moveToFront()
 260    */
 261
 262   public void moveToBack(Component c)
 263   {
 264     setPosition (c, -1);
 265   }
 266
 267   /**
 268    * Return the position of a component within its layer. Positions are assigned
 269    * from the "front" (position 0) to the "back" (position N-1), and drawn from
 270    * the back towards the front.
 271    *
 272    * @param c the component to get the position of.
 273    * @throws IllegalArgumentException if the component is not a child of
 274    * this container.
 275    * @see #setPosition()
 276    */
 277
 278   public int getPosition(Component c)
 279   {
 280     Integer layer = getLayer (c);
 281     int[] range = layerToRange (layer);
 282     int top = range[0];
 283     int bot = range[1];
 284     Component[] comps = getComponents ();
 285     for (int i = top; i < bot; ++i)
 286             {
 287         if (comps[i] == c)
 288           return i - top;
 289             }
 290     // should have found it
 291     throw new IllegalArgumentException ();
 292   }
 293
 294   /**
 295    * Change the position of a component within its layer. Positions are assigned
 296    * from the "front" (position 0) to the "back" (position N-1), and drawn from
 297    * the back towards the front.
 298    *
 299    * @param c the component to change the position of.
 300    * @param position the position to assign the component to.
 301    * @throws IllegalArgumentException if the component is not a child of
 302    * this container.
 303    * @see #getPosition()
 304    */
 305
 306   public void setPosition(Component c, int position)
 307   {
 308     Integer layer = getLayer (c);
 309     int[] range = layerToRange (layer);
 310     if (range[0] == range[1])
 311             throw new IllegalArgumentException ();
 312
 313     int top = range[0];
 314     int bot = range[1];
 315     if (position == -1)
 316             position = (bot - top) - 1;
 317     int targ = Math.min(top + position, bot-1);
 318     int curr = -1;
 319
 320     Component[] comps = getComponents();
 321     for (int i = top; i < bot; ++i)
 322             {
 323         if (comps[i] == c)
 324           {
 325             curr = i;
 326             break;
 327           }
 328             }
 329     if (curr == -1)
 330             // should have found it
 331             throw new IllegalArgumentException ();
 332
 333     super.swapComponents (curr, targ);
 334     revalidate();
 335     repaint();
 336   }
 337
 338   /**
 339    * Return an array of all components within a layer of this
 340    * container. Components are ordered front-to-back, with the "front"
 341    * element (which draws last) at position 0 of the returned array.
 342    *
 343    * @param layer the layer to return components from.
 344    * @return the components in the layer.
 345    */
 346
 347   public Component[] getComponentsInLayer(int layer)
 348   {
 349     int[] range = layerToRange (getObjectForLayer (layer));
 350     if (range[0] == range[1])
 351             return new Component[0];
 352     else
 353             {
 354         Component[] comps = getComponents ();
 355         int sz = range[1] - range[0];
 356         Component[] nc = new Component[sz];
 357         for (int i = 0; i < sz; ++i)
 358           nc[i] = comps[range[0] + i];
 359         return nc;
 360             }
 361   }
 362
 363   /**
 364    * Return the number of components within a layer of this
 365    * container.
 366    *
 367    * @param layer the layer count components in.
 368    * @return the number of components in the layer.
 369    */
 370
 371   public int getComponentCountInLayer(int layer)
 372   {
 373     int[] range = layerToRange (getObjectForLayer (layer));
 374     if (range[0] == range[1])
 375             return 0;
 376     else
 377             return (range[1] - range[0]);
 378   }
 379
 380   /**
 381    * Return a hashtable mapping child components of this container to
 382    * Integer objects representing the component's layer assignments.
 383    */
 384
 385   protected Hashtable getComponentToLayer()
 386   {
 387     return componentToLayer;
 388   }
 389
 390   /**
 391    * Return the index of a component within the underlying (contiguous)
 392    * array of children. This is a "raw" number which does not represent the
 393    * child's position in a layer, but rather its position in the logical
 394    * drawing order of all children of the container.
 395    *
 396    * @param c the component to look up.
 397    * @return the external index of the component.
 398    * @throws IllegalArgumentException if the component is not a child of
 399    * this container.
 400    */
 401
 402   public int getIndexOf(Component c)
 403   {
 404     Integer layer = getLayer (c);
 405     int[] range = layerToRange (layer);
 406     Component[] comps = getComponents();
 407     for (int i = range[0]; i < range[1]; ++i)
 408             {
 409         if (comps[i] == c)
 410           return i;
 411             }
 412     // should have found the component during iteration
 413     throw new IllegalArgumentException ();
 414   }
 415
 416   /**
 417    * Return an Integer object which holds the same int value as the
 418    * parameter. This is strictly an optimization to minimize the number of
 419    * identical Integer objects which we allocate.
 420    *
 421    * @param layer the layer number as an int.
 422    * @return the layer number as an Integer, possibly shared.
 423    */
 424
 425   protected Integer getObjectForLayer(int layer)
 426   {
 427     switch (layer)
 428             {
 429             case -30000:
 430         return FRAME_CONTENT_LAYER;
 431
 432             case 0:
 433         return DEFAULT_LAYER;
 434
 435             case 100:
 436         return PALETTE_LAYER;
 437
 438             case 200:
 439         return MODAL_LAYER;
 440
 441             case 300:
 442         return POPUP_LAYER;
 443
 444             case 400:
 445         return DRAG_LAYER;
 446
 447             default:
 448         break;
 449             }
 450
 451     return new Integer(layer);
 452   }
 453
 454   /**
 455    * Computes an index at which to request the superclass {@link
 456    * java.awt.Container} inserts a component, given an abstract layer and
 457    * position number.
 458    *
 459    * @param layer the layer in which to insert a component.
 460    * @param position the position in the layer at which to insert a component.
 461    * @return the index at which to insert the component.
 462    */
 463
 464   protected int insertIndexForLayer(int layer, int position)
 465   {
 466
 467     Integer lobj = getObjectForLayer (layer);
 468     if (! layers.containsKey(lobj))
 469       layers.put (lobj, new Integer (0));
 470     int[] range = layerToRange (lobj);
 471     if (range[0] == range[1])
 472         return range[0];
 473
 474     int top = range[0];
 475     int bot = range[1];
 476
 477     if (position == -1 || position > (bot - top))
 478         return bot;
 479     else
 480         return top + position;
 481   }
 482
 483   /**
 484    * Removes a child from this container. The child is specified by
 485    * index. After removal, the child no longer occupies a layer.
 486    *
 487    * @param index the index of the child component to remove.
 488    */
 489
 490   public void remove (int index)
 491   {
 492     Component c = getComponent (index);
 493     Integer layer = getLayer (c);
 494     decrLayer (layer);
 495     componentToLayer.remove (c);
 496     super.remove (index);
 497     revalidate();
 498     repaint();
 499   }
 500
 501   /**
 502    * Removes a child from this container. The child is specified directly.
 503    * After removal, the child no longer occupies a layer.
 504    *
 505    * @param comp the child to remove.
 506    */
 507
 508   public void remove (Component comp)
 509   {
 510     remove (getIndexOf (comp));
 511   }
 512
 513   /**
 514    * <p>Set the layer property for a component, within this container. The
 515    * component will be implicitly mapped to the bottom-most position in the
 516    * layer, but only if added <em>after</em> calling this method.</p>
 517    *
 518    * <p>Read that carefully: this method should be called <em>before</em> the
 519    * component is added to the container.</p>
 520    *
 521    * @param c the component to set the layer property for.
 522    * @param layer the layer number to assign to the component.
 523    */
 524
 525   public void setLayer(Component c, int layer)
 526   {
 527     componentToLayer.put (c, getObjectForLayer (layer));
 528   }
 529
 530   /**
 531    * Set the layer and position of a component, within this container.
 532    *
 533    * @param c the child component to set the layer property for.
 534    * @param layer the layer number to assign to the component.
 535    * @param position the position number to assign to the component.
 536    */
 537
 538   public void setLayer(Component c,
 539                        int layer,
 540                        int position)
 541   {
 542     remove(c);
 543     add(c, getObjectForLayer (layer));
 544     setPosition(c, position);
 545     revalidate();
 546     repaint();
 547   }
 548
 549   /**
 550    * Overrides the default implementation from {@link java.awt.Container}
 551    * such that <code>layerConstraint</code> is interpreted as an {@link
 552    * Integer}, specifying the layer to which the component will be added
 553    * (at the bottom position).
 554    *
 555    * @param comp the component to add.
 556    * @param layerConstraint an integer specifying the layer to add the component to.
 557    * @param index an ignored parameter, for compatibility.
 558    */
 559
 560   protected void addImpl(Component comp, Object layerConstraint, int index)
 561   {
 562     Integer layer;
 563     if (layerConstraint != null && layerConstraint instanceof Integer)
 564       layer = (Integer) layerConstraint;
 565     else if (componentToLayer.containsKey (comp))
 566             layer = (Integer) componentToLayer.remove (comp);
 567     else
 568             layer = DEFAULT_LAYER;
 569
 570     int newIdx = insertIndexForLayer(layer.intValue (), index);
 571
 572     componentToLayer.put (comp, layer);
 573     incrLayer (layer);
 574
 575     super.addImpl(comp, null, newIdx);
 576     revalidate();
 577     repaint();
 578   }
 579 }