Source for java.awt.CardLayout

   1: /* CardLayout.java -- Card-based layout engine
   2:    Copyright (C) 1999, 2000, 2002, 2003, 2004  Free Software Foundation
   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 java.awt;
  40: 
  41: import java.io.Serializable;
  42: import java.util.Enumeration;
  43: import java.util.Hashtable;
  44: 
  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:   private 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:    *
  71:    * @param hgap The horizontal gap
  72:    * @param vgap The vertical gap
  73:    */
  74:   public CardLayout (int hgap, int vgap)
  75:   {
  76:     this.hgap = hgap;
  77:     this.vgap = vgap;
  78:     this.tab = new Hashtable ();
  79:   }
  80: 
  81:   /**
  82:    * Add a new component to the layout.  The constraint must be a
  83:    * string which is used to name the component.  This string can
  84:    * later be used to refer to the particular component.
  85:    *
  86:    * @param comp The component to add
  87:    * @param constraints The name by which the component can later be called
  88:    *
  89:    * @exception IllegalArgumentException If `constraints' is not a
  90:    * <code>String</code>
  91:    */
  92:   public void addLayoutComponent (Component comp, Object constraints)
  93:   {
  94:     if (! (constraints instanceof String))
  95:       throw new IllegalArgumentException ("Object " + constraints
  96:                                           + " is not a string");
  97:     addLayoutComponent ((String) constraints, comp);
  98:   }
  99: 
 100:   /**
 101:    * Add a new component to the layout.  The name can be used later
 102:    * to refer to the component.
 103:    *
 104:    * @param name The name by which the component can later be called
 105:    * @param comp The component to add
 106:    *
 107:    * @deprecated This method is deprecated in favor of
 108:    * <code>addLayoutComponent(Component, Object)</code>.
 109:    */
 110:   public void addLayoutComponent (String name, Component comp)
 111:   {
 112:     tab.put (name, comp);
 113:     // First component added is the default component.
 114:     comp.setVisible(tab.size() == 1);
 115:   }
 116: 
 117:   /**
 118:    * Cause the first component in the container to be displayed.
 119:    *
 120:    * @param parent The parent container, not <code>null</code>.
 121:    */
 122:   public void first (Container parent)
 123:   {
 124:     gotoComponent (parent, FIRST);
 125:   }
 126: 
 127:   /**
 128:    * Return this layout manager's horizontal gap.
 129:    *
 130:    * @return the horizontal gap
 131:    */
 132:   public int getHgap ()
 133:   {
 134:     return hgap;
 135:   }
 136: 
 137:   /**
 138:    * Return this layout manager's x alignment.  This method always
 139:    * returns Component.CENTER_ALIGNMENT.
 140:    *
 141:    * @param parent Container using this layout manager instance
 142:    *
 143:    * @return the x-axis alignment
 144:    */
 145:   public float getLayoutAlignmentX (Container parent)
 146:   {
 147:     return Component.CENTER_ALIGNMENT;
 148:   }
 149: 
 150:   /**
 151:    * Returns this layout manager's y alignment.  This method always
 152:    * returns Component.CENTER_ALIGNMENT.
 153:    *
 154:    * @param parent Container using this layout manager instance
 155:    *
 156:    * @return the y-axis alignment
 157:    */
 158:   public float getLayoutAlignmentY (Container parent)
 159:   {
 160:     return Component.CENTER_ALIGNMENT;
 161:   }
 162: 
 163:   /**
 164:    * Return this layout manager's vertical gap.
 165:    *
 166:    * @return the vertical gap
 167:    */
 168:   public int getVgap ()
 169:   {
 170:     return vgap;
 171:   }
 172: 
 173:   /**
 174:    * Invalidate this layout manager's state.
 175:    */
 176:   public void invalidateLayout (Container target)
 177:   {
 178:     // Do nothing.
 179:   }
 180: 
 181:   /**
 182:    * Cause the last component in the container to be displayed.
 183:    *
 184:    * @param parent The parent container, not <code>null</code>.
 185:    */
 186:   public void last (Container parent)
 187:   {
 188:     gotoComponent (parent, LAST);
 189:   }
 190: 
 191:   /**
 192:    * Lays out the container.  This is done by resizing the child components
 193:    * to be the same size as the parent, less insets and gaps.
 194:    *
 195:    * @param parent The parent container.
 196:    */
 197:   public void layoutContainer (Container parent)
 198:   {
 199:     synchronized (parent.getTreeLock ())
 200:       {
 201:         int width = parent.width;
 202:         int height = parent.height;
 203: 
 204:         Insets ins = parent.getInsets ();
 205: 
 206:         int num = parent.ncomponents;
 207:         Component[] comps = parent.component;
 208: 
 209:         int x = ins.left + hgap;
 210:         int y = ins.top + vgap;
 211:         width = width - 2 * hgap - ins.left - ins.right;
 212:         height = height - 2 * vgap - ins.top - ins.bottom;
 213: 
 214:         for (int i = 0; i < num; ++i)
 215:           comps[i].setBounds (x, y, width, height);
 216:       }
 217:   }
 218: 
 219:   /**
 220:    * Get the maximum layout size of the container.
 221:    *
 222:    * @param target The parent container
 223:    *
 224:    * @return the maximum layout size
 225:    */
 226:   public Dimension maximumLayoutSize (Container target)
 227:   {
 228:     if (target == null || target.ncomponents == 0)
 229:       return new Dimension(Integer.MAX_VALUE, Integer.MAX_VALUE);
 230:     // The JCL says that this returns Integer.MAX_VALUE for both
 231:     // dimensions.  But that just seems wrong to me.
 232:     return getSize (target, MAX);
 233:   }
 234: 
 235:   /**
 236:    * Get the minimum layout size of the container.
 237:    *
 238:    * @param target The parent container
 239:    *
 240:    * @return the minimum layout size
 241:    */
 242:   public Dimension minimumLayoutSize (Container target)
 243:   {
 244:     return getSize (target, MIN);
 245:   }
 246: 
 247:   /**
 248:    * Cause the next component in the container to be displayed.  If
 249:    * this current card is the  last one in the deck, the first
 250:    * component is displayed.
 251:    *
 252:    * @param parent The parent container, not <code>null</code>.
 253:    */
 254:   public void next (Container parent)
 255:   {
 256:     gotoComponent (parent, NEXT);
 257:   }
 258: 
 259:   /**
 260:    * Get the preferred layout size of the container.
 261:    *
 262:    * @param parent The parent container
 263:    *
 264:    * @return the preferred layout size
 265:    */
 266:   public Dimension preferredLayoutSize (Container parent)
 267:   {
 268:     return getSize (parent, PREF);
 269:   }
 270: 
 271:   /**
 272:    * Cause the previous component in the container to be displayed.
 273:    * If this current card is the first one in the deck, the last
 274:    * component is displayed.
 275:    *
 276:    * @param parent The parent container, not <code>null</code>.
 277:    */
 278:   public void previous (Container parent)
 279:   {
 280:     gotoComponent (parent, PREV);
 281:   }
 282: 
 283:   /**
 284:    * Remove the indicated component from this layout manager.
 285:    *
 286:    * @param comp The component to remove
 287:    */
 288:   public void removeLayoutComponent (Component comp)
 289:   {
 290:     Enumeration e = tab.keys ();
 291:     while (e.hasMoreElements ())
 292:       {
 293:         Object key = e.nextElement ();
 294:         if (tab.get (key) == comp)
 295:           {
 296:             tab.remove (key);
 297:             Container parent = comp.getParent();
 298:             next(parent);
 299:             break;
 300:           }
 301:       }
 302:   }
 303: 
 304:   /**
 305:    * Set this layout manager's horizontal gap.
 306:    *
 307:    * @param hgap The new gap
 308:    */
 309:   public void setHgap (int hgap)
 310:   {
 311:     this.hgap = hgap;
 312:   }
 313: 
 314:   /**
 315:    * Set this layout manager's vertical gap.
 316:    *
 317:    * @param vgap The new gap
 318:    */
 319:   public void setVgap (int vgap)
 320:   {
 321:     this.vgap = vgap;
 322:   }
 323: 
 324:   /**
 325:    * Cause the named component to be shown.  If the component name is
 326:    * unknown or <code>null</code>, this method does nothing.
 327:    *
 328:    * @param parent The parent container, not <code>null</code>.
 329:    * @param name The name of the component to show
 330:    */
 331:   public void show (Container parent, String name)
 332:   {
 333:     if (name == null)
 334:       return;
 335: 
 336:     if (parent.getLayout() != this)
 337:       throw new IllegalArgumentException("parent's layout is not this CardLayout");
 338: 
 339:     Object target = tab.get (name);
 340:     if (target != null)
 341:       {
 342:         int num = parent.ncomponents;
 343:         // This is more efficient than calling getComponents().
 344:         Component[] comps = parent.component;
 345:         for (int i = 0; i < num; ++i)
 346:           {
 347:             if (comps[i].isVisible())
 348:               {
 349:                 if (target == comps[i])
 350:                   return;
 351:                 comps[i].setVisible (false);
 352:               }
 353:           }
 354:         ((Component) target).setVisible (true);
 355:         parent.validate();
 356:       }
 357:   }
 358: 
 359:   /**
 360:    * Returns a string representation of this layout manager.
 361:    *
 362:    * @return A string representation of this object.
 363:    */
 364:   public String toString ()
 365:   {
 366:     return getClass ().getName () + "[hgap=" + hgap + ",vgap=" + vgap + "]";
 367:   }
 368: 
 369:   /**
 370:    * This implements first(), last(), next(), and previous().
 371:    *
 372:    * @param parent The parent container
 373:    * @param what The type of goto: FIRST, LAST, NEXT or PREV
 374:    *
 375:    * @throws IllegalArgumentException if parent has not this
 376:    * CardLayout set as its layout.
 377:    */
 378:   private void gotoComponent (Container parent, int what)
 379:   {
 380:     if (parent.getLayout() != this)
 381:       throw new IllegalArgumentException("parent's layout is not this CardLayout");
 382: 
 383:     synchronized (parent.getTreeLock ())
 384:       {
 385:         int num = parent.ncomponents;
 386:         // This is more efficient than calling getComponents().
 387:         Component[] comps = parent.component;
 388: 
 389:         if (num == 1)
 390:           {
 391:             comps[0].setVisible(true);
 392:             return;
 393:           }
 394: 
 395:         int choice = -1;
 396: 
 397:         if (what == FIRST)
 398:           choice = 0;
 399:         else if (what == LAST)
 400:           choice = num - 1;
 401: 
 402:         for (int i = 0; i < num; ++i)
 403:           {
 404:             if (comps[i].isVisible ())
 405:               {
 406:                 if (choice == i)
 407:                   {
 408:                     // Do nothing if we're already looking at the right
 409:                     // component.
 410:                     return;
 411:                   }
 412:                 else if (what == PREV)
 413:                   {
 414:                     choice = i - 1;
 415:                     if (choice < 0)
 416:                       choice = num - 1;
 417:                   }
 418:                 else if (what == NEXT)
 419:                   {
 420:                     choice = i + 1;
 421:                     if (choice == num)
 422:                       choice = 0;
 423:                   }
 424:                 comps[i].setVisible (false);
 425: 
 426:                 if (choice >= 0)
 427:                   break;
 428:               } else
 429:                 {
 430:                   comps[i].setVisible(true);
 431:                 }
 432:           }
 433: 
 434:         if (choice >= 0 && choice < num)
 435:           comps[choice].setVisible (true);
 436:       }
 437:   }
 438: 
 439:   // Compute the size according to WHAT.
 440:   private Dimension getSize (Container parent, int what)
 441:   {
 442:     synchronized (parent.getTreeLock ())
 443:       {
 444:         int w = 0, h = 0, num = parent.ncomponents;
 445:         Component[] comps = parent.component;
 446: 
 447:         for (int i = 0; i < num; ++i)
 448:           {
 449:             Dimension d;
 450: 
 451:             if (what == MIN)
 452:               d = comps[i].getMinimumSize ();
 453:             else if (what == MAX)
 454:               d = comps[i].getMaximumSize ();
 455:             else
 456:               d = comps[i].getPreferredSize ();
 457: 
 458:             w = Math.max (d.width, w);
 459:             h = Math.max (d.height, h);
 460:           }
 461: 
 462:         Insets i = parent.getInsets ();
 463:         w += 2 * hgap + i.right + i.left;
 464:         h += 2 * vgap + i.bottom + i.top;
 465: 
 466:         // Handle overflow.
 467:         if (w < 0)
 468:           w = Integer.MAX_VALUE;
 469:         if (h < 0)
 470:           h = Integer.MAX_VALUE;
 471: 
 472:         return new Dimension (w, h);
 473:       }
 474:   }
 475: 
 476:   /**
 477:    * @serial Horizontal gap value.
 478:    */
 479:   private int hgap;
 480: 
 481:   /**
 482:    * @serial Vertical gap value.
 483:    */
 484:   private int vgap;
 485: 
 486:   /**
 487:    * @serial Table of named components.
 488:    */
 489:   private Hashtable tab;
 490: 
 491:   // These constants are used by the private gotoComponent method.
 492:   private static final int FIRST = 0;
 493:   private static final int LAST = 1;
 494:   private static final int NEXT = 2;
 495:   private static final int PREV = 3;
 496: 
 497:   // These constants are used by the private getSize method.
 498:   private static final int MIN = 0;
 499:   private static final int MAX = 1;
 500:   private static final int PREF = 2;
 501: }