001/* BorderLayout.java -- A layout manager class
002   Copyright (C) 1999, 2002, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.awt;
040
041
042/**
043  * This class implements a layout manager that positions components
044  * in certain sectors of the parent container.
045  *
046  * @author Aaron M. Renn (arenn@urbanophile.com)
047  * @author Rolf W. Rasmussen  (rolfwr@ii.uib.no)
048  */
049public class BorderLayout implements LayoutManager2, java.io.Serializable
050{
051
052  /**
053   * Constant indicating the top of the container
054   */
055  public static final String NORTH = "North";
056
057  /**
058   * Constant indicating the bottom of the container
059   */
060  public static final String SOUTH = "South";
061
062  /**
063   * Constant indicating the right side of the container
064   */
065  public static final String EAST = "East";
066
067  /**
068   * Constant indicating the left side of the container
069   */
070  public static final String WEST = "West";
071
072  /**
073   * Constant indicating the center of the container
074   */
075  public static final String CENTER = "Center";
076
077
078  /**
079   * The constant indicating the position before the first line of the
080   * layout.  The exact position depends on the writing system: For a
081   * top-to-bottom orientation, it is the same as {@link #NORTH}, for
082   * a bottom-to-top orientation, it is the same as {@link #SOUTH}.
083   *
084   * <p>This constant is an older name for {@link #PAGE_START} which
085   * has exactly the same value.
086   *
087   * @since 1.2
088   */
089  public static final String BEFORE_FIRST_LINE = "First";
090
091  /**
092   * The constant indicating the position after the last line of the
093   * layout.  The exact position depends on the writing system: For a
094   * top-to-bottom orientation, it is the same as {@link #SOUTH}, for
095   * a bottom-to-top orientation, it is the same as {@link #NORTH}.
096   *
097   * <p>This constant is an older name for {@link #PAGE_END} which
098   * has exactly the same value.
099   *
100   * @since 1.2
101   */
102  public static final String AFTER_LAST_LINE = "Last";
103
104  /**
105   * The constant indicating the position before the first item of the
106   * layout.  The exact position depends on the writing system: For a
107   * left-to-right orientation, it is the same as {@link #WEST}, for
108   * a right-to-left orientation, it is the same as {@link #EAST}.
109   *
110   * <p>This constant is an older name for {@link #LINE_START} which
111   * has exactly the same value.
112   *
113   * @since 1.2
114   */
115  public static final String BEFORE_LINE_BEGINS = "Before";
116
117  /**
118   * The constant indicating the position after the last item of the
119   * layout.  The exact position depends on the writing system: For a
120   * left-to-right orientation, it is the same as {@link #EAST}, for
121   * a right-to-left orientation, it is the same as {@link #WEST}.
122   *
123   * <p>This constant is an older name for {@link #LINE_END} which
124   * has exactly the same value.
125   *
126   * @since 1.2
127   */
128  public static final String AFTER_LINE_ENDS = "After";
129
130  /**
131   * The constant indicating the position before the first line of the
132   * layout.  The exact position depends on the writing system: For a
133   * top-to-bottom orientation, it is the same as {@link #NORTH}, for
134   * a bottom-to-top orientation, it is the same as {@link #SOUTH}.
135   *
136   * @since 1.4
137   */
138  public static final String PAGE_START = BEFORE_FIRST_LINE;
139
140  /**
141   * The constant indicating the position after the last line of the
142   * layout.  The exact position depends on the writing system: For a
143   * top-to-bottom orientation, it is the same as {@link #SOUTH}, for
144   * a bottom-to-top orientation, it is the same as {@link #NORTH}.
145   *
146   * @since 1.4
147   */
148  public static final String PAGE_END = AFTER_LAST_LINE;
149
150  /**
151   * The constant indicating the position before the first item of the
152   * layout.  The exact position depends on the writing system: For a
153   * left-to-right orientation, it is the same as {@link #WEST}, for
154   * a right-to-left orientation, it is the same as {@link #EAST}.
155   *
156   * @since 1.4
157   */
158  public static final String LINE_START = BEFORE_LINE_BEGINS;
159
160  /**
161   * The constant indicating the position after the last item of the
162   * layout.  The exact position depends on the writing system: For a
163   * left-to-right orientation, it is the same as {@link #EAST}, for
164   * a right-to-left orientation, it is the same as {@link #WEST}.
165   *
166   * @since 1.4
167   */
168  public static final String LINE_END = AFTER_LINE_ENDS;
169
170
171  /**
172   * Serialization constant.
173   */
174  private static final long serialVersionUID = -8658291919501921765L;
175
176
177  /**
178   * @serial
179   */
180  private Component north;
181
182  /**
183   * @serial
184   */
185  private Component south;
186
187  /**
188   * @serial
189   */
190  private Component east;
191
192  /**
193   * @serial
194   */
195  private Component west;
196
197  /**
198   * @serial
199  */
200  private Component center;
201
202  /**
203   * @serial
204   */
205  private Component firstLine;
206
207  /**
208   * @serial
209   */
210  private Component lastLine;
211
212  /**
213   * @serial
214   */
215  private Component firstItem;
216
217  /**
218   * @serial
219   */
220  private Component lastItem;
221
222  /**
223   * @serial The horizontal gap between components
224   */
225  private int hgap;
226
227  /**
228   * @serial The vertical gap between components
229   */
230  private int vgap;
231
232
233  // Some constants for use with calcSize().
234  private static final int MIN = 0;
235  private static final int MAX = 1;
236  private static final int PREF = 2;
237
238
239  /**
240   * Initializes a new instance of <code>BorderLayout</code> with no
241   * horiztonal or vertical gaps between components.
242   */
243  public BorderLayout()
244  {
245    this(0,0);
246  }
247
248  /**
249   * Initializes a new instance of <code>BorderLayout</code> with the
250   * specified horiztonal and vertical gaps between components.
251   *
252   * @param hgap The horizontal gap between components.
253   * @param vgap The vertical gap between components.
254   */
255  public BorderLayout(int hgap, int vgap)
256  {
257    this.hgap = hgap;
258    this.vgap = vgap;
259  }
260
261  /**
262   * Returns the horitzontal gap value.
263   *
264   * @return The horitzontal gap value.
265   */
266  public int getHgap()
267  {
268    return(hgap);
269  }
270
271  /**
272   * Sets the horizontal gap to the specified value.
273   *
274   * @param hgap The new horizontal gap.
275   */
276  public void setHgap(int hgap)
277  {
278    this.hgap = hgap;
279  }
280
281  /**
282   * Returns the vertical gap value.
283   *
284   * @return The vertical gap value.
285   */
286  public int getVgap()
287  {
288    return(vgap);
289  }
290
291  /**
292   * Sets the vertical gap to the specified value.
293   *
294   * @param vgap The new vertical gap value.
295   */
296  public void setVgap(int vgap)
297  {
298    this.vgap = vgap;
299  }
300
301  /**
302   * Adds a component to the layout in the specified constraint position,
303   * which must be one of the string constants defined in this class.
304   *
305   * @param component The component to add.
306   * @param constraints The constraint string.
307   *
308   * @exception IllegalArgumentException If the constraint object is not
309   * a string, or is not one of the specified constants in this class.
310   */
311  public void addLayoutComponent(Component component, Object constraints)
312  {
313    if (constraints != null && ! (constraints instanceof String))
314      throw new IllegalArgumentException("Constraint must be a string");
315
316    addLayoutComponent((String) constraints, component);
317  }
318
319  /**
320   * Adds a component to the layout in the specified constraint position,
321   * which must be one of the string constants defined in this class.
322   *
323   * @param constraints The constraint string.
324   * @param component The component to add.
325   *
326   * @exception IllegalArgumentException If the constraint object is not
327   *            one of the specified constants in this class.
328   *
329   * @deprecated This method is deprecated in favor of
330   *             <code>addLayoutComponent(Component, Object)</code>.
331   */
332  public void addLayoutComponent(String constraints, Component component)
333  {
334    String str = constraints;
335
336    if (str == null || str.equals(CENTER))
337      center = component;
338    else if (str.equals(NORTH))
339      north = component;
340    else if (str.equals(SOUTH))
341      south = component;
342    else if (str.equals(EAST))
343      east = component;
344    else if (str.equals(WEST))
345      west = component;
346    else if (str.equals(BEFORE_FIRST_LINE))
347      firstLine = component;
348    else if (str.equals(AFTER_LAST_LINE))
349      lastLine = component;
350    else if (str.equals(BEFORE_LINE_BEGINS))
351      firstItem = component;
352    else if (str.equals(AFTER_LINE_ENDS))
353      lastItem = component;
354    else
355      throw new IllegalArgumentException("Constraint value not valid: " + str);
356  }
357
358  /**
359   * Removes the specified component from the layout.
360   *
361   * @param component The component to remove from the layout.
362   */
363  public void removeLayoutComponent(Component component)
364  {
365    if (north == component)
366      north = null;
367    if (south == component)
368      south = null;
369    if (east == component)
370      east = null;
371    if (west == component)
372      west = null;
373    if (center == component)
374      center = null;
375    if (firstItem == component)
376      firstItem = null;
377    if (lastItem == component)
378      lastItem = null;
379    if (firstLine == component)
380      firstLine = null;
381    if (lastLine == component)
382      lastLine = null;
383  }
384
385  /**
386   * Returns the minimum size of the specified container using this layout.
387   *
388   * @param target The container to calculate the minimum size for.
389   *
390   * @return The minimum size of the container
391   */
392  public Dimension minimumLayoutSize(Container target)
393  {
394    return calcSize(target, MIN);
395  }
396
397  /**
398   * Returns the preferred size of the specified container using this layout.
399   *
400   * @param target The container to calculate the preferred size for.
401   *
402   * @return The preferred size of the container
403   */
404  public Dimension preferredLayoutSize(Container target)
405  {
406    return calcSize(target, PREF);
407  }
408
409  /**
410   * Returns the maximum size of the specified container using this layout.
411   *
412   * @param target The container to calculate the maximum size for.
413   *
414   * @return The maximum size of the container
415   */
416  public Dimension maximumLayoutSize(Container target)
417  {
418    return new Dimension (Integer.MAX_VALUE, Integer.MAX_VALUE);
419  }
420
421  /**
422   * Returns the X axis alignment, which is a <code>float</code> indicating
423   * where along the X axis this container wishs to position its layout.
424   * 0 indicates align to the left, 1 indicates align to the right, and 0.5
425   * indicates align to the center.
426   *
427   * @param parent The parent container.
428   *
429   * @return The X alignment value.
430   */
431  public float getLayoutAlignmentX(Container parent)
432  {
433    return 0.5F;
434  }
435
436  /**
437   * Returns the Y axis alignment, which is a <code>float</code> indicating
438   * where along the Y axis this container wishs to position its layout.
439   * 0 indicates align to the top, 1 indicates align to the bottom, and 0.5
440   * indicates align to the center.
441   *
442   * @param parent The parent container.
443   *
444   * @return The Y alignment value.
445   */
446  public float getLayoutAlignmentY(Container parent)
447  {
448    return 0.5F;
449  }
450
451  /**
452   * Instructs this object to discard any layout information it might
453   * have cached.
454   *
455   * @param parent The parent container.
456   */
457  public void invalidateLayout(Container parent)
458  {
459    // Nothing to do here.
460  }
461
462  /**
463   * Lays out the specified container according to the constraints in this
464   * object.
465   *
466   * @param target The container to lay out.
467   */
468  public void layoutContainer(Container target)
469  {
470    synchronized (target.getTreeLock())
471      {
472        Insets i = target.getInsets();
473        int top = i.top;
474        int bottom = target.height - i.bottom;
475        int left = i.left;
476        int right = target.width - i.right;
477
478        boolean left_to_right = target.getComponentOrientation().isLeftToRight();
479
480        Component my_north = north;
481        Component my_east = east;
482        Component my_south = south;
483        Component my_west = west;
484
485        // Note that we currently don't handle vertical layouts.
486        // Neither does JDK 1.3.
487        if (firstLine != null)
488          my_north = firstLine;
489        if (lastLine != null)
490          my_south = lastLine;
491        if (firstItem != null)
492          {
493            if (left_to_right)
494              my_west = firstItem;
495            else
496              my_east = firstItem;
497          }
498        if (lastItem != null)
499          {
500            if (left_to_right)
501              my_east = lastItem;
502            else
503              my_west = lastItem;
504          }
505
506        if (my_north != null)
507          {
508            Dimension n = calcCompSize(my_north, PREF);
509            my_north.setBounds(left, top, right - left, n.height);
510            top += n.height + vgap;
511          }
512
513        if (my_south != null)
514          {
515            Dimension s = calcCompSize(my_south, PREF);
516            my_south.setBounds(left, bottom - s.height, right - left, s.height);
517            bottom -= s.height + vgap;
518          }
519
520        if (my_east != null)
521          {
522            Dimension e = calcCompSize(my_east, PREF);
523            my_east.setBounds(right - e.width, top, e.width, bottom - top);
524            right -= e.width + hgap;
525          }
526
527        if (my_west != null)
528          {
529            Dimension w = calcCompSize(my_west, PREF);
530            my_west.setBounds(left, top, w.width, bottom - top);
531            left += w.width + hgap;
532          }
533
534        if (center != null)
535          center.setBounds(left, top, right - left, bottom - top);
536      }
537  }
538
539  /**
540   * Returns a string representation of this layout manager.
541   *
542   * @return A string representation of this object.
543   */
544  public String toString()
545  {
546    return getClass().getName() + "[hgap=" + hgap + ",vgap=" + vgap + "]";
547  }
548
549  private Dimension calcCompSize(Component comp, int what)
550  {
551    if (comp == null || ! comp.isVisible())
552      return new Dimension(0, 0);
553    if (what == MIN)
554      return comp.getMinimumSize();
555    else if (what == MAX)
556      return comp.getMaximumSize();
557    return comp.getPreferredSize();
558  }
559
560  /**
561   * This is a helper function used to compute the various sizes for this
562   * layout.
563   */
564  private Dimension calcSize(Container target, int what)
565  {
566    synchronized (target.getTreeLock())
567      {
568        Insets ins = target.getInsets();
569
570        ComponentOrientation orient = target.getComponentOrientation ();
571        boolean left_to_right = orient.isLeftToRight ();
572
573        Component my_north = north;
574        Component my_east = east;
575        Component my_south = south;
576        Component my_west = west;
577
578        // Note that we currently don't handle vertical layouts.  Neither
579        // does JDK 1.3.
580        if (firstLine != null)
581          my_north = firstLine;
582        if (lastLine != null)
583          my_south = lastLine;
584        if (firstItem != null)
585          {
586            if (left_to_right)
587              my_west = firstItem;
588            else
589              my_east = firstItem;
590          }
591        if (lastItem != null)
592          {
593            if (left_to_right)
594              my_east = lastItem;
595            else
596              my_west = lastItem;
597          }
598
599        Dimension ndim = calcCompSize(my_north, what);
600        Dimension sdim = calcCompSize(my_south, what);
601        Dimension edim = calcCompSize(my_east, what);
602        Dimension wdim = calcCompSize(my_west, what);
603        Dimension cdim = calcCompSize(center, what);
604
605        int width = edim.width + cdim.width + wdim.width + (hgap * 2);
606        // Check for overflow.
607        if (width < edim.width || width < cdim.width || width < cdim.width)
608          width = Integer.MAX_VALUE;
609
610        if (ndim.width > width)
611          width = ndim.width;
612        if (sdim.width > width)
613          width = sdim.width;
614
615        width += (ins.left + ins.right);
616
617        int height = edim.height;
618        if (cdim.height > height)
619          height = cdim.height;
620        if (wdim.height > height)
621          height = wdim.height;
622
623        int addedHeight = height + (ndim.height + sdim.height + (vgap * 2)
624                                    + ins.top + ins.bottom);
625        // Check for overflow.
626        if (addedHeight < height)
627          height = Integer.MAX_VALUE;
628        else
629          height = addedHeight;
630
631        return(new Dimension(width, height));
632      }
633  }
634
635  /**
636   * Return the component at the indicated location, or null if no component
637   * is at that location.  The constraints argument must be one of the
638   * location constants specified by this class.
639   * @param constraints the location
640   * @return the component at that location, or null
641   * @throws IllegalArgumentException if the constraints argument is not
642   * recognized
643   * @since 1.5
644   */
645  public Component getLayoutComponent(Object constraints)
646  {
647    if (constraints == CENTER)
648      return center;
649    if (constraints == NORTH)
650      return north;
651    if (constraints == EAST)
652      return east;
653    if (constraints == SOUTH)
654      return south;
655    if (constraints == WEST)
656      return west;
657    if (constraints == PAGE_START)
658      return firstLine;
659    if (constraints == PAGE_END)
660      return lastLine;
661    if (constraints == LINE_START)
662      return firstItem;
663    if (constraints == LINE_END)
664      return lastItem;
665    throw new IllegalArgumentException("constraint " + constraints
666                                       + " is not recognized");
667  }
668
669  /**
670   * Return the component at the specified location, which must be one
671   * of the absolute constants such as CENTER or SOUTH.  The container's
672   * orientation is used to map this location to the correct corresponding
673   * component, so for instance in a right-to-left container, a request
674   * for the EAST component could return the LINE_END component.  This will
675   * return null if no component is available at the given location.
676   * @param container the container whose orientation is used
677   * @param constraints the absolute location of the component
678   * @return the component at the location, or null
679   * @throws IllegalArgumentException if the constraint is not recognized
680   */
681  public Component getLayoutComponent(Container container, Object constraints)
682  {
683    ComponentOrientation orient = container.getComponentOrientation();
684    if (constraints == CENTER)
685      return center;
686    // Note that we don't support vertical layouts.
687    if (constraints == NORTH)
688      return north;
689    if (constraints == SOUTH)
690      return south;
691    if (constraints == WEST)
692      {
693        // Note that relative layout takes precedence.
694        if (orient.isLeftToRight())
695          return firstItem == null ? west : firstItem;
696        return lastItem == null ? west : lastItem;
697      }
698    if (constraints == EAST)
699      {
700        // Note that relative layout takes precedence.
701        if (orient.isLeftToRight())
702          return lastItem == null ? east : lastItem;
703        return firstItem == null ? east : firstItem;
704      }
705    throw new IllegalArgumentException("constraint " + constraints
706                                       + " is not recognized");
707  }
708
709  /**
710   * Return the constraint corresponding to a component in this layout.
711   * If the component is null, or is not in this layout, returns null.
712   * Otherwise, this will return one of the constraint constants defined
713   * in this class.
714   * @param c the component
715   * @return the constraint, or null
716   * @since 1.5
717   */
718  public Object getConstraints(Component c)
719  {
720    if (c == null)
721      return null;
722    if (c == center)
723      return CENTER;
724    if (c == north)
725      return NORTH;
726    if (c == east)
727      return EAST;
728    if (c == south)
729      return SOUTH;
730    if (c == west)
731      return WEST;
732    if (c == firstLine)
733      return PAGE_START;
734    if (c == lastLine)
735      return PAGE_END;
736    if (c == firstItem)
737      return LINE_START;
738    if (c == lastItem)
739      return LINE_END;
740    return null;
741  }
742}