1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
|
# Copyright (c) 1996, Expert Interface Technologies
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
# The file man.macros and some of the macros used by this file are
# copyrighted: (c) 1990 The Regents of the University of California.
# (c) 1994-1995 Sun Microsystems, Inc.
# The license terms of the Tcl/Tk distribution are in the file
# license.tcl.
=head1 NAME
Tk::form - Geometry manager based on attachment rules
=for category Tk Geometry Management
=head1 SYNOPSIS
S< >I<$widget>->B<form>?(I<args>)?
S< >I<$widget>->B<form>I<Option>?(I<args>)?
=head1 DESCRIPTION
The B<form> method is used to communicate with the
B<form> Geometry Manager, a geometry manager that arranges the
geometry of the children in a parent window according to attachment
rules. The B<form> geometry manager is very flexible and
powerful; it can be used to emulate all the existing features of the
Tk packer and placer geometry managers (see L<pack|Tk::pack>,
L<place|Tk::place>).
The B<form> method can have any of several forms,
depending on I<Option>:
=over 4
=item I<$slave>->B<form>?(I<options>)?
Sets or adjusts the attachment values of the slave window
according to the I<-option>=>I<value> argument pairs.
=over 8
=item B<-b> => I<attachment>
Abbreviation for the B<-bottom> option.
=item B<-bottom> => I<attachment>
Specifies an attachment for the bottom edge of the slave window. The
attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below.
=item B<-bottomspring> => I<weight>
Specifies the weight of the spring at the bottom edge of the slave
window. See L<"USING SPRINGS"> below.
=item B<-bp> => I<value>
Abbreviation for the B<-padbottom> option.
=item B<-bs> => I<weight>
Abbreviation for the B<-bottomspring> option.
=item B<-fill> => I<style>
Specifies the fillings when springs are used for this widget. The
value must be B<x>, B<y>, B<both> or B<none>.
=item B<-in> => I<$master>
Places the slave window into the specified I<$master> window. If the slave
was originally in another master window, all attachment values with
respect to the original master window are discarded. Even if the
attachment values are the same as in the original master window, they
need to be specified again. The B<-in> flag, when needed, must appear
as the first flag of I<options>. Otherwise an error is
generated.
=item B<-l> => I<attachment>
Abbreviation for the B<-left> option.
=item B<-left> => I<attachment>
Specifies an attachment for the left edge of the slave window. The
attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below.
=item B<-leftspring> => I<weight>
Specifies the weight of the spring at the left edge of the slave
window. See L<"USING SPRINGS"> below.
=item B<-lp> => I<value>
Abbreviation for the B<-padleft> option.
=item B<-ls> => I<weight>
Abbreviation for the B<-leftspring> option.
=item B<-padbottom> => I<value>
Specifies the amount of external padding to leave on the bottom side
of the slave. The I<value> may have any of the forms acceptable to
B<Tk_GetPixels>.
=item B<-padleft> => I<value>
Specifies the amount of external padding to leave on the left side of
the slave.
=item B<-padright> => I<value>
Specifies the amount of external padding to leave on the right side of
the slave.
=item B<-padtop> => I<value>
Specifies the amount of external padding to leave on the top side of
the slave.
=item B<-padx> => I<value>
Specifies the amount of external padding to leave on both the left and
the right sides of the slave.
=item B<-pady> => I<value>
Specifies the amount of external padding to leave on both the top and
the bottom sides of the slave.
=item B<-r> => I<attachment>
Abbreviation for the B<-right> option.
=item B<-right> => I<attachment>
Specifies an attachment for the right edge of the slave window. The
attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below.
=item B<-rightspring> => I<weight>
Specifies the weight of the spring at the right edge of the slave
window. See L<"USING SPRINGS"> below.
=item B<-rp> => I<value>
Abbreviation for the B<-padright> option.
=item B<-rs> => I<weight>
Abbreviation for the B<-rightspring> option.
=item B<-t> => I<attachment>
Abbreviation for the B<-top> option.
=item B<-top> => I<attachment>
Specifies an attachment for the top edge of the slave window. The
attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below.
=item B<-topspring> => I<weight>
Specifies the weight of the spring at the top edge of the slave
window. See L<"USING SPRINGS"> below.
=item B<-tp> => I<value>
Abbreviation for the B<-padtop> option.
=item B<-ts> => I<weight>
Abbreviation for the B<-topspring> option.
=back
=item I<$master>->B<formCheck>
This method checks whether there is circular dependency in the
attachments of the master's slaves (see L<"CIRCULAR DEPENDENCY"> below).
It returns the Boolean value B<TRUE> if it
discover circular dependency and B<FALSE> otherwise.
=item I<$slave>->B<formForget>
Removes the slave from its master and unmaps its window.
The slave will no longer be managed by form. All attachment values
with respect to its master window are discarded. If another slave
is attached to this slave, then the attachment of the other slave will
be changed to grid attachment based on its geometry.
=item I<$master>->B<formGrid>?(I<x_size, y_size>)?
When I<x_size> and I<y_size> are given, this method returns the
number of grids of the I<$master> window in a pair of integers of the form
(I<x_size, y_size>). When both I<x_size> and I<y_size> are
given, this method changes the number of horizontal and vertical
grids on the master window.
=item I<$slave>->B<formInfo>?(I<-option)>?
Queries the attachment options of a slave window. I<-option> can be
any of the options accepted by the B<form> method. If
I<-option> is given, only the value of that option is returned.
Otherwise, this method returns a list whose elements are the current
configuration state of the slave given in the same I<option-value> form
that might be specified to B<form>. The first two
elements in this list list are "B<-in>=>I<$master>" where
I<$master> is the slave's master window.
=item I<$master>->B<formSlaves>
Returns a list of all of the slaves for the master window. The order
of the slaves in the list is the same as their order in the packing
order. If master has no slaves then an empty string is returned.
=back
=head1 SPECIFYING ATTACHMENTS
One can specify an attachment for each side of a slave window managed
by form. An attachment is specified in the the form "-I<side> =>
[I<anchor_point>, I<offset>]". -I<side> can be one of
B<-top>, B<-bottom>, B<-left> or B<-right>.
I<Offset> is given in screen units (i.e. any of the forms
acceptable to B<Tk_GetPixels>). A positive offset indicates
shifting to a position to the right or bottom of an anchor point. A
negative offset indicates shifting to a position to the left or top of
an anchor point.
I<Anchor_point> can be given in one of the
following forms:
=over 4
=item B<Grid Attachment>
The master window is divided into a number of horizontal and vertical
grids. By default the master window is divided into 100x100 grids; the
number of grids can be adjusted by the B<formGrid> method. A
grid attachment anchor point is given by a B<%> sign followed by an
integer value. For example, B<'%0'> specifies the first grid
line (the top or left edge of the master window). B<'%100'> specifies
the last grid line (the bottom or right edge of the master window).
=item B<Opposite Side Attachment>
Opposite attachment specifies an anchor point located on the
B<opposite> side of another slave widget, which must be managed by
form in the same master window. An opposite attachment anchor point
is given by the name of another widget. For example,
"I<$b>->B<form>(B<-top>=>[I<$a>,0])" attaches the top side of the widget I<$b> to the
bottom of the widget I<$a>.
=item B<Parallel Side Attachment>
Opposite attachment specifies an anchor point located on the
B<same> side of another slave widget, which must be managed by
form in the same master window. An parallel attachment anchor point
is given by the sign B<E<amp>> follwed by the name of another widget.
For example, "I<$b>->B<form>(B<-top>=>['&',I<$a>,0])" attaches the top side of
the widget I<$b> to the top of the widget I<$a>, making
the top sides of these two widgets at the same vertical position
in their parent window.
=item B<No Attachment>
Specifies a side of the slave to be attached to nothing, indicated by
the keyword B<none>. When the B<none> anchor point is given, the
offset must be zero (or not present).
When a side of a slave is attached to B<['none', 0]>, the position
of this side is calculated by the position of the other side and the
natural size of the slave. For example, if a the left side of a
widget is attached to B<['%0', 100]>, its right side attached to
B<['none', 0]>, and the natural size of the widget is B<50> pixels,
the right side of the widget will be positioned at pixel
B<['%0', 149]>.
When both B<-top> and B<-bottom> are attached to B<none>,
then by default B<-top> will be attached to B<['%0', 0]>. When both
B<-left> and B<-right> are attached to none, then by default
B<-left> will be attached to B<['%0', 0]>.
=back
Shifting effects can be achieved by specifying a non-zero offset with
an anchor point. In the following example, the top side of
widget I<\$b> is attached to the bottom of
I<\$a>; hence I<\$b>
always appears below I<\$a>. Also, the left edge of I<\$b>
is attached to the left side of I<\$a> with a 10
pixel offest. Therefore, the left edge of I<\$b> is always
shifted 10 pixels to the right of I<\$a>'s left edge:
S< >I<$b>->B<form>(B<-left>=>[I<$a>,10], B<-top>=>[I<$a>,0]);
=head2 ABBREVIATIONS:
Certain abbreviations can be made on the
attachment specifications: First an offset of zero can be omitted.
Thus, the following two lines are equivalent:
S< >I<$b>->B<form>(B<-top>=>[I<$a>,0], B<-right>=>['%100',0]);
S< >I<$b>->B<form>(B<-top>=>[I<$a>], B<-right>=>'%100');
In the second case, when the anchor point is omitted, the offset must
be given. A default anchor point is chosen according to the value of
the offset. If the anchor point is B<0> or positive, the default
anchor point %0 is used; thus, "I<$b>->B<form>(B<-top>=>15)" attaches the top
edge of I<$b> to a position 15 pixels below the top edge of the
master window. If the anchor point is "B<-0>" or negative, the
default anchor point B<%100> is used; thus, "I<$a>->B<form>(B<-right>=>-2)"
attaches the right edge of I<\$a> to a position 2 pixels to
the left of the master window's right edge. An further example
below shows a method with its equivalent abbreviation.
S< >I<$b>->B<form>(B<-top>=>['%0',10], B<-bottom>=>['%100',0]);
S< >I<$b>->B<form>(B<-top>=>10, B<-bottom>=>-0);
=head1 USING SPRINGS
To be written.
=head1 ALGORITHM OF FORM
B<form> starts with any slave in the list of slaves of the master
window. Then it tries to determine the position of each side of the
slave.
If the attachment of a side of the slave is grid attachment, the
position of the side is readily determined.
If the attachment of this side is B<none>, then form tries to
determine the position of the opposite side first, and then use the
position of the opposite side and the natural size of the slave to
determine the position of this side.
If the attachment is opposite or parallel widget attachments, then
form tries to determine the positions of the other widget first,
and then use the positions of the other widget and the natural size of
the slave determine the position of this side. This recursive
algorithmis carried on until the positions of all slaves are
determined.
=head1 CIRCULAR DEPENDENCY
The algorithm of form will fail if a circular dependency exists in
the attachments of the slaves. For example:
S< >I<$c>->B<form>(B<-left>=>I<$b>);
S< >I<$b>->B<form>(B<-right>=>I<$c>);
In this example, the position of the left side of I<$b> depends on
the right side of I<$c>, which in turn depends on the left side of I<$b>.
When a circular dependency is discovered during the execution of the
form algorithm, form will generate a background error and the
geometry of the slaves are undefined (and will be arbitrary). Notice
that form only executes the algorithm when the specification of the
slaves' attachments is complete. Therefore, it allows intermediate
states of circular dependency during the specification of the slaves'
attachments. Also, unlike the Motif Form manager widget, form
defines circular dependency as
``I<dependency in the same dimension>''.
Therefore, the following code fragment will does not
have circular dependency because the two widgets do not depend on each
other in the same dimension (I<$b> depends I<$c> in the
horizontal dimension and I<$c> depends on I<$b> in the vertical
dimension):
S< >I<$b>->B<form>(B<-left>=>I<$c>);
S< >I<$c>->B<form>(B<-top>=>I<$b>);
=head1 BUGS
Springs have not been fully implemented yet.
=head1 SEE ALSO
L<Tk::grid|Tk::grid>
L<Tk::pack|Tk::pack>
L<Tk::place|Tk::place>
=head1 KEYWORDS
geometry manager, form, attachment, spring, propagation, size, pack,
tix, master, slave
=cut
|