1form(3)               User Contributed Perl Documentation              form(3)
2
3
4

NAME

6       Tk::form - Geometry manager based on attachment rules
7

SYNOPSIS

9           $widget->form?(args)?
10
11           $widget->formOption?(args)?
12

DESCRIPTION

14       The form method is used to communicate with the form Geometry Manager,
15       a geometry manager that arranges the geometry of the children in a
16       parent window according to attachment rules. The form geometry manager
17       is very flexible and powerful; it can be used to emulate all the
18       existing features of the Tk packer and placer geometry managers (see
19       pack, place).  The form method can have any of several forms, depending
20       on Option:
21
22       $slave->form?(options)?
23           Sets or adjusts the attachment values of the slave window according
24           to the -option=>value argument pairs.
25
26           -b => attachment
27                   Abbreviation for the -bottom option.
28
29           -bottom => attachment
30                   Specifies an attachment for the bottom edge of the slave
31                   window. The attachment must specified according to
32                   "SPECIFYING ATTACHMENTS" below.
33
34           -bottomspring => weight
35                   Specifies the weight of the spring at the bottom edge of
36                   the slave window. See "USING SPRINGS" below.
37
38           -bp => value
39                   Abbreviation for the -padbottom option.
40
41           -bs => weight
42                   Abbreviation for the -bottomspring option.
43
44           -fill => style
45                   Specifies the fillings when springs are used for this
46                   widget. The value must be x, y, both or none.
47
48           -in => $master
49                   Places the slave window into the specified $master window.
50                   If the slave was originally in another master window, all
51                   attachment values with respect to the original master
52                   window are discarded. Even if the attachment values are the
53                   same as in the original master window, they need to be
54                   specified again.  The -in flag, when needed, must appear as
55                   the first flag of options. Otherwise an error is generated.
56
57           -l => attachment
58                   Abbreviation for the -left option.
59
60           -left => attachment
61                   Specifies an attachment for the left edge of the slave
62                   window. The attachment must specified according to
63                   "SPECIFYING ATTACHMENTS" below.
64
65           -leftspring => weight
66                   Specifies the weight of the spring at the left edge of the
67                   slave window. See "USING SPRINGS" below.
68
69           -lp => value
70                   Abbreviation for the -padleft option.
71
72           -ls => weight
73                   Abbreviation for the -leftspring option.
74
75           -padbottom => value
76                   Specifies the amount of external padding to leave on the
77                   bottom side of the slave. The value may have any of the
78                   forms acceptable to Tk_GetPixels.
79
80           -padleft => value
81                   Specifies the amount of external padding to leave on the
82                   left side of the slave.
83
84           -padright => value
85                   Specifies the amount of external padding to leave on the
86                   right side of the slave.
87
88           -padtop => value
89                   Specifies the amount of external padding to leave on the
90                   top side of the slave.
91
92           -padx => value
93                   Specifies the amount of external padding to leave on both
94                   the left and the right sides of the slave.
95
96           -pady => value
97                   Specifies the amount of external padding to leave on both
98                   the top and the bottom sides of the slave.
99
100           -r => attachment
101                   Abbreviation for the -right option.
102
103           -right => attachment
104                   Specifies an attachment for the right edge of the slave
105                   window. The attachment must specified according to
106                   "SPECIFYING ATTACHMENTS" below.
107
108           -rightspring => weight
109                   Specifies the weight of the spring at the right edge of the
110                   slave window. See "USING SPRINGS" below.
111
112           -rp  => value
113                   Abbreviation for the -padright option.
114
115           -rs => weight
116                   Abbreviation for the -rightspring option.
117
118           -t => attachment
119                   Abbreviation for the -top option.
120
121           -top => attachment
122                   Specifies an attachment for the top edge of the slave
123                   window. The attachment must specified according to
124                   "SPECIFYING ATTACHMENTS" below.
125
126           -topspring => weight
127                   Specifies the weight of the spring at the top edge of the
128                   slave window. See "USING SPRINGS" below.
129
130           -tp => value
131                   Abbreviation for the -padtop option.
132
133           -ts => weight
134                   Abbreviation for the -topspring option.
135
136       $master->formCheck
137           This method checks whether there is circular dependency in the
138           attachments of the master's slaves (see "CIRCULAR DEPENDENCY"
139           below).  It returns the Boolean value TRUE if it discover circular
140           dependency and FALSE otherwise.
141
142       $slave->formForget
143           Removes the slave from its master and unmaps its window.  The slave
144           will no longer be managed by form. All attachment values with
145           respect to its master window are discarded. If another slave is
146           attached to this slave, then the attachment of the other slave will
147           be changed to grid attachment based on its geometry.
148
149       $master->formGrid?(x_size, y_size)?
150           When x_size and y_size are given, this method returns the number of
151           grids of the $master window in a pair of integers of the form
152           (x_size, y_size). When both x_size and y_size are given, this
153           method changes the number of horizontal and vertical grids on the
154           master window.
155
156       $slave->formInfo?(-option)?
157           Queries the attachment options of a slave window. -option can be
158           any of the options accepted by the form method. If -option is
159           given, only the value of that option is returned.  Otherwise, this
160           method returns a list whose elements are the current configuration
161           state of the slave given in the same option-value form that might
162           be specified to form. The first two elements in this list list are
163           "-in=>$master" where $master is the slave's master window.
164
165       $master->formSlaves
166           Returns a list of all of the slaves for the master window. The
167           order of the slaves in the list is the same as their order in the
168           packing order. If master has no slaves then an empty string is
169           returned.
170

SPECIFYING ATTACHMENTS

172       One can specify an attachment for each side of a slave window managed
173       by form. An attachment is specified in the the form "-side =>
174       [anchor_point, offset]". -side can be one of -top, -bottom, -left or
175       -right.
176
177       Offset is given in screen units (i.e. any of the forms acceptable to
178       Tk_GetPixels).  A positive offset indicates shifting to a position to
179       the right or bottom of an anchor point. A negative offset indicates
180       shifting to a position to the left or top of an anchor point.
181
182       Anchor_point can be given in one of the following forms:
183
184       Grid Attachment
185           The master window is divided into a number of horizontal and
186           vertical grids. By default the master window is divided into
187           100x100 grids; the number of grids can be adjusted by the formGrid
188           method. A grid attachment anchor point is given by a % sign
189           followed by an integer value. For example, '%0' specifies the first
190           grid line (the top or left edge of the master window). '%100'
191           specifies the last grid line (the bottom or right edge of the
192           master window).
193
194       Opposite Side Attachment
195           Opposite attachment specifies an anchor point located on the
196           opposite side of another slave widget, which must be managed by
197           form in the same master window. An opposite attachment anchor point
198           is given by the name of another widget. For example,
199           "$b->form(-top=>[$a,0])" attaches the top side of the widget $b to
200           the bottom of the widget $a.
201
202       Parallel Side Attachment
203           Opposite attachment specifies an anchor point located on the same
204           side of another slave widget, which must be managed by form in the
205           same master window. An parallel attachment anchor point is given by
206           the sign & follwed by the name of another widget.  For example,
207           "$b->form(-top=>['&',$a,0])" attaches the top side of the widget $b
208           to the top of the widget $a, making the top sides of these two
209           widgets at the same vertical position in their parent window.
210
211       No Attachment
212           Specifies a side of the slave to be attached to nothing, indicated
213           by the keyword none. When the none anchor point is given, the
214           offset must be zero (or not present).  When a side of a slave is
215           attached to ['none', 0], the position of this side is calculated by
216           the position of the other side and the natural size of the slave.
217           For example, if a the left side of a widget is attached to ['%0',
218           100], its right side attached to ['none', 0], and the natural size
219           of the widget is 50 pixels, the right side of the widget will be
220           positioned at pixel ['%0', 149].  When both -top and -bottom are
221           attached to none, then by default -top will be attached to ['%0',
222           0]. When both -left and -right are attached to none, then by
223           default -left will be attached to ['%0', 0].
224
225       Shifting effects can be achieved by specifying a non-zero offset with
226       an anchor point. In the following example, the top side of widget \$b
227       is attached to the bottom of \$a; hence \$b always appears below \$a.
228       Also, the left edge of \$b is attached to the left side of \$a with a
229       10 pixel offest.  Therefore, the left edge of \$b is always shifted 10
230       pixels to the right of \$a's left edge:
231
232           $b->form(-left=>[$a,10], -top=>[$a,0]);
233
234   ABBREVIATIONS:
235       Certain abbreviations can be made on the attachment specifications:
236       First an offset of zero can be omitted.  Thus, the following two lines
237       are equivalent:
238
239           $b->form(-top=>[$a,0], -right=>['%100',0]);
240
241           $b->form(-top=>[$a], -right=>'%100');
242
243       In the second case, when the anchor point is omitted, the offset must
244       be given. A default anchor point is chosen according to the value of
245       the offset. If the anchor point is 0 or positive, the default anchor
246       point %0 is used; thus, "$b->form(-top=>15)" attaches the top edge of
247       $b to a position 15 pixels below the top edge of the master window. If
248       the anchor point is "-0" or negative, the default anchor point %100 is
249       used; thus, "$a->form(-right=>-2)" attaches the right edge of \$a to a
250       position 2 pixels to the left of the master window's right edge.  An
251       further example below shows a method with its equivalent abbreviation.
252
253           $b->form(-top=>['%0',10], -bottom=>['%100',0]);
254
255           $b->form(-top=>10, -bottom=>-0);
256

USING SPRINGS

258       To be written.
259

ALGORITHM OF FORM

261       form starts with any slave in the list of slaves of the master window.
262       Then it tries to determine the position of each side of the slave.
263
264       If the attachment of a side of the slave is grid attachment, the
265       position of the side is readily determined.
266
267       If the attachment of this side is none, then form tries to determine
268       the position of the opposite side first, and then use the position of
269       the opposite side and the natural size of the slave to determine the
270       position of this side.
271
272       If the attachment is opposite or parallel widget attachments, then form
273       tries to determine the positions of the other widget first, and then
274       use the positions of the other widget and the natural size of the slave
275       determine the position of this side. This recursive algorithmis carried
276       on until the positions of all slaves are determined.
277

CIRCULAR DEPENDENCY

279       The algorithm of form will fail if a circular dependency exists in the
280       attachments of the slaves. For example:
281
282           $c->form(-left=>$b);
283
284           $b->form(-right=>$c);
285
286       In this example, the position of the left side of $b depends on the
287       right side of $c, which in turn depends on the left side of $b.
288
289       When a circular dependency is discovered during the execution of the
290       form algorithm, form will generate a background error and the geometry
291       of the slaves are undefined (and will be arbitrary). Notice that form
292       only executes the algorithm when the specification of the slaves'
293       attachments is complete.  Therefore, it allows intermediate states of
294       circular dependency during the specification of the slaves'
295       attachments.  Also, unlike the Motif Form manager widget, form defines
296       circular dependency as ``dependency in the same dimension''.
297       Therefore, the following code fragment will does not have circular
298       dependency because the two widgets do not depend on each other in the
299       same dimension ($b depends $c in the horizontal dimension and $c
300       depends on $b in the vertical dimension):
301
302           $b->form(-left=>$c);
303
304           $c->form(-top=>$b);
305

BUGS

307       Springs have not been fully implemented yet.
308

SEE ALSO

310       Tk::grid Tk::pack Tk::place
311

KEYWORDS

313       geometry manager, form, attachment, spring, propagation, size, pack,
314       tix, master, slave
315
316
317
318perl v5.16.3                      2014-06-10                           form(3)
Impressum