1form(3) User Contributed Perl Documentation form(3)
2
6 Tk::form - Geometry manager based on attachment rules
7
9 $widget->form?(args)?
10 $widget->formOption?(args)?
12
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 par‐
16 ent window according to attachment rules. The form geometry manager is
17 very flexible and powerful; it can be used to emulate all the existing
18 features of the Tk packer and placer geometry managers (see pack,
19 place). The form method can have any of several forms, depending on
20 Option:
21 $slave->form?(options)?
23 Sets or adjusts the attachment values of the slave window according
24 to the -option=>value argument pairs.
25 -b => attachment
27 Abbreviation for the -bottom option.
28 -bottom => attachment
30 Specifies an attachment for the bottom edge of the slave
31 window. The attachment must specified according to "SPECI‐
32 FYING ATTACHMENTS" below.
33 -bottomspring => weight
35 Specifies the weight of the spring at the bottom edge of
36 the slave window. See "USING SPRINGS" below.
37 -bp => value
39 Abbreviation for the -padbottom option.
40 -bs => weight
42 Abbreviation for the -bottomspring option.
43 -fill => style
45 Specifies the fillings when springs are used for this wid‐
46 get. The value must be x, y, both or none.
47 -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 win‐
52 dow 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 -l => attachment
58 Abbreviation for the -left option.
59 -left => attachment
61 Specifies an attachment for the left edge of the slave win‐
62 dow. The attachment must specified according to "SPECIFYING
63 ATTACHMENTS" below.
64 -leftspring => weight
66 Specifies the weight of the spring at the left edge of the
67 slave window. See "USING SPRINGS" below.
68 -lp => value
70 Abbreviation for the -padleft option.
71 -ls => weight
73 Abbreviation for the -leftspring option.
74 -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 -padleft => value
81 Specifies the amount of external padding to leave on the
82 left side of the slave.
83 -padright => value
85 Specifies the amount of external padding to leave on the
86 right side of the slave.
87 -padtop => value
89 Specifies the amount of external padding to leave on the
90 top side of the slave.
91 -padx => value
93 Specifies the amount of external padding to leave on both
94 the left and the right sides of the slave.
95 -pady => value
97 Specifies the amount of external padding to leave on both
98 the top and the bottom sides of the slave.
99 -r => attachment
101 Abbreviation for the -right option.
102 -right => attachment
104 Specifies an attachment for the right edge of the slave
105 window. The attachment must specified according to "SPECI‐
106 FYING ATTACHMENTS" below.
107 -rightspring => weight
109 Specifies the weight of the spring at the right edge of the
110 slave window. See "USING SPRINGS" below.
111 -rp => value
113 Abbreviation for the -padright option.
114 -rs => weight
116 Abbreviation for the -rightspring option.
117 -t => attachment
119 Abbreviation for the -top option.
120 -top => attachment
122 Specifies an attachment for the top edge of the slave win‐
123 dow. The attachment must specified according to "SPECIFYING
124 ATTACHMENTS" below.
125 -topspring => weight
127 Specifies the weight of the spring at the top edge of the
128 slave window. See "USING SPRINGS" below.
129 -tp => value
131 Abbreviation for the -padtop option.
132 -ts => weight
134 Abbreviation for the -topspring option.
135 $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 $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 $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 $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 $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
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 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 Anchor_point can be given in one of the following forms:
183 Grid Attachment
185 The master window is divided into a number of horizontal and verti‐
186 cal grids. By default the master window is divided into 100x100
187 grids; the number of grids can be adjusted by the formGrid method.
188 A grid attachment anchor point is given by a % sign followed by an
189 integer value. For example, '%0' specifies the first grid line (the
190 top or left edge of the master window). '%100' specifies the last
191 grid line (the bottom or right edge of the master window).
192 Opposite Side Attachment
194 Opposite attachment specifies an anchor point located on the oppo‐
195 site side of another slave widget, which must be managed by form in
196 the same master window. An opposite attachment anchor point is
197 given by the name of another widget. For example,
198 "$b->form(-top=>[$a,0])" attaches the top side of the widget $b to
199 the bottom of the widget $a.
200 Parallel Side Attachment
202 Opposite attachment specifies an anchor point located on the same
203 side of another slave widget, which must be managed by form in the
204 same master window. An parallel attachment anchor point is given by
205 the sign & follwed by the name of another widget. For example,
206 "$b->form(-top=>['&',$a,0])" attaches the top side of the widget $b
207 to the top of the widget $a, making the top sides of these two wid‐
208 gets at the same vertical position in their parent window.
209 No Attachment
211 Specifies a side of the slave to be attached to nothing, indicated
212 by the keyword none. When the none anchor point is given, the off‐
213 set must be zero (or not present). When a side of a slave is
214 attached to ['none', 0], the position of this side is calculated by
215 the position of the other side and the natural size of the slave.
216 For example, if a the left side of a widget is attached to ['%0',
217 100], its right side attached to ['none', 0], and the natural size
218 of the widget is 50 pixels, the right side of the widget will be
219 positioned at pixel ['%0', 149]. When both -top and -bottom are
220 attached to none, then by default -top will be attached to ['%0',
221 0]. When both -left and -right are attached to none, then by
222 default -left will be attached to ['%0', 0].
223 Shifting effects can be achieved by specifying a non-zero offset with
225 an anchor point. In the following example, the top side of widget \$b
226 is attached to the bottom of \$a; hence \$b always appears below \$a.
227 Also, the left edge of \$b is attached to the left side of \$a with a
228 10 pixel offest. Therefore, the left edge of \$b is always shifted 10
229 pixels to the right of \$a's left edge:
230 $b->form(-left=>[$a,10], -top=>[$a,0]);
232 ABBREVIATIONS:
234 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 $b->form(-top=>[$a,0], -right=>['%100',0]);
240 $b->form(-top=>[$a], -right=>'%100');
242 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 $b->form(-top=>['%0',10], -bottom=>['%100',0]);
254 $b->form(-top=>10, -bottom=>-0);
256
258 To be written.
259
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 If the attachment of a side of the slave is grid attachment, the posi‐
265 tion of the side is readily determined.
266 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 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
279 The algorithm of form will fail if a circular dependency exists in the
280 attachments of the slaves. For example:
281 $c->form(-left=>$b);
283 $b->form(-right=>$c);
285 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 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' attach‐
295 ments. Also, unlike the Motif Form manager widget, form defines circu‐
296 lar dependency as ``dependency in the same dimension''. Therefore, the
297 following code fragment will does not have circular dependency because
298 the two widgets do not depend on each other in the same dimension ($b
299 depends $c in the horizontal dimension and $c depends on $b in the ver‐
300 tical dimension):
301 $b->form(-left=>$c);
303 $c->form(-top=>$b);
305
307 Springs have not been fully implemented yet.
308
310 Tk::grid Tk::pack Tk::place
311
313 geometry manager, form, attachment, spring, propagation, size, pack,
314 tix, master, slave
315perl v5.8.8 2008-02-05 form(3)