diff options
Diffstat (limited to 'libs/FLib/TableLayout/doc/tutorial.html')
| -rw-r--r-- | libs/FLib/TableLayout/doc/tutorial.html | 338 |
1 files changed, 338 insertions, 0 deletions
diff --git a/libs/FLib/TableLayout/doc/tutorial.html b/libs/FLib/TableLayout/doc/tutorial.html new file mode 100644 index 0000000..5522d3f --- /dev/null +++ b/libs/FLib/TableLayout/doc/tutorial.html @@ -0,0 +1,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>
|