libjava/java/awt/CardLayout.java

   1 // CardLayout.java - Card-based layout engine
   2
   3 /* Copyright (C) 1999, 2000, 2002, 2003  Free Software Foundation
   4
   5 This file is part of GNU Classpath.
   6
   7 GNU Classpath is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Classpath is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Classpath; see the file COPYING.  If not, write to the
  19 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  20 02111-1307 USA.
  21
  22 Linking this library statically or dynamically with other modules is
  23 making a combined work based on this library.  Thus, the terms and
  24 conditions of the GNU General Public License cover the whole
  25 combination.
  26
  27 As a special exception, the copyright holders of this library give you
  28 permission to link this library with independent modules to produce an
  29 executable, regardless of the license terms of these independent
  30 modules, and to copy and distribute the resulting executable under
  31 terms of your choice, provided that you also meet, for each linked
  32 independent module, the terms and conditions of the license of that
  33 module.  An independent module is a module which is not derived from
  34 or based on this library.  If you modify this library, you may extend
  35 this exception to your version of the library, but you are not
  36 obligated to do so.  If you do not wish to do so, delete this
  37 exception statement from your version. */
  38
  39
  40 package java.awt;
  41
  42 import java.util.Enumeration;
  43 import java.util.Hashtable;
  44 import java.io.Serializable;
  45
  46 /** This class implements a card-based layout scheme.  Each included
  47  * component is treated as a card.  Only one card can be shown at a
  48  * time.  This class includes methods for changing which card is
  49  * shown.
  50  *
  51  * @author Tom Tromey <tromey@redhat.com>
  52  * @author Aaron M. Renn (arenn@urbanophile.com)
  53  */
  54 public class CardLayout implements LayoutManager2, Serializable
  55 {
  56   static final long serialVersionUID = -4328196481005934313L;
  57
  58   /**
  59    * Initializes a new instance of <code>CardLayout</code> with horizontal
  60    * and vertical gaps of 0.
  61    */
  62   public CardLayout ()
  63   {
  64     this (0, 0);
  65   }
  66
  67   /**
  68    * Create a new <code>CardLayout</code> object with the specified
  69    * horizontal and vertical gaps.
  70    * @param hgap The horizontal gap
  71    * @param vgap The vertical gap
  72    */
  73   public CardLayout (int hgap, int vgap)
  74   {
  75     this.hgap = hgap;
  76     this.vgap = vgap;
  77     this.tab = new Hashtable ();
  78   }
  79
  80   /** Add a new component to the layout.  The constraint must be a
  81    * string which is used to name the component.  This string can
  82    * later be used to refer to the particular component.
  83    * @param comp The component to add
  84    * @param constraints The name by which the component can later be called
  85    * @exception IllegalArgumentException If `constraints' is not a
  86    * <code>String</code>
  87    */
  88   public void addLayoutComponent (Component comp, Object constraints)
  89   {
  90     if (! (constraints instanceof String))
  91       throw new IllegalArgumentException ("Object " + constraints
  92                                           + " is not a string");
  93     tab.put (constraints, comp);
  94   }
  95
  96   /** Add a new component to the layout.  The name can be used later
  97    * to refer to the component.
  98    * @param name The name by which the component can later be called
  99    * @param comp The component to add
 100    * @deprecated This method is deprecated in favor of
 101    * <code>addLayoutComponent(Component, Object)</code>.
 102    */
 103   public void addLayoutComponent (String name, Component comp)
 104   {
 105     addLayoutComponent (comp, name);
 106   }
 107
 108   /** Cause the first component in the container to be displayed.
 109    * @param parent The parent container
 110    */
 111   public void first (Container parent)
 112   {
 113     gotoComponent (parent, FIRST);
 114   }
 115
 116   /** Return this layout manager's horizontal gap.  */
 117   public int getHgap ()
 118   {
 119     return hgap;
 120   }
 121
 122   /** Return this layout manager's x alignment.  This method always
 123    * returns Component.CENTER_ALIGNMENT.
 124    * @param parent Container using this layout manager instance
 125    */
 126   public float getLayoutAlignmentX (Container parent)
 127   {
 128     return Component.CENTER_ALIGNMENT;
 129   }
 130
 131   /** Returns this layout manager's y alignment.  This method always
 132    * returns Component.CENTER_ALIGNMENT.
 133    * @param parent Container using this layout manager instance
 134    */
 135   public float getLayoutAlignmentY (Container parent)
 136   {
 137     return Component.CENTER_ALIGNMENT;
 138   }
 139
 140   /** Return this layout manager's vertical gap.  */
 141   public int getVgap ()
 142   {
 143     return vgap;
 144   }
 145
 146   /** Invalidate this layout manager's state.  */
 147   public void invalidateLayout (Container target)
 148   {
 149     // Do nothing.
 150   }
 151
 152   /** Cause the last component in the container to be displayed.
 153    * @param parent The parent container
 154    */
 155   public void last (Container parent)
 156   {
 157     gotoComponent (parent, LAST);
 158   }
 159
 160   /**
 161    * Lays out the container.  This is done by resizing the child components
 162    * to be the same size as the parent, less insets and gaps.
 163    *
 164    * @param parent The parent container.
 165    */
 166   public void layoutContainer (Container parent)
 167   {
 168     synchronized (parent.getTreeLock ())
 169       {
 170         int width = parent.width;
 171         int height = parent.height;
 172
 173         Insets ins = parent.getInsets ();
 174
 175         int num = parent.ncomponents;
 176         Component[] comps = parent.component;
 177
 178         int x = ins.left + hgap;
 179         int y = ins.top + vgap;
 180         width = width - 2 * hgap - ins.left - ins.right;
 181         height = height - 2 * vgap - ins.top - ins.bottom;
 182
 183         for (int i = 0; i < num; ++i)
 184           comps[i].setBounds (x, y, width, height);
 185       }
 186   }
 187
 188   /** Get the maximum layout size of the container.
 189    * @param target The parent container
 190    */
 191   public Dimension maximumLayoutSize (Container target)
 192   {
 193     // The JCL says that this returns Integer.MAX_VALUE for both
 194     // dimensions.  But that just seems wrong to me.
 195     return getSize (target, MAX);
 196   }
 197
 198   /** Get the minimum layout size of the container.
 199    * @param target The parent container
 200    */
 201   public Dimension minimumLayoutSize (Container target)
 202   {
 203     return getSize (target, MIN);
 204   }
 205
 206   /** Cause the next component in the container to be displayed.  If
 207    * this current card is the  last one in the deck, the first
 208    * component is displayed.
 209    * @param parent The parent container
 210    */
 211   public void next (Container parent)
 212   {
 213     gotoComponent (parent, NEXT);
 214   }
 215
 216   /** Get the preferred layout size of the container.
 217    * @param target The parent container
 218    */
 219   public Dimension preferredLayoutSize (Container parent)
 220   {
 221     return getSize (parent, PREF);
 222   }
 223
 224   /** Cause the previous component in the container to be displayed.
 225    * If this current card is the first one in the deck, the last
 226    * component is displayed.
 227    * @param parent The parent container
 228    */
 229   public void previous (Container parent)
 230   {
 231     gotoComponent (parent, PREV);
 232   }
 233
 234   /** Remove the indicated component from this layout manager.
 235    * @param comp The component to remove
 236    */
 237   public void removeLayoutComponent (Component comp)
 238   {
 239     Enumeration e = tab.keys ();
 240     while (e.hasMoreElements ())
 241       {
 242         Object key = e.nextElement ();
 243         if (tab.get (key) == comp)
 244           {
 245             tab.remove (key);
 246             break;
 247           }
 248       }
 249   }
 250
 251   /** Set this layout manager's horizontal gap.
 252    * @param hgap The new gap
 253    */
 254   public void setHgap (int hgap)
 255   {
 256     this.hgap = hgap;
 257   }
 258
 259   /** Set this layout manager's vertical gap.
 260    * @param vgap The new gap
 261    */
 262   public void setVgap (int vgap)
 263   {
 264     this.vgap = vgap;
 265   }
 266
 267   /** Cause the named component to be shown.  If the component name is
 268    * unknown, this method does nothing.
 269    * @param parent The parent container
 270    * @param name The name of the component to show
 271    */
 272   public void show (Container parent, String name)
 273   {
 274     Object target = tab.get (name);
 275     if (target != null)
 276       {
 277         int num = parent.ncomponents;
 278         // This is more efficient than calling getComponents().
 279         Component[] comps = parent.component;
 280         for (int i = 0; i < num; ++i)
 281           {
 282             if (comps[i].isVisible())
 283               {
 284                 if (target == comps[i])
 285                   return;
 286                 comps[i].setVisible (false);
 287               }
 288           }
 289         ((Component) target).setVisible (true);
 290       }
 291   }
 292
 293   /**
 294    * Returns a string representation of this layout manager.
 295    *
 296    * @return A string representation of this object.
 297    */
 298   public String toString ()
 299   {
 300     return getClass ().getName () + "[" + hgap + "," + vgap + "]";
 301   }
 302
 303   /** This implements first(), last(), next(), and previous().
 304    * @param parent The parent container
 305    * @param what The type of goto: FIRST, LAST, NEXT or PREV
 306    */
 307   private void gotoComponent (Container parent, int what)
 308   {
 309     synchronized (parent.getTreeLock ())
 310       {
 311         int num = parent.ncomponents;
 312         // This is more efficient than calling getComponents().
 313         Component[] comps = parent.component;
 314         int choice = -1;
 315
 316         if (what == FIRST)
 317           choice = 0;
 318         else if (what == LAST)
 319           choice = num - 1;
 320
 321         for (int i = 0; i < num; ++i)
 322           {
 323             if (comps[i].isVisible ())
 324               {
 325                 if (what == NEXT)
 326                   {
 327                     choice = i + 1;
 328                     if (choice == num)
 329                       choice = 0;
 330                   }
 331                 else if (what == PREV)
 332                   {
 333                     choice = i - 1;
 334                     if (choice < 0)
 335                       choice = num - 1;
 336                   }
 337                 else if (choice == i)
 338                   {
 339                     // Do nothing if we're already looking at the right
 340                     // component.
 341                     return;
 342                   }
 343                 comps[i].setVisible (false);
 344
 345                 if (choice >= 0)
 346                   break;
 347               }
 348           }
 349
 350         if (choice >= 0 && choice < num)
 351           comps[choice].setVisible (true);
 352       }
 353   }
 354
 355   // Compute the size according to WHAT.
 356   private Dimension getSize (Container parent, int what)
 357   {
 358     synchronized (parent.getTreeLock ())
 359       {
 360         int w = 0, h = 0, num = parent.ncomponents;
 361         Component[] comps = parent.component;
 362
 363         for (int i = 0; i < num; ++i)
 364           {
 365             Dimension d;
 366
 367             if (what == MIN)
 368               d = comps[i].getMinimumSize ();
 369             else if (what == MAX)
 370               d = comps[i].getMaximumSize ();
 371             else
 372               d = comps[i].getPreferredSize ();
 373
 374             w = Math.max (d.width, w);
 375             h = Math.max (d.height, h);
 376           }
 377
 378         Insets i = parent.getInsets ();
 379         w += 2 * hgap + i.right + i.left;
 380         h += 2 * vgap + i.bottom + i.top;
 381
 382         // Handle overflow.
 383         if (w < 0)
 384           w = Integer.MAX_VALUE;
 385         if (h < 0)
 386           h = Integer.MAX_VALUE;
 387
 388         return new Dimension (w, h);
 389       }
 390   }
 391
 392   /**
 393    * @serial Horizontal gap value.
 394    */
 395   private int hgap;
 396
 397   /**
 398    * @serial Vertical gap value.
 399    */
 400   private int vgap;
 401
 402   /**
 403    * @serial Table of named components.
 404    */
 405   private Hashtable tab;
 406
 407   // These constants are used by the private gotoComponent method.
 408   private int FIRST = 0;
 409   private int LAST = 1;
 410   private int NEXT = 2;
 411   private int PREV = 3;
 412
 413   // These constants are used by the private getSize method.
 414   private int MIN = 0;
 415   private int MAX = 1;
 416   private int PREF = 2;
 417 }