1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><!-- InstanceBegin template="/Templates/TableLayout.dwt" codeOutsideHTMLIsLocked="false" -->
<head>
<!-- InstanceBeginEditable name="doctitle" -->
<title>TableLayout - Tutorial</title>
<!-- InstanceEndEditable -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<!-- InstanceBeginEditable name="head" -->
<!-- InstanceEndEditable -->
<link href="stylesheet.css" rel="stylesheet" type="text/css" />
</head>
<body>
<p><img src="images/Logo.png" width="800" height="150" /></p>
<table width="800" border="0" cellspacing="0" cellpadding="10">
<tr>
<td width="150" align="left" valign="top" id="sidebar">
<p><a href="index.html">Introduction</a></p>
<p><a href="features.html">Features</a></p>
<p><a href="screenshots.html">Screen<br />
shots</a></p>
<p><a href="tutorial.html">Tutorial</a></p>
<p><a href="examples.html">Examples</a></p>
<p><a href="api/index.html">API<br />
documentation</a></p>
<p><a href="https://sourceforge.net/project/showfiles.php?group_id=113939">Download</a></p>
<p><a href="resources.html">Other<br />
resources</a></p>
<p><a href="../../index.html">Return to<br />
FLib </a></p>
<p><a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=113939&type=1" alt="SourceForge.net Logo" width="88" height="31" border="0" align="top" title="" /></a></p>
<p><a href="http://www.jars.com/"><img src="http://www.jars.com/images/r750.gif" alt="Rated JARS Top 25%" width="104" height="56" border="0" align="top" title="" /></a></p> </td>
<td id="content" width="614" align="left" valign="top"><!-- InstanceBeginEditable name="content" -->
<h1>Tutorial</h1>
<h2>TableLayout</h2>
<p>This layout manager was loosely inspired by the HTML table. It has all
the power of the GridBagLayout, but is much easier to use.</p>
<h3>The Layout Manager Concept</h3>
<p>Container is a Component class which contains one or more other components.
Every container has a layout manager which arranges the positions and
sizes of the components in the container. </p>
<p>The container is given a certain
amount of screen space for its components. The layout manager then
needs to figure out how to size and position the container's components
within
this space. It can use any algorithm it wants. It does not need to
fill all the space nor does it need to prevent components from overlapping.</p>
<h3>The TableLayout</h3>
<p>The TableLayout lays out components in a table format. The table has
rows and columns which are typically not all the same width or height
(if you need constant width and height, consider using the GridLayout). </p>
<p>You usually need
to define the number of columns in the table (the default is 1, which
is typically not what you want). As components are added to the container,
they are placed in the next available column of the current row. When
a row is filled, the next component adds a row and is placed in the first
column.</p>
<p>Consider this code:</p>
<pre>JPanel panel = new JPanel(new TableLayout("cols=3"));
panel.add(new JButton("0"));
panel.add(new JButton("1"));
panel.add(new JButton("2"));
panel.add(new JButton("3"));
panel.add(new JButton("4"));
</pre>
<p>This generates the following layout:</p>
<p align="center"><img src="images/tutorial1.png" width="213" height="139" /></p>
<p align="left">I started numbering with "0" because, for the TableLayout,
the first column is column 0. In this example, we see a three-column
table, with each JButton component added to the next available column.
Since there are only five components, the last "slot" is left empty.</p>
<h3>Attributes</h3>
<p>The above example is very simple because only one attribute was given
to the TableLayout ("cols=5"). Attributes are instructions to the TableLayout
which tell it how to lay out each component in the table or the table
as a whole. </p>
<p>The format of the attributes is similar to HTML attributes. The attributes
are case insensitive and can be separated with any white space. Attributes
which take a value are followed by an '=' and then an integer. Here's
an example: "cols=6 rgap=2 cgap=5 w".</p>
<p>Attributes are evaluated from left to right. If you duplicate an attribute,
the right-most one wins.</p>
<p>Some attributes apply only to the table as whole. You pass them in a
String given either in the TableLayout constructor or in the <code>setTableAttributes()</code>
method.</p>
<p>The remaining attributes apply to the components in the container. Of
these, some can also be specified along with the table attributes. These
become the defaults for all components in the table. This is one of the
features which makes the TableLayout easy to use.</p>
<p>Here is the complete list of attributes:</p>
<table border="1" cellpadding="3" cellspacing="0">
<tr bgcolor="#CCCCFF">
<td><b>Name</b></td>
<td><b>Description</b></td>
<td><b>Has Value?</b></td>
<td><b>Default</b></td>
<td><b>Scope</b></td>
</tr>
<tr bgcolor="white">
<td>cols</td>
<td>Number of columns</td>
<td>Yes</td>
<td>1</td>
<td>Table</td>
</tr>
<tr bgcolor="white">
<td>col</td>
<td>Place Component in this column</td>
<td>Yes</td>
<td>Next empty column</td>
<td>Component</td>
</tr>
<tr bgcolor="white">
<td>skip</td>
<td>Skip a number of columns</td>
<td>Yes</td>
<td>0</td>
<td>Component</td>
</tr>
<tr bgcolor="white">
<td>rspan, cspan</td>
<td>Row and column spanning</td>
<td>Yes</td>
<td>1</td>
<td>Component</td>
</tr>
<tr bgcolor="white">
<td>titop, tibottom, tileft, tiright</td>
<td>Table insets</td>
<td>Yes</td>
<td>0</td>
<td>Table</td>
</tr>
<tr bgcolor="white">
<td>rgap, cgap</td>
<td>Row and column gaps</td>
<td>Yes</td>
<td>0</td>
<td>Table</td>
</tr>
<tr bgcolor="white">
<td>itop, ibottom, ileft, iright</td>
<td>Component insets</td>
<td>Yes</td>
<td>0</td>
<td>Table/Component</td>
</tr>
<tr bgcolor="white">
<td>tn, tne, te, tse, ts, tsw, tw, tnw, tc, tf, tfh, tfv</td>
<td>Table placement and fill</td>
<td>No</td>
<td>tf</td>
<td>Table</td>
</tr>
<tr bgcolor="white">
<td>n, ne, e, se, s, sw, w, nw, c, f, fh, fv</td>
<td>Component placement and fill</td>
<td>No</td>
<td>f</td>
<td>Table/Component</td>
</tr>
<tr bgcolor="white">
<td>rweight, cweight</td>
<td>Row and column weights</td>
<td>Yes</td>
<td>0</td>
<td>Table/Component</td>
</tr>
</table>
<h3>Rows and Columns</h3>
<p>As I stated above, you will almost always specify the number of columns
in the table. Components are then placed in the table from left to right,
adding new rows as necessary.</p>
<p>You can override the default component placement somewhat with "col"
and "skip".
With "col", you specify the column number in which the component
should be placed. If you have already passed the given column, the layout
adds another row and places the Component in the column on that new row.</p>
<p> "skip" allows you to skip a number of cells. If the layout reaches
the end of the row, skipping continues on the next row.</p>
<p> You can also make a component span multiple rows or columns with rspan
and cspan. Components added later will skip over any occupied cells,
which is important to note for row spanning.</p>
<p>Let's take the example above and make it use these attributes:</p>
<pre>JPanel panel = new JPanel(new TableLayout("cols=3"));
panel.add(new JButton("0"));
panel.add(new JButton("1"),"skip=1");
panel.add(new JButton("2"), "col=1");
panel.add(new JButton("3"), "rspan=2");
panel.add(new JButton("4"), "cspan=2");</pre>
<p align="center"><img src="images/tutorial2.png" width="232" height="204" /></p>
<h3>Spacing</h3>
The space the TableLayout works with is inside the container's insets.
Some containers have insets of 0 (e.g. JPanel) and most don't allow you
to alter the insets. Since you will often want to control the space between
the table and the edges of the container,
an "extra" table inset can be given: titop, tibottom, tileft and tiright
(in
the "ti" prefix, the "t" stands for "table" and
the "i" stands
for "inset").
<p> Within a cell, you can create space between the cells edges and the component
in the cell. The attributes are itop, ibottom, ileft and iright.</p>
<p>You can also add space between cells in the table. This space is <em>only</em> placed
between cells; never along the edges of the table. This allows you to nest
table layouts and keep consistent cell spacing. The attributes used are rgap
and cgap and their default value is 0.</p>
<p>Here is our example with the addition of table and cell insets plus cell spacing.
Note that we specify the cell insets and spacing when we define the table attributes.
This means that all components will get the same insets and spacing without
having to duplicate this information for each individual component. We override
the default insets for one of the components.</p>
<pre>JPanel panel = new JPanel(
new TableLayout(
"cols=3 rgap=3 cgap=3 " +
"titop=5 tibottom=5 tileft=5 tiright=5 " +
"itop=2 ibottom=2 ileft=2 iright=2"));
panel.add(new JButton("0"));
panel.add(new JButton("1"), "skip=1");
panel.add(new JButton("2"), "itop=0 ibottom=0 ileft=0 iright=0 col=1");
panel.add(new JButton("3"), "rspan=2");
panel.add(new JButton("4"), "cspan=2");</pre>
<p>Here's what we get:</p>
<p align="center"><img src="images/tutorial3.png" width="260" height="226" /></p>
<h3>Placement and Filling</h3>
<p> Given that you have something to draw and a space to draw it in, you have
some choices as to where to place it and how to fill it, particularly when
the available area is bigger than required. So far, except for the insets,
we've allowed the table to completely fill the available container space and
we've
allowed each component to completely fill its table cell.</p>
<p> Placement attributes allow you to place a component centered or in one of
eight compass directions within its cell. It's easier to demonstrate than to
describe:</p>
<pre>JPanel panel = new JPanel(new TableLayout("cols=3"));
panel.add(new JButton("1"), "nw");
panel.add(new JButton("2"), "n");
panel.add(new JButton("3"), "ne");
panel.add(new JButton("4"), "w");
panel.add(new JButton("5"), "c");
panel.add(new JButton("6"), "e");
panel.add(new JButton("7"), "sw");
panel.add(new JButton("8"), "s");
panel.add(new JButton("9"), "se");</pre>
<p align="center"><img src="images/tutorial4.png" width="204" height="138" /></p>
<p>Using the placement attributes, a component is left at its preferred size.
Then it is moved to the designated edge or corner (or center) of the cell.</p>
<p>There are placement attributes for the table itself. These are just like the
component placement attributes, but start with a "t". You can find these in
the attribute table above. Like the component, the table is set to its preferred
size and moved to the edge, corner or center of the container.</p>
<p>The entire table can be placed within the container using tn, tne, te, tse,
ts, tsw, tw, tnw and tc (the "t" prefix is for "table").</p>
<p> Fill attributes allow you to fill the item to cover all available space.
Horizontal and vertical filling are handled separately. For tables, the attributes
are tfh, tfv and tf. "tf" fills in both directions. For Components, use
fh, fv and f. For instance, if we change just the first line of the example
to:</p>
<pre>JPanel panel = new JPanel(new TableLayout("cols=3 tnw"));
</pre>
<p>We get</p>
<p align="center"><img src="images/tutorial5.png" width="204" height="138" /></p>
<p>The table is at its preferred size and placed in the northwest
corner of the container. Since the preferred sizes of the buttons are all the
same, the cells appeared to be filled even though they still have the same
placement attributes as before.</p>
<p>Instead of placing a component within a cell, you can have it stretch to fill
the cell, either vertically, horizontally or both. Here's our example:</p>
<pre>JPanel panel = new JPanel(new TableLayout("cols=3"));
panel.add(new JButton("1"), "c fh");
panel.add(new JButton("2"), "f");
panel.add(new JButton("3"), "c fh");</pre>
<p align="center"><img src="images/tutorial6.png" width="261" height="67" /></p>
<p>Since the default is "f", we turn off filling by using "c". Then we can fill
horizontally, vertically or in both directions. </p>
<p>The "f" in the second component
is redundant, since this is the default. But keep in mind that you can define
the default placement or fill by specifying it in the table attributes.
For example,</p>
<pre>JPanel panel = new JPanel(new TableLayout("cols=3 nw"));</pre>
<p>would place all components in the top left corner of each cell, unless a
component overrides the default.</p>
<p>When combining placement and fill attributes, the rules are:</p>
<ul>
<li>Placement attributes turn off all filling.</li>
<li>Fill attributes turn off placement, but only in the fill direction.</li>
</ul>
<p>So, for example, "n fh" will stretch a component horizontally, but will attach
its top edge at the top of the cell.</p>
<h3>Weighting</h3>
<p>By setting the "weight" of each row or column, you can control how the rows
and columns are allocated space when there is more space available than is
needed (given the preferred sizes of the components).</p>
<p>The default is to equally distribute the extra space to all cells. This is
not always what you want. Sometimes you'd like some rows or columns to stretch
while others stay a fixed size. This is easy to do: assign the rows and columns
you want to stretch a weight of 1 ("rweight" for row weight and "cweight" for
column weight). Here's an example. To keep it simple, we'll stretch components
"1" and "3" horizontally, while the rest of the components are fixed.</p>
<pre>JPanel panel = new JPanel(new TableLayout("cols=5"));
panel.add(new JButton("0"));
panel.add(new JButton("1"), "cweight=1");
panel.add(new JButton("2"));
panel.add(new JButton("3"), "cweight=1");
panel.add(new JButton("4"));</pre>
<p align="center"><img src="images/tutorial7.png" width="205" height="26" /></p>
<p align="center"><img src="images/tutorial8.png" width="314" height="26" /></p>
<p>There are a few things to keep in mind about weighting. The weight of a row
is the largest weight of any component in the row. The advantage is that you
only have to set the row weight for one component in a row and the column weight
for one component in the column.</p>
<p>Keep in mind that assigning the same weight to two rows or columns does
not make them the same size! Weighting only describes how <em>excess</em> space
is distributed to the cells. If the two components have different preferred
sizes, the row or column sizes won't be equal.</p>
<p>Also remember that what we resize is the cell, not the component! If you want
the component to stretch, make sure it fills in the appropriate direction.</p>
<p>There's a subtlety to weighting: weighting is only used when there is excess
space available given the components' preferred sizes. When there is not enough
space for preferred sizes, space is taken away from cells equally, regardless
of the weighting. However, components that shrink to their minimum allowed
size will not shrink further.</p>
<p>There is further detail on all attributes, but particularly on weighting in
the <a href="api/org/freixas/tablelayout/TableLayout.html">TableLayout API</a>.</p>
<h3>Summary</h3>
<p> The TableLayout is both powerful and easy-to-use. After reading this tutorial,
you should examine the <a href="examples.html">example programs</a> provided.
One program places TableLayout head-to-head with GridBagLayout. The
other example simulates the GridBagExplorer written by Eric Burke. I call it
TableExplorer. It allows you to place some JButtons in a container and dynamically
change the table and component attributes. I used this program to create the
examples on this page.</p>
<!-- InstanceEndEditable --></td>
</tr>
</table>
</body>
<!-- InstanceEnd --></html>
|
