gridbag.html

jsf、swing的官方指南

<a class="SourceLink" target="_blank" href="examples/GridBagLayoutDemo.java"><code>GridBagLayoutDemo.java</code></a>.

<p>

<code>GridBagLayout</code> is one of the most flexible &#151;
and complex &#151;
layout managers the Java platform provides.
A <code>GridBagLayout</code> places components 
in a grid of rows and columns,
allowing specified components
to span multiple rows or columns.
Not all rows necessarily have the same height.
Similarly, not all columns necessarily have the same width.
Essentially, <code>GridBagLayout</code> places components
in rectangles (cells) in a grid,
and then uses the components' preferred sizes
to determine how big the cells should be.

<p>

The following figure shows the grid for
the preceding applet.
As you can see, the grid has three rows and three columns.
The button in the second row 
spans all the columns;
the button in the third row
spans the two right columns.

<p>

If you enlarge the window as shown in the following figure,
you'll notice that the bottom row,
which contains Button 5,
gets all the new vertical space.
The new horizontal space 
is split evenly among all the columns.
This resizing behavior is based on weights
the program assigns to individual components
in the <code>GridBagLayout</code>.
You'll also notice that each component
takes up all the available horizontal space &#151;
but not (as you can see with button 5)
all the available vertical space.
This behavior is also specified by the program.

<p><center><IMG SRC="../../figures/uiswing/layout/gridbagbigA.png" WIDTH="388" HEIGHT="182" ALIGN="BOTTOM" ALT="GridBagLayout shown after the user enlarged it."></center></p>
<p>

The way the program specifies
the size and position characteristics 
of its components
is by specifying <em>constraints</em> for each component,
To specify constraints,
you set instance variables in a <code>GridBagConstraints</code> object
and tell the <code>GridBagLayout</code>
(with the <code>setConstraints</code> method)
to associate the constraints with the component.

<p>

The following sections explain the constraints you can set
and provide examples.


</blockquote>
<h3>
<a name="gridbagConstraints">
Specifying Constraints
</a>
</h3>
<blockquote>
The following code is typical of what goes
in a container that uses a
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/java/awt/GridBagLayout.html"><code>GridBagLayout</code></a>.
You'll see a more detailed example
in the next section.

<blockquote><pre>
JPanel pane = new JPanel(new GridBagLayout());
GridBagConstraints c = new GridBagConstraints();

<em>//For each component to be added to this container:</em>
<em>//...Create the component...</em>
<em>//...Set instance variables in the GridBagConstraints instance...</em>
pane.add(theComponent, c);
</pre></blockquote>

As you might have guessed from the above example,
you can reuse the same <code>GridBagConstraints</code> instance
for multiple components,
even if the components have different constraints.
The <code>GridBagLayout</code> extracts the constraint values
and doesn't use the <code>GridBagConstraints</code> again.
You must be careful, however,
to reset the <code>GridBagConstraints</code> instance variables
to their default values
when necessary.

<blockquote><hr><strong>Note:</strong>&nbsp;The following discussion assumes that the <code>GridBagLayout</code>
controls a container that has a left-to-right component orientation.
<hr></blockquote>
<p>

You can set the following 
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/java/awt/GridBagConstraints.html"><code>GridBagConstraints</code></a> instance variables:
<dl>
<dt> <strong><code>gridx</code></strong>,
     <strong><code>gridy</code></strong>
<dd> Specify the row and column
     at the upper left of the component.
     The leftmost column has address
     <code>gridx=0</code>
     and the top row has address
     <code>gridy=0</code>.
     Use <code>GridBagConstraints.RELATIVE</code>
     (the default value)
     to specify that the component be placed
     just to the right of (for <code>gridx</code>)
     or just below (for <code>gridy</code>)
     the component that was added to the container
     just before this component was added.
     We recommend specifying the <code>gridx</code>
     and <code>gridy</code> values for each component;
     this tends to result in more predictable layouts.
<p>
<dt> <strong><code>gridwidth</code></strong>,
     <strong><code>gridheight</code></strong>
<dd> Specify the number of columns
     (for <code>gridwidth</code>)
     or rows
     (for <code>gridheight</code>)
     in the component's display area.
     These constraints specify the number of cells
     the component uses,
     <em>not</em> the number of pixels it uses.
     The default value is 1.
     Use <code>GridBagConstraints.REMAINDER</code> to specify 
     that the component be the last one in its row
     (for <code>gridwidth</code>)
     or column
     (for <code>gridheight</code>).
     Use <code>GridBagConstraints.RELATIVE</code> to specify 
     that the component be the next to last one
     in its row
     (for <code>gridwidth</code>)
     or column
     (for <code>gridheight</code>).
<p>
<strong>Note:</strong>
<code>GridBagLayout</code> doesn't allow components 
to span multiple rows unless the component
is in the leftmost column or you've specified
positive <code>gridx</code> and <code>gridy</code>
values for the component.
<p>
<dt> <strong><code>fill</code></strong>
<dd> Used when the component's display area
     is larger than the component's requested size
     to determine whether and how to resize the component.
     Valid values (defined as <code>GridBagConstraints</code> constants)
     are <code>NONE</code> (the default),
     <code>HORIZONTAL</code>
     (make the component wide enough to fill its display area
     horizontally, but don't change its height),
     <code>VERTICAL</code>
     (make the component tall enough to fill its display area
     vertically, but don't change its width),
     and 
     <code>BOTH</code>
     (make the component fill its display area entirely).
<p>
<dt> <strong><code>ipadx</code></strong>,
     <strong><code>ipady</code></strong>
<dd> Specifies the internal padding: 
     how much to add to the minimum size of the component.
     The default value is zero.
     The width of the component will be at least
     its minimum width plus <code>ipadx*2</code> pixels,
     since the padding applies to both sides of the component.
     Similarly, the height of the component will be at least
     its minimum height plus <code>ipady*2</code> pixels.
<p>
<dt> <strong><code>insets</code></strong>
<dd> Specifies the external padding of the component --
     the minimum amount of space between the component 
     and the edges of its display area.
     The value is specified as an 
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/java/awt/Insets.html"><code>Insets</code></a>     object.
     By default, each component has no external padding.
<p>
<dt> <strong><code>anchor</code></strong>
<dd> Used when the component is smaller than its display area
     to determine where (within the area) to place the component.
     Valid values (defined as <code>GridBagConstraints</code> constants)
     are
     <code>CENTER</code> (the default),
     <code>PAGE_START</code>,
     <code>PAGE_END</code>,
     <code>LINE_START</code>,
     <code>LINE_END</code>,
     <code>FIRST_LINE_START</code>,
     <code>FIRST_LINE_END</code>,
     <code>LAST_LINE_END</code>, and
     <code>LAST_LINE_START</code>.
     <p>
     Here is a picture of how these values are interpreted
     in a container that has the default, left-to-right
     component orientation. [PENDING: A real figure will go here.
     It will put a hint of a button border around each constant,
     so that it's obvious that the component is hugging the 
     specified part of its display area.]

<blockquote>
<pre>-------------------------------------------------
|FIRST_LINE_START   PAGE_START     FIRST_LINE_END|
|                                                |
|                                                |
|LINE_START           CENTER             LINE_END|
|                                                |
|                                                |
|LAST_LINE_START     PAGE_END       LAST_LINE_END|
-------------------------------------------------</pre>
</blockquote>

<blockquote><hr><strong>Version note:</strong>&nbsp;     The <code>PAGE_*</code> and <code>*LINE_*</code>
     constants were introduced in 1.4. 
     Previous releases
     require values named after points of the compass.
     For example, 
     <code>NORTHEAST</code>
     indicates the top-right part of the display area.
     We recommend that you use the new constants, instead,
     since they enable easier localization.
<hr></blockquote>

<p>
<dt> <strong><code>weightx</code></strong>,
     <strong><code>weighty</code></strong>
<dd> Specifying weights is an art 
     that can have a significant impact
     on the appearance of the components a <code>GridBagLayout</code> controls.
     Weights are used to determine how to distribute space
     among columns
     (<code>weightx</code>)
     and among rows
     (<code>weighty</code>);
     this is important for specifying resizing behavior.
     <p>
     Unless you specify at least one nonzero value
     for <code>weightx</code>
     or <code>weighty</code>,
     all the components clump together in the center of
     their container.
     This is because when the weight is 0.0 (the default),
     the <code>GridBagLayout</code> puts any extra space 
     between its grid of cells and the edges of the container.
     <p>
     Generally weights are specified with 0.0 and 1.0 as the extremes:
     the numbers in between are used as necessary.
     Larger numbers indicate that the component's row or column
     should get more space.
     For each column, the weight is related to
     the highest <code>weightx</code> specified 
     for a component within that column,
     with each multicolumn component's weight being split somehow
     between the columns the component is in.
     Similarly, each row's weight is related to
     the highest <code>weighty</code> specified 
     for a component within that row.
     Extra space tends to go toward the rightmost column and bottom row.

</dl>

<p>

The next section discusses constraints in depth,
in the context of explaining
how the example program works.


</blockquote>
<h3>
<a name="gridbagExample">
The Example Explained
</a>
</h3>
<blockquote>
Here, again, is a picture of the
GridBagLayoutDemo application,
which you can
<a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/layout/examples/GridBagLayoutDemo.jnlp">run</a>
using
<a class="TutorialLink" target="_top" href="../../information/javawebstart.html">Java<sup><font size=-2>TM</font></sup> Web Start</a>.

<p><center><IMG SRC="../../figures/uiswing/layout/GridBagLayoutDemo.png" WIDTH="250" HEIGHT="164" ALIGN="BOTTOM" ALT="A snapshot of GridBagLayoutDemo"></center></p>
<p>
The following code creates the <code>GridBagLayout</code>
and the components it manages.
You can find the entire source file in
<a class="SourceLink" target="_blank" href="examples/GridBagLayoutDemo.java"><code>GridBagLayoutDemo.java</code></a>.

<blockquote><pre>
JButton button;
pane.setLayout(new GridBagLayout());
GridBagConstraints c = new GridBagConstraints();
c.fill = GridBagConstraints.HORIZONTAL;

button = new JButton("Button 1");
c.weightx = 0.5;
c.gridx = 0;
c.gridy = 0;
pane.add(button, c);

button = new JButton("Button 2");
c.gridx = 1;
c.gridy = 0;
pane.add(button, c);

button = new JButton("Button 3");
c.gridx = 2;
c.gridy = 0;
pane.add(button, c);

button = new JButton("Long-Named Button 4");
c.ipady = 40;      //make this component tall
c.weightx = 0.0;
c.gridwidth = 3;
c.gridx = 0;
c.gridy = 1;