NAME

Gtk2::Ex::FormFactory::Table - Complex table layouts made easy

SYNOPSIS

  Gtk2::Ex::FormFactory::Table->new (
    layout => "+--------------+>>>>>>>>>>>+
	       | Name	      | Image	  |
	       +--------------+ 	  |
	       | Keywords     | 	  |
	       +-------+------+-----------+
	       > Notes | More | Something |
	       >       |      +-----+-----+
	       >       |      |     | Foo |
	       +-------+------+-----+-----+
	       > Bar	      | Baz	  |
	       +--------------+-----------+",
    content => [
      Gtk2::Ex::FormFactory::Entry->new ( ... ),
      Gtk2::Ex::FormFactory::Image->new ( ... ),
      Gtk2::Ex::FormFactory::Entry->new ( ... ),
      ...
    ],
    ...
    Gtk2::Ex::FormFactory::Container attributes
    Gtk2::Ex::FormFactory::Widget attributes
  );

DESCRIPTION

This module implements a simple way of defining complex table layouts inside a Gtk2::Ex::FormFactory environment.

OBJECT HIERARCHY

Gtk2::Ex::FormFactory::Intro

Gtk2::Ex::FormFactory::Widget
+--- Gtk2::Ex::FormFactory::Container
     +--- Gtk2::Ex::FormFactory::Table

Gtk2::Ex::FormFactory::Layout
Gtk2::Ex::FormFactory::Rules
Gtk2::Ex::FormFactory::Context
Gtk2::Ex::FormFactory::Proxy

LAYOUT DEFINITION

Take a look at the example in the SYNPOSIS. You see, you simply draw the layout of your table. But how does this work exactly?

Each table is based on a straight two dimensional grid, no matter how complicated the cells span over one or more rows or columns. You see the grid when you extend all lines (horizontal and vertical) up to the borders of the table. The following graphic shows the grid by marking the imaginary lines with · characters:

+-------+------+>>>>>+>>>>>+
| Name  ·	 | Img ·     |
+-------+------+·····+·····|
| Keyw  ·	 |     ·     |
+-------+------+-----+-----+
> Notes | More | Som ·     |
>·······|····· +-----+-----+
>	  |	 |     | Foo |
+-------+------+-----+-----+
> Bar   ·	 | Baz ·     |
+-------+------+-----+-----+

All cells of the table are attached to this grid.

Gtk2::Ex::FormFactory::Table distinguishes empty and non empty cells. If only whitespace is inside the cell, it's empty, otherwise it has a widget inside. Since Gtk2::Ex::FormFactory::Table is a Gtk2::Ex::FormFactory::Container it has a simple list of widgets as children.

So how are these widgets assigned to the cells of the table?

Short answer: from left/top to the right/bottom. Gtk2::Ex::FormFactory::Table scans your layout drawing in this direction and once it sees a new cell, it's counted as the next child of the table.

Our example has this child order:

+--------------+>>>>>>>>>>>+
| 1		 | 2	     |
+--------------+	     |
| 3		 |	     |
+-------+------+-----------+
> 4	  | 5	 | 6	     |
>	  |	 +-----+-----+
>	  |	 |     | 7   |
+-------+------+-----+-----+
> 8		 | 9	     |
+--------------+-----------+

So the content attribute of this table must list exactly nine widgets, otherwise you would get a runtime exception, when it comes to building the table.

Ok, now it's clear how the table cells are attached to the grid of the table. But what about the size of the cells and their widgets?

This answer is about funny characters ;)

Since all cells share the same part of the underlying grid they also share the same expansion/filling strategy. So it's sufficient to define the strategy per span, not per cell.

That's why only the first character row and the first character column of your layout definition string matter. You recognized the > characters? They say, that the cell and its widget should both resize with the table, by allocating all space available. In our example cell 2, 6, 7 and 9 resize horizontally with the table, cell 4, 5, 6, 7, 8 and 9 vertically. Cell 1 and 3 don't resize at all, they fill the cell but stay at the cell's size, no matter how the table resizes.

This is the complete list of recognized characters and their meaning (again: these matter only at the first row and column of your layout drawing):

- | + =

The widget fills the cell, but the cell doesn't resize with the table. That's the default, because these characters belong to the set of ASCII graphic characters used to draw the layout.

Equals specifying only 'fill' in terms of Gtk2::Table->attach.

> ^

Both, the cell and the widget, resize with the table.

Equals specifying both 'expand' and 'fill' in terms of Gtk2::Table->attach.

<

The cell doesn't resize and the widget doesn't fill the cell - it keeps its natural size.

Equals specifying neither 'expand' nor 'fill' in terms of Gtk2::Table->attach.

~

The cell resizes with the table, but the Widget keeps its natural size.

Equals specifying only 'expand' in terms of Gtk2::Table->attach.

Notes

Some additional notes about the layout definition string.

Drawing characters

Although this should be obvious ;)

In your drawing | characters (pipe symbol) mark column boundaries, and - or = (dash or equal sign) characters mark row boundaries. The + (plus) characters have no special meaning. They're just for candy.

TAB characters

Don't use TAB characters but true SPACE characters inside the table.

Whitespace around the table

You may have arbitrary whitespace around your table, inlcuding TAB characters. It's cut off before the layout string is parsed.

ATTRIBUTES

Attributes are handled through the common get_ATTR(), set_ATTR() style accessors, but they are mostly passed once to the object constructor and must not be altered after the associated FormFactory was built.

layout = SCALAR

This is a string which defines the layout of this table using some sort of line art ASCII graphics. Refer to the LAYOUT DEFINITION chapter for details about the format.

For more attributes refer to Gtk2::Ex::FormFactory::Container.

AUTHORS

Jörn Reder <joern at zyn dot de>

COPYRIGHT AND LICENSE

Copyright 2004 by Jörn Reder.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA.

cpanm Gtk2::Ex::FormFactory

perl -MCPAN -e shell
install Gtk2::Ex::FormFactory