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