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