| 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 | |