View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  package javax.swing;
26  
27  
28  import java.awt.*;
29  import java.beans.ConstructorProperties;
30  import java.io.Serializable;
31  
32  /**
33   * A layout manager to arrange components over the top
34   * of each other.  The requested size of the container
35   * will be the largest requested size of the children,
36   * taking alignment needs into consideration.
37   *
38   * The alignment is based upon what is needed to properly
39   * fit the children in the allocation area.  The children
40   * will be placed such that their alignment points are all
41   * on top of each other.
42   * <p>
43   * <strong>Warning:</strong>
44   * Serialized objects of this class will not be compatible with
45   * future Swing releases. The current serialization support is
46   * appropriate for short term storage or RMI between applications running
47   * the same version of Swing.  As of 1.4, support for long term storage
48   * of all JavaBeans&trade;
49   * has been added to the <code>java.beans</code> package.
50   * Please see {@link java.beans.XMLEncoder}.
51   *
52   * @author   Timothy Prinzing
53   */
54  public class OverlayLayout implements LayoutManager2,Serializable {
55  
56      /**
57       * Constructs a layout manager that performs overlay
58       * arrangement of the children.  The layout manager
59       * created is dedicated to the given container.
60       *
61       * @param target  the container to do layout against
62       */
63      @ConstructorProperties({"target"})
64      public OverlayLayout(Container target) {
65          this.target = target;
66      }
67  
68      /**
69       * Returns the container that uses this layout manager.
70       *
71       * @return the container that uses this layout manager
72       *
73       * @since 1.6
74       */
75      public final Container getTarget() {
76          return this.target;
77      }
78  
79      /**
80       * Indicates a child has changed its layout related information,
81       * which causes any cached calculations to be flushed.
82       *
83       * @param target the container
84       */
85      public void invalidateLayout(Container target) {
86          checkContainer(target);
87          xChildren = null;
88          yChildren = null;
89          xTotal = null;
90          yTotal = null;
91      }
92  
93      /**
94       * Adds the specified component to the layout. Used by
95       * this class to know when to invalidate layout.
96       *
97       * @param name the name of the component
98       * @param comp the the component to be added
99       */
100     public void addLayoutComponent(String name, Component comp) {
101         invalidateLayout(comp.getParent());
102     }
103 
104     /**
105      * Removes the specified component from the layout. Used by
106      * this class to know when to invalidate layout.
107      *
108      * @param comp the component to remove
109      */
110     public void removeLayoutComponent(Component comp) {
111         invalidateLayout(comp.getParent());
112     }
113 
114     /**
115      * Adds the specified component to the layout, using the specified
116      * constraint object. Used by this class to know when to invalidate
117      * layout.
118      *
119      * @param comp the component to be added
120      * @param constraints  where/how the component is added to the layout.
121      */
122     public void addLayoutComponent(Component comp, Object constraints) {
123         invalidateLayout(comp.getParent());
124     }
125 
126     /**
127      * Returns the preferred dimensions for this layout given the components
128      * in the specified target container.  Recomputes the layout if it
129      * has been invalidated.  Factors in the current inset setting returned
130      * by getInsets().
131      *
132      * @param target the component which needs to be laid out
133      * @return a Dimension object containing the preferred dimensions
134      * @see #minimumLayoutSize
135      */
136     public Dimension preferredLayoutSize(Container target) {
137         checkContainer(target);
138         checkRequests();
139 
140         Dimension size = new Dimension(xTotal.preferred, yTotal.preferred);
141         Insets insets = target.getInsets();
142         size.width += insets.left + insets.right;
143         size.height += insets.top + insets.bottom;
144         return size;
145     }
146 
147     /**
148      * Returns the minimum dimensions needed to lay out the components
149      * contained in the specified target container.  Recomputes the layout
150      * if it has been invalidated, and factors in the current inset setting.
151      *
152      * @param target the component which needs to be laid out
153      * @return a Dimension object containing the minimum dimensions
154      * @see #preferredLayoutSize
155      */
156     public Dimension minimumLayoutSize(Container target) {
157         checkContainer(target);
158         checkRequests();
159 
160         Dimension size = new Dimension(xTotal.minimum, yTotal.minimum);
161         Insets insets = target.getInsets();
162         size.width += insets.left + insets.right;
163         size.height += insets.top + insets.bottom;
164         return size;
165     }
166 
167     /**
168      * Returns the maximum dimensions needed to lay out the components
169      * contained in the specified target container.  Recomputes the
170      * layout if it has been invalidated, and factors in the inset setting
171      * returned by <code>getInset</code>.
172      *
173      * @param target the component that needs to be laid out
174      * @return a <code>Dimension</code> object containing the maximum
175      *         dimensions
176      * @see #preferredLayoutSize
177      */
178     public Dimension maximumLayoutSize(Container target) {
179         checkContainer(target);
180         checkRequests();
181 
182         Dimension size = new Dimension(xTotal.maximum, yTotal.maximum);
183         Insets insets = target.getInsets();
184         size.width += insets.left + insets.right;
185         size.height += insets.top + insets.bottom;
186         return size;
187     }
188 
189     /**
190      * Returns the alignment along the x axis for the container.
191      *
192      * @param target the container
193      * @return the alignment &gt;= 0.0f &amp;&amp; &lt;= 1.0f
194      */
195     public float getLayoutAlignmentX(Container target) {
196         checkContainer(target);
197         checkRequests();
198         return xTotal.alignment;
199     }
200 
201     /**
202      * Returns the alignment along the y axis for the container.
203      *
204      * @param target the container
205      * @return the alignment &gt;= 0.0f &amp;&amp; &lt;= 1.0f
206      */
207     public float getLayoutAlignmentY(Container target) {
208         checkContainer(target);
209         checkRequests();
210         return yTotal.alignment;
211     }
212 
213     /**
214      * Called by the AWT when the specified container needs to be laid out.
215      *
216      * @param target  the container to lay out
217      *
218      * @exception AWTError  if the target isn't the container specified to the
219      *                      constructor
220      */
221     public void layoutContainer(Container target) {
222         checkContainer(target);
223         checkRequests();
224 
225         int nChildren = target.getComponentCount();
226         int[] xOffsets = new int[nChildren];
227         int[] xSpans = new int[nChildren];
228         int[] yOffsets = new int[nChildren];
229         int[] ySpans = new int[nChildren];
230 
231         // determine the child placements
232         Dimension alloc = target.getSize();
233         Insets in = target.getInsets();
234         alloc.width -= in.left + in.right;
235         alloc.height -= in.top + in.bottom;
236         SizeRequirements.calculateAlignedPositions(alloc.width, xTotal,
237                                                    xChildren, xOffsets,
238                                                    xSpans);
239         SizeRequirements.calculateAlignedPositions(alloc.height, yTotal,
240                                                    yChildren, yOffsets,
241                                                    ySpans);
242 
243         // flush changes to the container
244         for (int i = 0; i < nChildren; i++) {
245             Component c = target.getComponent(i);
246             c.setBounds(in.left + xOffsets[i], in.top + yOffsets[i],
247                         xSpans[i], ySpans[i]);
248         }
249     }
250 
251     void checkContainer(Container target) {
252         if (this.target != target) {
253             throw new AWTError("OverlayLayout can't be shared");
254         }
255     }
256 
257     void checkRequests() {
258         if (xChildren == null || yChildren == null) {
259             // The requests have been invalidated... recalculate
260             // the request information.
261             int n = target.getComponentCount();
262             xChildren = new SizeRequirements[n];
263             yChildren = new SizeRequirements[n];
264             for (int i = 0; i < n; i++) {
265                 Component c = target.getComponent(i);
266                 Dimension min = c.getMinimumSize();
267                 Dimension typ = c.getPreferredSize();
268                 Dimension max = c.getMaximumSize();
269                 xChildren[i] = new SizeRequirements(min.width, typ.width,
270                                                     max.width,
271                                                     c.getAlignmentX());
272                 yChildren[i] = new SizeRequirements(min.height, typ.height,
273                                                     max.height,
274                                                     c.getAlignmentY());
275             }
276 
277             xTotal = SizeRequirements.getAlignedSizeRequirements(xChildren);
278             yTotal = SizeRequirements.getAlignedSizeRequirements(yChildren);
279         }
280     }
281 
282     private Container target;
283     private SizeRequirements[] xChildren;
284     private SizeRequirements[] yChildren;
285     private SizeRequirements xTotal;
286     private SizeRequirements yTotal;
287 
288 }