Gtk2::Ex::FormFactory:UserlContributed Perl DocGtk2::Ex::FormFactory::Table(3)NAMEGtk2::Ex::FormFactory::Table - Complex table layouts made easy
SYNOPSIS
Gtk2::Ex::FormFactory::Table->new (
layout => "+-------%------+>>>>>>>>>>>>>>>+
| Name | |
+--------------~ Image |
| Keywords | |
+-------+------+[--------------+
^ ' More | Something |
^ | +-----+--------]+
_ Notes | | | 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 AX characters:
+-------+------+>>>>>+>>>>>+
| Name AX | Img AX |
+-------+------+AXAXAXAXAX+AXAXAXAXAX|
| Keyw AX | AX |
+-------+------+-----+-----+
^ Notes | More | Som AX |
^AXAXAXAXAXAXAX|AXAXAXAXAX +-----+-----+
^ | | | Foo |
+-------+------+-----+-----+
^ Bar AX | Baz AX |
+-------+------+-----+-----+
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 resp. their widgets and the
alignment of widgets inside their cells?
This answer is about funny characters ;)
Cell / Widget expansion
By default all cells and their widgets doesn't expand if the table
expands. But you recognized the > and ^ characters? They say, that the
cell and its widget should both resize with the table, by allocating
all space available (> for horizontal expansion and ^ for vertical).
If you want to resize just the cell, but not its widget, refer to the
next chapter about widget alignments.
In our example cell 2, 7 and 9 resize horizontal with the table, cell
4, 5, 6, 7, 8 and 9 vertical. 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.
Widget alignment
By default widgets fill their cell completely. If the cell expands the
widgets expands as well. But you may want to align the widget on the
left or right side, or in the middle, resp. at the top and the bottom.
Once you define an alignment, the widget doesn't fill the cell anymore.
Again there are some funny characters defining the alignment.
For horizontal alignments the characters must be used in the top border
of the cell. For vertical alignment it needs to be the left border of
the cell.
Horinzontal alignment is controlled with these characters: [ left, ]
right and % middle.
Vertical alignment is controlled with these characters: ' top, _ bottom
and ~ middle.
In the SYNPOSIS example "Image" is attached in the middle (vertical),
"Notes" at the bottom and "More" at the top. "Something" is attached
left, "Foo" right and "Name" centered (horizontal).
Complete list of special characters
This is the complete list of recognized characters and their meaning:
- | + = 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.
> The cell expands horizontal. Recognized only in the top
border of a cell.
^ The cell expands vertical. Recognized only in the left border
of a cell.
[ Widget is attached on the left and doesn't expand anymore
with the cell. Recognized only in the top border of a cell.
] Widget is attached on the right and doesn't expand anymore
with the cell. Recognized only in the top border of a cell.
% Widget is attached in the middle (horizontal) and doesn't
expand anymore with the cell. Recognized only in the top
border of a cell.
' Widget is attached on the top and doesn't expand anymore with
the cell. Recognized only in the left border of a cell.
_ Widget is attached on the bottom and doesn't expand anymore
with the cell. Recognized only in the left border of a cell.
~ Widget is attached in the middle (vertical) and doesn't
expand anymore with the cell. Recognized only in the left
border of a cell.
Notes
Some additional notes about the layout definition string.
Drawing characters
Although this should be obvious ;)
In your drawing | characters (pipe symbol) mark column borders, and
- or = (dash or equal sign) characters mark row borders. The +
(plus) characters have no special meaning. They're just for candy.
For completeness: additionally the ^ _ and ' characters mark
horizontal cell borders, since these are special characters
controling the vertical alignment of a cell and are placed on the
vertical borders of cells.
You need at least one - or = character in the top vertical border
of each row, otherwise the vertical raster of your table can't be
recognized correctly. This should be no problem in practice at all.
TAB characters
Don't use TAB characters but true SPACE characters inside the
table. You get a warning on TAB characters.
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
JA~Xrn Reder <joern at zyn dot de>
COPYRIGHT AND LICENSE
Copyright 2004-2006 by JA~Xrn 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.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 42:
=cut found outside a pod block. Skipping to next block.
Around line 72:
=cut found outside a pod block. Skipping to next block.
perl v5.14.1 2006-02-27 Gtk2::Ex::FormFactory::Table(3)
