1Gtk2::Ex::FormFactory::UTsaebrleC(o3n)tributed Perl DocuGmtekn2t:a:tEixo:n:FormFactory::Table(3)
2
6 Gtk2::Ex::FormFactory::Table - Complex table layouts made easy
7
9 Gtk2::Ex::FormFactory::Table->new (
10 layout => "+-------%------+>>>>>>>>>>>>>>>+
11 | Name | |
12 +--------------~ Image |
13 | Keywords | |
14 +-------+------+[--------------+
15 ^ ' More | Something |
16 ^ | +-----+--------]+
17 _ Notes | | | Foo |
18 +-------+------+-----+---------+
19 ^ Bar | Baz |
20 +--------------+---------------+",
21 content => [
22 Gtk2::Ex::FormFactory::Entry->new ( ... ),
23 Gtk2::Ex::FormFactory::Image->new ( ... ),
24 Gtk2::Ex::FormFactory::Entry->new ( ... ),
25 ...
26 ],
27 ...
28 Gtk2::Ex::FormFactory::Container attributes
29 Gtk2::Ex::FormFactory::Widget attributes
30 );
31
33 This module implements a simple way of defining complex table layouts
34 inside a Gtk2::Ex::FormFactory environment.
35
37 Gtk2::Ex::FormFactory::Intro
38 Gtk2::Ex::FormFactory::Widget
40 +--- Gtk2::Ex::FormFactory::Container
41 +--- Gtk2::Ex::FormFactory::Table
42 Gtk2::Ex::FormFactory::Layout
44 Gtk2::Ex::FormFactory::Rules
45 Gtk2::Ex::FormFactory::Context
46 Gtk2::Ex::FormFactory::Proxy
47
49 Take a look at the example in the SYNPOSIS. You see, you simply draw
50 the layout of your table. But how does this work exactly?
51 Each table is based on a straight two dimensional grid, no matter how
53 complicated the cells span over one or more rows or columns. You see
54 the grid when you extend all lines (horizontal and vertical) up to the
55 borders of the table. The following graphic shows the grid by marking
56 the imaginary lines with · characters:
57 +-------+------+>>>>>+>>>>>+
59 | Name · | Img · |
60 +-------+------+·····+·····|
61 | Keyw · | · |
62 +-------+------+-----+-----+
63 ^ Notes | More | Som · |
64 ^·······|····· +-----+-----+
65 ^ | | | Foo |
66 +-------+------+-----+-----+
67 ^ Bar · | Baz · |
68 +-------+------+-----+-----+
69 All cells of the table are attached to this grid.
71 Gtk2::Ex::FormFactory::Table distinguishes empty and non empty cells.
73 If only whitespace is inside the cell, it's empty, otherwise it has a
74 widget inside. Since Gtk2::Ex::FormFactory::Table is a
75 Gtk2::Ex::FormFactory::Container it has a simple list of widgets as
76 children.
77 So how are these widgets assigned to the cells of the table?
79 Short answer: from left/top to the right/bottom.
81 Gtk2::Ex::FormFactory::Table scans your layout drawing in this
82 direction and once it sees a new cell, it's counted as the next child
83 of the table.
84 Our example has this child order:
86 +--------------+>>>>>>>>>>>+
88 | 1 | 2 |
89 +--------------+ |
90 | 3 | |
91 +-------+------+-----------+
92 ^ 4 | 5 | 6 |
93 ^ | +-----+>>>>>+
94 ^ | | | 7 |
95 +-------+------+-----+-----+
96 ^ 8 | 9 |
97 +--------------+-----------+
98 So the content attribute of this table must list exactly nine widgets,
100 otherwise you would get a runtime exception, when it comes to building
101 the table.
102 Ok, now it's clear how the table cells are attached to the grid of the
104 table. But what about the size of the cells resp. their widgets and the
105 alignment of widgets inside their cells?
106 This answer is about funny characters ;)
108 Cell / Widget expansion
110 By default all cells and their widgets doesn't expand if the table
111 expands. But you recognized the > and ^ characters? They say, that the
112 cell and its widget should both resize with the table, by allocating
113 all space available (> for horizontal expansion and ^ for vertical).
114 If you want to resize just the cell, but not its widget, refer to the
115 next chapter about widget alignments.
116 In our example cell 2, 7 and 9 resize horizontal with the table, cell
118 4, 5, 6, 7, 8 and 9 vertical. Cell 1 and 3 don't resize at all, they
119 fill the cell but stay at the cell's size, no matter how the table
120 resizes.
121 Widget alignment
123 By default widgets fill their cell completely. If the cell expands the
124 widgets expands as well. But you may want to align the widget on the
125 left or right side, or in the middle, resp. at the top and the bottom.
126 Once you define an alignment, the widget doesn't fill the cell anymore.
127 Again there are some funny characters defining the alignment.
128 For horizontal alignments the characters must be used in the top border
130 of the cell. For vertical alignment it needs to be the left border of
131 the cell.
132 Horinzontal alignment is controlled with these characters: [ left, ]
134 right and % middle.
135 Vertical alignment is controlled with these characters: ' top, _ bottom
137 and ~ middle.
138 In the SYNPOSIS example "Image" is attached in the middle (vertical),
140 "Notes" at the bottom and "More" at the top. "Something" is attached
141 left, "Foo" right and "Name" centered (horizontal).
142 Complete list of special characters
144 This is the complete list of recognized characters and their meaning:
145 - | + = The widget fills the cell, but the cell doesn't resize with
147 the table. That's the default, because these characters
148 belong to the set of ASCII graphic characters used to draw
149 the layout.
150 > The cell expands horizontal. Recognized only in the top
152 border of a cell.
153 ^ The cell expands vertical. Recognized only in the left border
155 of a cell.
156 [ Widget is attached on the left and doesn't expand anymore
158 with the cell. Recognized only in the top border of a cell.
159 ] Widget is attached on the right and doesn't expand anymore
161 with the cell. Recognized only in the top border of a cell.
162 % Widget is attached in the middle (horizontal) and doesn't
164 expand anymore with the cell. Recognized only in the top
165 border of a cell.
166 ' Widget is attached on the top and doesn't expand anymore with
168 the cell. Recognized only in the left border of a cell.
169 _ Widget is attached on the bottom and doesn't expand anymore
171 with the cell. Recognized only in the left border of a cell.
172 ~ Widget is attached in the middle (vertical) and doesn't
174 expand anymore with the cell. Recognized only in the left
175 border of a cell.
176 Notes
178 Some additional notes about the layout definition string.
179 Drawing characters
181 Although this should be obvious ;)
182 In your drawing | characters (pipe symbol) mark column borders, and
184 - or = (dash or equal sign) characters mark row borders. The +
185 (plus) characters have no special meaning. They're just for candy.
186 For completeness: additionally the ^ _ and ' characters mark
188 horizontal cell borders, since these are special characters
189 controling the vertical alignment of a cell and are placed on the
190 vertical borders of cells.
191 You need at least one - or = character in the top vertical border
193 of each row, otherwise the vertical raster of your table can't be
194 recognized correctly. This should be no problem in practice at all.
195 TAB characters
197 Don't use TAB characters but true SPACE characters inside the
198 table. You get a warning on TAB characters.
199 Whitespace around the table
201 You may have arbitrary whitespace around your table, inlcuding TAB
202 characters. It's cut off before the layout string is parsed.
203
205 Attributes are handled through the common get_ATTR(), set_ATTR() style
206 accessors, but they are mostly passed once to the object constructor
207 and must not be altered after the associated FormFactory was built.
208 layout = SCALAR
210 This is a string which defines the layout of this table using some
211 sort of line art ASCII graphics. Refer to the LAYOUT DEFINITION
212 chapter for details about the format.
213 For more attributes refer to Gtk2::Ex::FormFactory::Container.
215
217 Jörn Reder <joern at zyn dot de>
218
220 Copyright 2004-2006 by Jörn Reder.
221 This library is free software; you can redistribute it and/or modify it
223 under the terms of the GNU Library General Public License as published
224 by the Free Software Foundation; either version 2.1 of the License, or
225 (at your option) any later version.
226 This library is distributed in the hope that it will be useful, but
228 WITHOUT ANY WARRANTY; without even the implied warranty of
229 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
230 Library General Public License for more details.
231 You should have received a copy of the GNU Library General Public
233 License along with this library; if not, write to the Free Software
234 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
235 USA.
236
238 Hey! The above document had some coding errors, which are explained
239 below:
240 Around line 42:
242 =cut found outside a pod block. Skipping to next block.
243 Around line 72:
245 =cut found outside a pod block. Skipping to next block.
246 Around line 413:
248 Non-ASCII character seen before =encoding in '·'. Assuming UTF-8
249perl v5.36.0 2023-01-20 Gtk2::Ex::FormFactory::Table(3)