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 & 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 }