View Javadoc
1   /*
2    * Copyright (c) 1995, 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 java.awt;
26  
27  /**
28   * The <code>GridBagConstraints</code> class specifies constraints
29   * for components that are laid out using the
30   * <code>GridBagLayout</code> class.
31   *
32   * @author Doug Stein
33   * @author Bill Spitzak (orignial NeWS &amp; OLIT implementation)
34   * @see java.awt.GridBagLayout
35   * @since JDK1.0
36   */
37  public class GridBagConstraints implements Cloneable, java.io.Serializable {
38  
39      /**
40       * Specifies that this component is the next-to-last component in its
41       * column or row (<code>gridwidth</code>, <code>gridheight</code>),
42       * or that this component be placed next to the previously added
43       * component (<code>gridx</code>, <code>gridy</code>).
44       * @see      java.awt.GridBagConstraints#gridwidth
45       * @see      java.awt.GridBagConstraints#gridheight
46       * @see      java.awt.GridBagConstraints#gridx
47       * @see      java.awt.GridBagConstraints#gridy
48       */
49      public static final int RELATIVE = -1;
50  
51      /**
52       * Specifies that this component is the
53       * last component in its column or row.
54       */
55      public static final int REMAINDER = 0;
56  
57      /**
58       * Do not resize the component.
59       */
60      public static final int NONE = 0;
61  
62      /**
63       * Resize the component both horizontally and vertically.
64       */
65      public static final int BOTH = 1;
66  
67      /**
68       * Resize the component horizontally but not vertically.
69       */
70      public static final int HORIZONTAL = 2;
71  
72      /**
73       * Resize the component vertically but not horizontally.
74       */
75      public static final int VERTICAL = 3;
76  
77      /**
78       * Put the component in the center of its display area.
79       */
80      public static final int CENTER = 10;
81  
82      /**
83       * Put the component at the top of its display area,
84       * centered horizontally.
85       */
86      public static final int NORTH = 11;
87  
88      /**
89       * Put the component at the top-right corner of its display area.
90       */
91      public static final int NORTHEAST = 12;
92  
93      /**
94       * Put the component on the right side of its display area,
95       * centered vertically.
96       */
97      public static final int EAST = 13;
98  
99      /**
100      * Put the component at the bottom-right corner of its display area.
101      */
102     public static final int SOUTHEAST = 14;
103 
104     /**
105      * Put the component at the bottom of its display area, centered
106      * horizontally.
107      */
108     public static final int SOUTH = 15;
109 
110     /**
111      * Put the component at the bottom-left corner of its display area.
112      */
113     public static final int SOUTHWEST = 16;
114 
115     /**
116      * Put the component on the left side of its display area,
117      * centered vertically.
118      */
119     public static final int WEST = 17;
120 
121     /**
122      * Put the component at the top-left corner of its display area.
123      */
124     public static final int NORTHWEST = 18;
125 
126     /**
127      * Place the component centered along the edge of its display area
128      * associated with the start of a page for the current
129      * {@code ComponentOrientation}.  Equal to NORTH for horizontal
130      * orientations.
131      */
132     public static final int PAGE_START = 19;
133 
134     /**
135      * Place the component centered along the edge of its display area
136      * associated with the end of a page for the current
137      * {@code ComponentOrientation}.  Equal to SOUTH for horizontal
138      * orientations.
139      */
140     public static final int PAGE_END = 20;
141 
142     /**
143      * Place the component centered along the edge of its display area where
144      * lines of text would normally begin for the current
145      * {@code ComponentOrientation}.  Equal to WEST for horizontal,
146      * left-to-right orientations and EAST for horizontal, right-to-left
147      * orientations.
148      */
149     public static final int LINE_START = 21;
150 
151     /**
152      * Place the component centered along the edge of its display area where
153      * lines of text would normally end for the current
154      * {@code ComponentOrientation}.  Equal to EAST for horizontal,
155      * left-to-right orientations and WEST for horizontal, right-to-left
156      * orientations.
157      */
158     public static final int LINE_END = 22;
159 
160     /**
161      * Place the component in the corner of its display area where
162      * the first line of text on a page would normally begin for the current
163      * {@code ComponentOrientation}.  Equal to NORTHWEST for horizontal,
164      * left-to-right orientations and NORTHEAST for horizontal, right-to-left
165      * orientations.
166      */
167     public static final int FIRST_LINE_START = 23;
168 
169     /**
170      * Place the component in the corner of its display area where
171      * the first line of text on a page would normally end for the current
172      * {@code ComponentOrientation}.  Equal to NORTHEAST for horizontal,
173      * left-to-right orientations and NORTHWEST for horizontal, right-to-left
174      * orientations.
175      */
176     public static final int FIRST_LINE_END = 24;
177 
178     /**
179      * Place the component in the corner of its display area where
180      * the last line of text on a page would normally start for the current
181      * {@code ComponentOrientation}.  Equal to SOUTHWEST for horizontal,
182      * left-to-right orientations and SOUTHEAST for horizontal, right-to-left
183      * orientations.
184      */
185     public static final int LAST_LINE_START = 25;
186 
187     /**
188      * Place the component in the corner of its display area where
189      * the last line of text on a page would normally end for the current
190      * {@code ComponentOrientation}.  Equal to SOUTHEAST for horizontal,
191      * left-to-right orientations and SOUTHWEST for horizontal, right-to-left
192      * orientations.
193      */
194     public static final int LAST_LINE_END = 26;
195 
196     /**
197      * Possible value for the <code>anchor</code> field.  Specifies
198      * that the component should be horizontally centered and
199      * vertically aligned along the baseline of the prevailing row.
200      * If the component does not have a baseline it will be vertically
201      * centered.
202      *
203      * @since 1.6
204      */
205     public static final int BASELINE = 0x100;
206 
207     /**
208      * Possible value for the <code>anchor</code> field.  Specifies
209      * that the component should be horizontally placed along the
210      * leading edge.  For components with a left-to-right orientation,
211      * the leading edge is the left edge.  Vertically the component is
212      * aligned along the baseline of the prevailing row.  If the
213      * component does not have a baseline it will be vertically
214      * centered.
215      *
216      * @since 1.6
217      */
218     public static final int BASELINE_LEADING = 0x200;
219 
220     /**
221      * Possible value for the <code>anchor</code> field.  Specifies
222      * that the component should be horizontally placed along the
223      * trailing edge.  For components with a left-to-right
224      * orientation, the trailing edge is the right edge.  Vertically
225      * the component is aligned along the baseline of the prevailing
226      * row.  If the component does not have a baseline it will be
227      * vertically centered.
228      *
229      * @since 1.6
230      */
231     public static final int BASELINE_TRAILING = 0x300;
232 
233     /**
234      * Possible value for the <code>anchor</code> field.  Specifies
235      * that the component should be horizontally centered.  Vertically
236      * the component is positioned so that its bottom edge touches
237      * the baseline of the starting row.  If the starting row does not
238      * have a baseline it will be vertically centered.
239      *
240      * @since 1.6
241      */
242     public static final int ABOVE_BASELINE = 0x400;
243 
244     /**
245      * Possible value for the <code>anchor</code> field.  Specifies
246      * that the component should be horizontally placed along the
247      * leading edge.  For components with a left-to-right orientation,
248      * the leading edge is the left edge.  Vertically the component is
249      * positioned so that its bottom edge touches the baseline of the
250      * starting row.  If the starting row does not have a baseline it
251      * will be vertically centered.
252      *
253      * @since 1.6
254      */
255     public static final int ABOVE_BASELINE_LEADING = 0x500;
256 
257     /**
258      * Possible value for the <code>anchor</code> field.  Specifies
259      * that the component should be horizontally placed along the
260      * trailing edge.  For components with a left-to-right
261      * orientation, the trailing edge is the right edge.  Vertically
262      * the component is positioned so that its bottom edge touches
263      * the baseline of the starting row.  If the starting row does not
264      * have a baseline it will be vertically centered.
265      *
266      * @since 1.6
267      */
268     public static final int ABOVE_BASELINE_TRAILING = 0x600;
269 
270     /**
271      * Possible value for the <code>anchor</code> field.  Specifies
272      * that the component should be horizontally centered.  Vertically
273      * the component is positioned so that its top edge touches the
274      * baseline of the starting row.  If the starting row does not
275      * have a baseline it will be vertically centered.
276      *
277      * @since 1.6
278      */
279     public static final int BELOW_BASELINE = 0x700;
280 
281     /**
282      * Possible value for the <code>anchor</code> field.  Specifies
283      * that the component should be horizontally placed along the
284      * leading edge.  For components with a left-to-right orientation,
285      * the leading edge is the left edge.  Vertically the component is
286      * positioned so that its top edge touches the baseline of the
287      * starting row.  If the starting row does not have a baseline it
288      * will be vertically centered.
289      *
290      * @since 1.6
291      */
292     public static final int BELOW_BASELINE_LEADING = 0x800;
293 
294     /**
295      * Possible value for the <code>anchor</code> field.  Specifies
296      * that the component should be horizontally placed along the
297      * trailing edge.  For components with a left-to-right
298      * orientation, the trailing edge is the right edge.  Vertically
299      * the component is positioned so that its top edge touches the
300      * baseline of the starting row.  If the starting row does not
301      * have a baseline it will be vertically centered.
302      *
303      * @since 1.6
304      */
305     public static final int BELOW_BASELINE_TRAILING = 0x900;
306 
307     /**
308      * Specifies the cell containing the leading edge of the component's
309      * display area, where the first cell in a row has <code>gridx=0</code>.
310      * The leading edge of a component's display area is its left edge for
311      * a horizontal, left-to-right container and its right edge for a
312      * horizontal, right-to-left container.
313      * The value
314      * <code>RELATIVE</code> specifies that the component be placed
315      * immediately following the component that was added to the container
316      * just before this component was added.
317      * <p>
318      * The default value is <code>RELATIVE</code>.
319      * <code>gridx</code> should be a non-negative value.
320      * @serial
321      * @see #clone()
322      * @see java.awt.GridBagConstraints#gridy
323      * @see java.awt.ComponentOrientation
324      */
325     public int gridx;
326 
327     /**
328      * Specifies the cell at the top of the component's display area,
329      * where the topmost cell has <code>gridy=0</code>. The value
330      * <code>RELATIVE</code> specifies that the component be placed just
331      * below the component that was added to the container just before
332      * this component was added.
333      * <p>
334      * The default value is <code>RELATIVE</code>.
335      * <code>gridy</code> should be a non-negative value.
336      * @serial
337      * @see #clone()
338      * @see java.awt.GridBagConstraints#gridx
339      */
340     public int gridy;
341 
342     /**
343      * Specifies the number of cells in a row for the component's
344      * display area.
345      * <p>
346      * Use <code>REMAINDER</code> to specify that the component's
347      * display area will be from <code>gridx</code> to the last
348      * cell in the row.
349      * Use <code>RELATIVE</code> to specify that the component's
350      * display area will be from <code>gridx</code> to the next
351      * to the last one in its row.
352      * <p>
353      * <code>gridwidth</code> should be non-negative and the default
354      * value is 1.
355      * @serial
356      * @see #clone()
357      * @see java.awt.GridBagConstraints#gridheight
358      */
359     public int gridwidth;
360 
361     /**
362      * Specifies the number of cells in a column for the component's
363      * display area.
364      * <p>
365      * Use <code>REMAINDER</code> to specify that the component's
366      * display area will be from <code>gridy</code> to the last
367      * cell in the column.
368      * Use <code>RELATIVE</code> to specify that the component's
369      * display area will be from <code>gridy</code> to the next
370      * to the last one in its column.
371      * <p>
372      * <code>gridheight</code> should be a non-negative value and the
373      * default value is 1.
374      * @serial
375      * @see #clone()
376      * @see java.awt.GridBagConstraints#gridwidth
377      */
378     public int gridheight;
379 
380     /**
381      * Specifies how to distribute extra horizontal space.
382      * <p>
383      * The grid bag layout manager calculates the weight of a column to
384      * be the maximum <code>weightx</code> of all the components in a
385      * column. If the resulting layout is smaller horizontally than the area
386      * it needs to fill, the extra space is distributed to each column in
387      * proportion to its weight. A column that has a weight of zero receives
388      * no extra space.
389      * <p>
390      * If all the weights are zero, all the extra space appears between
391      * the grids of the cell and the left and right edges.
392      * <p>
393      * The default value of this field is <code>0</code>.
394      * <code>weightx</code> should be a non-negative value.
395      * @serial
396      * @see #clone()
397      * @see java.awt.GridBagConstraints#weighty
398      */
399     public double weightx;
400 
401     /**
402      * Specifies how to distribute extra vertical space.
403      * <p>
404      * The grid bag layout manager calculates the weight of a row to be
405      * the maximum <code>weighty</code> of all the components in a row.
406      * If the resulting layout is smaller vertically than the area it
407      * needs to fill, the extra space is distributed to each row in
408      * proportion to its weight. A row that has a weight of zero receives no
409      * extra space.
410      * <p>
411      * If all the weights are zero, all the extra space appears between
412      * the grids of the cell and the top and bottom edges.
413      * <p>
414      * The default value of this field is <code>0</code>.
415      * <code>weighty</code> should be a non-negative value.
416      * @serial
417      * @see #clone()
418      * @see java.awt.GridBagConstraints#weightx
419      */
420     public double weighty;
421 
422     /**
423      * This field is used when the component is smaller than its
424      * display area. It determines where, within the display area, to
425      * place the component.
426      * <p> There are three kinds of possible values: orientation
427      * relative, baseline relative and absolute.  Orientation relative
428      * values are interpreted relative to the container's component
429      * orientation property, baseline relative values are interpreted
430      * relative to the baseline and absolute values are not.  The
431      * absolute values are:
432      * <code>CENTER</code>, <code>NORTH</code>, <code>NORTHEAST</code>,
433      * <code>EAST</code>, <code>SOUTHEAST</code>, <code>SOUTH</code>,
434      * <code>SOUTHWEST</code>, <code>WEST</code>, and <code>NORTHWEST</code>.
435      * The orientation relative values are: <code>PAGE_START</code>,
436      * <code>PAGE_END</code>,
437      * <code>LINE_START</code>, <code>LINE_END</code>,
438      * <code>FIRST_LINE_START</code>, <code>FIRST_LINE_END</code>,
439      * <code>LAST_LINE_START</code> and <code>LAST_LINE_END</code>.  The
440      * baseline relative values are:
441      * <code>BASELINE</code>, <code>BASELINE_LEADING</code>,
442      * <code>BASELINE_TRAILING</code>,
443      * <code>ABOVE_BASELINE</code>, <code>ABOVE_BASELINE_LEADING</code>,
444      * <code>ABOVE_BASELINE_TRAILING</code>,
445      * <code>BELOW_BASELINE</code>, <code>BELOW_BASELINE_LEADING</code>,
446      * and <code>BELOW_BASELINE_TRAILING</code>.
447      * The default value is <code>CENTER</code>.
448      * @serial
449      * @see #clone()
450      * @see java.awt.ComponentOrientation
451      */
452     public int anchor;
453 
454     /**
455      * This field is used when the component's display area is larger
456      * than the component's requested size. It determines whether to
457      * resize the component, and if so, how.
458      * <p>
459      * The following values are valid for <code>fill</code>:
460      *
461      * <ul>
462      * <li>
463      * <code>NONE</code>: Do not resize the component.
464      * <li>
465      * <code>HORIZONTAL</code>: Make the component wide enough to fill
466      *         its display area horizontally, but do not change its height.
467      * <li>
468      * <code>VERTICAL</code>: Make the component tall enough to fill its
469      *         display area vertically, but do not change its width.
470      * <li>
471      * <code>BOTH</code>: Make the component fill its display area
472      *         entirely.
473      * </ul>
474      * <p>
475      * The default value is <code>NONE</code>.
476      * @serial
477      * @see #clone()
478      */
479     public int fill;
480 
481     /**
482      * This field specifies the external padding of the component, the
483      * minimum amount of space between the component and the edges of its
484      * display area.
485      * <p>
486      * The default value is <code>new Insets(0, 0, 0, 0)</code>.
487      * @serial
488      * @see #clone()
489      */
490     public Insets insets;
491 
492     /**
493      * This field specifies the internal padding of the component, how much
494      * space to add to the minimum width of the component. The width of
495      * the component is at least its minimum width plus
496      * <code>ipadx</code> pixels.
497      * <p>
498      * The default value is <code>0</code>.
499      * @serial
500      * @see #clone()
501      * @see java.awt.GridBagConstraints#ipady
502      */
503     public int ipadx;
504 
505     /**
506      * This field specifies the internal padding, that is, how much
507      * space to add to the minimum height of the component. The height of
508      * the component is at least its minimum height plus
509      * <code>ipady</code> pixels.
510      * <p>
511      * The default value is 0.
512      * @serial
513      * @see #clone()
514      * @see java.awt.GridBagConstraints#ipadx
515      */
516     public int ipady;
517 
518     /**
519      * Temporary place holder for the x coordinate.
520      * @serial
521      */
522     int tempX;
523     /**
524      * Temporary place holder for the y coordinate.
525      * @serial
526      */
527     int tempY;
528     /**
529      * Temporary place holder for the Width of the component.
530      * @serial
531      */
532     int tempWidth;
533     /**
534      * Temporary place holder for the Height of the component.
535      * @serial
536      */
537     int tempHeight;
538     /**
539      * The minimum width of the component.  It is used to calculate
540      * <code>ipady</code>, where the default will be 0.
541      * @serial
542      * @see #ipady
543      */
544     int minWidth;
545     /**
546      * The minimum height of the component. It is used to calculate
547      * <code>ipadx</code>, where the default will be 0.
548      * @serial
549      * @see #ipadx
550      */
551     int minHeight;
552 
553     // The following fields are only used if the anchor is
554     // one of BASELINE, BASELINE_LEADING or BASELINE_TRAILING.
555     // ascent and descent include the insets and ipady values.
556     transient int ascent;
557     transient int descent;
558     transient Component.BaselineResizeBehavior baselineResizeBehavior;
559     // The folllowing two fields are used if the baseline type is
560     // CENTER_OFFSET.
561     // centerPadding is either 0 or 1 and indicates if
562     // the height needs to be padded by one when calculating where the
563     // baseline lands
564     transient int centerPadding;
565     // Where the baseline lands relative to the center of the component.
566     transient int centerOffset;
567 
568     /*
569      * JDK 1.1 serialVersionUID
570      */
571     private static final long serialVersionUID = -1000070633030801713L;
572 
573     /**
574      * Creates a <code>GridBagConstraint</code> object with
575      * all of its fields set to their default value.
576      */
577     public GridBagConstraints () {
578         gridx = RELATIVE;
579         gridy = RELATIVE;
580         gridwidth = 1;
581         gridheight = 1;
582 
583         weightx = 0;
584         weighty = 0;
585         anchor = CENTER;
586         fill = NONE;
587 
588         insets = new Insets(0, 0, 0, 0);
589         ipadx = 0;
590         ipady = 0;
591     }
592 
593     /**
594      * Creates a <code>GridBagConstraints</code> object with
595      * all of its fields set to the passed-in arguments.
596      *
597      * Note: Because the use of this constructor hinders readability
598      * of source code, this constructor should only be used by
599      * automatic source code generation tools.
600      *
601      * @param gridx     The initial gridx value.
602      * @param gridy     The initial gridy value.
603      * @param gridwidth The initial gridwidth value.
604      * @param gridheight        The initial gridheight value.
605      * @param weightx   The initial weightx value.
606      * @param weighty   The initial weighty value.
607      * @param anchor    The initial anchor value.
608      * @param fill      The initial fill value.
609      * @param insets    The initial insets value.
610      * @param ipadx     The initial ipadx value.
611      * @param ipady     The initial ipady value.
612      *
613      * @see java.awt.GridBagConstraints#gridx
614      * @see java.awt.GridBagConstraints#gridy
615      * @see java.awt.GridBagConstraints#gridwidth
616      * @see java.awt.GridBagConstraints#gridheight
617      * @see java.awt.GridBagConstraints#weightx
618      * @see java.awt.GridBagConstraints#weighty
619      * @see java.awt.GridBagConstraints#anchor
620      * @see java.awt.GridBagConstraints#fill
621      * @see java.awt.GridBagConstraints#insets
622      * @see java.awt.GridBagConstraints#ipadx
623      * @see java.awt.GridBagConstraints#ipady
624      *
625      * @since 1.2
626      */
627     public GridBagConstraints(int gridx, int gridy,
628                               int gridwidth, int gridheight,
629                               double weightx, double weighty,
630                               int anchor, int fill,
631                               Insets insets, int ipadx, int ipady) {
632         this.gridx = gridx;
633         this.gridy = gridy;
634         this.gridwidth = gridwidth;
635         this.gridheight = gridheight;
636         this.fill = fill;
637         this.ipadx = ipadx;
638         this.ipady = ipady;
639         this.insets = insets;
640         this.anchor  = anchor;
641         this.weightx = weightx;
642         this.weighty = weighty;
643     }
644 
645     /**
646      * Creates a copy of this grid bag constraint.
647      * @return     a copy of this grid bag constraint
648      */
649     public Object clone () {
650         try {
651             GridBagConstraints c = (GridBagConstraints)super.clone();
652             c.insets = (Insets)insets.clone();
653             return c;
654         } catch (CloneNotSupportedException e) {
655             // this shouldn't happen, since we are Cloneable
656             throw new InternalError(e);
657         }
658     }
659 
660     boolean isVerticallyResizable() {
661         return (fill == BOTH || fill == VERTICAL);
662     }
663 }