| 1 | # Copyright (c) 1996 Sun Microsystems, Inc. |
| 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 | # |
| 6 | |
| 7 | =head1 NAME |
| 8 | |
| 9 | Tk::grid - Geometry manager that arranges widgets in a grid |
| 10 | |
| 11 | =for category Tk Geometry Management |
| 12 | |
| 13 | =head1 SYNOPSIS |
| 14 | |
| 15 | S< >I<$widget>-E<gt>B<grid>?(?I<widget> ...,? ?I<arg> ?...>?)? |
| 16 | |
| 17 | S< >I<$widget>-E<gt>B<grid>I<Option>?(I<arg> ?,I<arg> ...?)? |
| 18 | |
| 19 | =head1 DESCRIPTION |
| 20 | |
| 21 | The B<grid> method is used to communicate with the grid |
| 22 | geometry manager that arranges widgets in rows and columns inside |
| 23 | of another window, called the geometry master (or master window). |
| 24 | The B<grid> method can have any of several forms, depending |
| 25 | on the I<option> argument: |
| 26 | |
| 27 | =over 4 |
| 28 | |
| 29 | =item I<$slave>-E<gt>B<grid>(?I<$slave, ...>??, I<options>?) |
| 30 | |
| 31 | The arguments consist of the optional references to more slave windows |
| 32 | followed by pairs of arguments that specify how to manage the slaves. |
| 33 | The characters B<->, B<x> and B<^>, |
| 34 | can be specified instead of a window reference to alter the default |
| 35 | location of a I<$slave>, as described in L<"RELATIVE PLACEMENT">, below. |
| 36 | |
| 37 | If any of the slaves are already managed by the geometry manager |
| 38 | then any unspecified options for them retain their previous values rather |
| 39 | than receiving default values. |
| 40 | |
| 41 | The following options are supported: |
| 42 | |
| 43 | =over 8 |
| 44 | |
| 45 | =item B<-column> => I<n> |
| 46 | |
| 47 | Insert the I<$slave> so that it occupies the I<n>th column in the grid. |
| 48 | Column numbers start with 0. If this option is not supplied, then the |
| 49 | I<$slave> is arranged just to the right of previous slave specified on this |
| 50 | call to B<grid>, or column "0" if it is the first slave. For each |
| 51 | B<x> that immediately precedes the I<$slave>, the column position |
| 52 | is incremented by one. Thus the B<x> represents a blank column |
| 53 | for this row in the grid. |
| 54 | |
| 55 | =item B<-columnspan> => I<n> |
| 56 | |
| 57 | Insert the slave so that it occupies I<n> columns in the grid. |
| 58 | The default is one column, unless the window name is followed by a |
| 59 | B<->, in which case the columnspan is incremented once for each immediately |
| 60 | following B<->. |
| 61 | |
| 62 | =item B<-in> => I<$other> |
| 63 | |
| 64 | Insert the slave(s) in the master |
| 65 | window given by I<$other>. The default is the first slave's |
| 66 | parent window. |
| 67 | |
| 68 | =item B<-ipadx> => I<amount> |
| 69 | |
| 70 | The I<amount> specifies how much horizontal internal padding to |
| 71 | leave on each side of the slave(s). This is space is added |
| 72 | inside the slave(s) border. |
| 73 | The I<amount> must be a valid screen distance, such as B<2> or B<'.5c'>. |
| 74 | It defaults to 0. |
| 75 | |
| 76 | =item B<-ipady> => I<amount> |
| 77 | |
| 78 | The I<amount> specifies how much vertical internal padding to |
| 79 | leave on on the top and bottom of the slave(s). |
| 80 | This space is added inside the slave(s) border. |
| 81 | The I<amount> defaults to 0. |
| 82 | |
| 83 | =item B<-padx> => I<amount> |
| 84 | |
| 85 | The I<amount> specifies how much horizontal external padding to |
| 86 | leave on each side of the slave(s), in screen units. |
| 87 | The I<amount> defaults to 0. |
| 88 | This space is added outside the slave(s) border. |
| 89 | |
| 90 | =item B<-pady> => I<amount> |
| 91 | |
| 92 | The I<amount> specifies how much vertical external padding to |
| 93 | leave on the top and bottom of the slave(s), in screen units. |
| 94 | The I<amount> defaults to 0. |
| 95 | This space is added outside the slave(s) border. |
| 96 | |
| 97 | =item B<-row> => I<n> |
| 98 | |
| 99 | Insert the slave so that it occupies the I<n>th row in the grid. |
| 100 | Row numbers start with 0. If this option is not supplied, then the |
| 101 | slave is arranged on the same row as the previous slave specified on this |
| 102 | call to B<grid>, or the first unoccupied row if this is the first slave. |
| 103 | |
| 104 | =item B<-rowspan> => I<n> |
| 105 | |
| 106 | Insert the slave so that it occupies I<n> rows in the grid. |
| 107 | The default is one row. If the next B<grid> method contains |
| 108 | B<^> characters instead of I<$slave>s that line up with the columns |
| 109 | of this I<$slave>, then the B<rowspan> of this I<$slave> is |
| 110 | extended by one. |
| 111 | |
| 112 | =item B<-sticky> => I<style> |
| 113 | |
| 114 | If a slave's cell is larger than its requested dimensions, this |
| 115 | option may be used to position (or stretch) the slave within its cell. |
| 116 | I<Style> is a string that contains zero or more of the characters |
| 117 | B<n>, B<s>, B<e> or B<w>. |
| 118 | The string can optionally contain spaces or |
| 119 | commas, but they are ignored. Each letter refers to a side (north, south, |
| 120 | east, or west) that the slave will "stick" to. If both B<n> and B<s> (or |
| 121 | B<e> and B<w>) are specified, the slave will be stretched to fill the entire |
| 122 | height (or width) of its cavity. The B<sticky> option subsumes the |
| 123 | combination of B<-anchor> and B<-fill> that is used by L<pack|Tk::pack>. |
| 124 | The default is B<''>, which causes the slave to be centered in its cavity, |
| 125 | at its requested size. |
| 126 | |
| 127 | =back |
| 128 | |
| 129 | =item I<$master>-E<gt>B<gridBbox>(?I<column, row>,? ?I<column2, row2>?) |
| 130 | |
| 131 | With no arguments, |
| 132 | the bounding box (in pixels) of the grid is returned. |
| 133 | The return value consists of 4 integers. The first two are the pixel |
| 134 | offset from the master window (x then y) of the top-left corner of the |
| 135 | grid, and the second two integers are the width and height of the grid, |
| 136 | also in pixels. If a single I<column> and I<row> is specified on |
| 137 | the command line, then the bounding box for that cell is returned, where the |
| 138 | top left cell is numbered from zero. If both I<column> and I<row> |
| 139 | arguments are specified, then the bounding box spanning the rows and columns |
| 140 | indicated is returned. |
| 141 | |
| 142 | =item I<$master>-E<gt>B<gridColumnconfigure>(I<index>?, I<-option>=>I<value, ...>?) |
| 143 | |
| 144 | Query or set the column properties of the I<index> column of the |
| 145 | geometry master, I<$master>. |
| 146 | The valid options are B<-minsize>, B<-weight> and B<-pad>. |
| 147 | If one or more options are provided, then I<index> may be given as |
| 148 | a list of column indices to which the configuration options will operate on. |
| 149 | The B<-minsize> option sets the minimum size, in screen units, |
| 150 | that will be permitted for this column. |
| 151 | The B<-weight> option (an integer value) |
| 152 | sets the relative weight for apportioning |
| 153 | any extra spaces among |
| 154 | columns. |
| 155 | A weight of zero (0) indicates the column will not deviate from its requested |
| 156 | size. A column whose weight is two will grow at twice the rate as a column |
| 157 | of weight one when extra space is allocated to the layout. |
| 158 | The B<-pad> option specifies the number of screen units that will be |
| 159 | added to the largest window contained completely in that column when the |
| 160 | grid geometry manager requests a size from the containing window. |
| 161 | If only an option is specified, with no value, |
| 162 | the current value of that option is returned. |
| 163 | If only the master window and index is specified, all the current settings |
| 164 | are returned in an list of "-option value" pairs. |
| 165 | |
| 166 | =item I<$slave>-E<gt>B<gridConfigure>(?I<$slave, ...>?, I<options>?) |
| 167 | |
| 168 | The same as B<grid> method. |
| 169 | |
| 170 | =item I<$slave>-E<gt>B<gridForget>?(I<$slave, ...>)? |
| 171 | |
| 172 | Removes each of the I<$slave>s from grid for its |
| 173 | master and unmaps their windows. |
| 174 | The slaves will no longer be managed by the grid geometry manager. |
| 175 | The configuration options for that window are forgotten, so that if the |
| 176 | slave is managed once more by the grid geometry manager, the initial |
| 177 | default settings are used. |
| 178 | |
| 179 | =item I<$slave>-E<gt>B<gridInfo> |
| 180 | |
| 181 | Returns a list whose elements are the current configuration state of |
| 182 | the slave given by I<$slave> in the same option-value form that |
| 183 | might be specified to B<gridConfigure>. |
| 184 | The first two elements of the list are ``B<-in>=>I<$master>'' where |
| 185 | I<$master> is the slave's master. |
| 186 | |
| 187 | =item I<$master>-E<gt>B<gridLocation>(I<x, y>) |
| 188 | |
| 189 | Given I<x> and I<y> values in screen units relative to the master window, |
| 190 | the column and row number at that I<x> and I<y> location is returned. |
| 191 | For locations that are above or to the left of the grid, B<-1> is returned. |
| 192 | |
| 193 | =item I<$master>-E<gt>B<gridPropagate>?(I<boolean>)? |
| 194 | |
| 195 | If I<boolean> has a true boolean value such as B<1> or B<on> |
| 196 | then propagation is enabled for I<$master>, which must be a window |
| 197 | name (see L<"GEOMETRY PROPAGATION"> below). |
| 198 | If I<boolean> has a false boolean value then propagation is |
| 199 | disabled for I<$master>. |
| 200 | In either of these cases an empty string is returned. |
| 201 | If I<boolean> is omitted then the method returns B<0> or |
| 202 | B<1> to indicate whether propagation is currently enabled |
| 203 | for I<$master>. |
| 204 | Propagation is enabled by default. |
| 205 | |
| 206 | =item I<$master>-E<gt>B<gridRowconfigure>(I<index>?, I<-option>=>I<value, ...>?) |
| 207 | |
| 208 | Query or set the row properties of the I<index> row of the |
| 209 | geometry master, I<$master>. |
| 210 | The valid options are B<-minsize>, B<-weight> and B<-pad>. |
| 211 | If one or more options are provided, then I<index> may be given as |
| 212 | a list of row indeces to which the configuration options will operate on. |
| 213 | The B<-minsize> option sets the minimum size, in screen units, |
| 214 | that will be permitted for this row. |
| 215 | The B<-weight> option (an integer value) |
| 216 | sets the relative weight for apportioning |
| 217 | any extra spaces among |
| 218 | rows. |
| 219 | A weight of zero (0) indicates the row will not deviate from its requested |
| 220 | size. A row whose weight is two will grow at twice the rate as a row |
| 221 | of weight one when extra space is allocated to the layout. |
| 222 | The B<-pad> option specifies the number of screen units that will be |
| 223 | added to the largest window contained completely in that row when the |
| 224 | grid geometry manager requests a size from the containing window. |
| 225 | If only an option is specified, with no value, |
| 226 | the current value of that option is returned. |
| 227 | If only the master window and index is specified, all the current settings |
| 228 | are returned in an list of "option-value" pairs. |
| 229 | |
| 230 | =item I<$slave>-E<gt>B<gridRemove>?(I<$slave, ...>)? |
| 231 | |
| 232 | Removes each of the I<$slave>s from grid for its |
| 233 | master and unmaps their windows. |
| 234 | The slaves will no longer be managed by the grid geometry manager. |
| 235 | However, the configuration options for that window are remembered, |
| 236 | so that if the |
| 237 | slave is managed once more by the grid geometry manager, the previous |
| 238 | values are retained. |
| 239 | |
| 240 | =item I<$master>-E<gt>B<gridSize> |
| 241 | |
| 242 | Returns the size of the grid (in columns then rows) for I<$master>. |
| 243 | The size is determined either by the I<$slave> occupying the largest |
| 244 | row or column, or the largest column or row with a B<-minsize>, |
| 245 | B<-weight>, or B<-pad> that is non-zero. |
| 246 | |
| 247 | =item I<$master>-E<gt>B<gridSlaves>?(I<-option>=>I<value>)? |
| 248 | |
| 249 | If no options are supplied, a list of all of the slaves in I<$master> |
| 250 | are returned, most recently manages first. |
| 251 | I<-option> can be either B<-row> or B<-column> which |
| 252 | causes only the slaves in the row (or column) specified by I<value> |
| 253 | to be returned. |
| 254 | |
| 255 | =back |
| 256 | |
| 257 | =head1 RELATIVE PLACEMENT |
| 258 | |
| 259 | The B<grid> method contains a limited set of capabilities that |
| 260 | permit layouts to be created without specifying the row and column |
| 261 | information for each slave. This permits slaves to be rearranged, |
| 262 | added, or removed without the need to explicitly specify row and |
| 263 | column information. |
| 264 | When no column or row information is specified for a I<$slave>, |
| 265 | default values are chosen for |
| 266 | B<-column>, B<-row>, B<-columnspan> and B<-rowspan> |
| 267 | at the time the I<$slave> is managed. The values are chosen |
| 268 | based upon the current layout of the grid, the position of the I<$slave> |
| 269 | relative to other I<$slave>s in the same grid method, and the presence |
| 270 | of the characters B<->, B<^>, and B<^> in B<grid> |
| 271 | method where I<$slave> names are normally expected. |
| 272 | |
| 273 | =over 4 |
| 274 | |
| 275 | =item B<-> |
| 276 | |
| 277 | This increases the columnspan of the I<$slave> to the left. Several |
| 278 | B<->'s in a row will successively increase the columnspan. A B<-> |
| 279 | may not follow a B<^> or a B<x>. |
| 280 | |
| 281 | =item B<x> |
| 282 | |
| 283 | This leaves an empty column between the I<$slave> on the left and |
| 284 | the I<$slave> on the right. |
| 285 | |
| 286 | =item B<^> |
| 287 | |
| 288 | This extends the B<-rowspan> of the I<$slave> above the B<^>'s |
| 289 | in the grid. The number of B<^>'s in a row must match the number of |
| 290 | columns spanned by the I<$slave> above it. |
| 291 | |
| 292 | =back |
| 293 | |
| 294 | =head1 THE GRID ALGORITHM |
| 295 | |
| 296 | The grid geometry manager lays out its slaves in three steps. |
| 297 | In the first step, the minimum size needed to fit all of the slaves |
| 298 | is computed, then (if propagation is turned on), a request is made |
| 299 | of the master window to become that size. |
| 300 | In the second step, the requested size is compared against the actual size |
| 301 | of the master. If the sizes are different, then space is added to or taken |
| 302 | away from the layout as needed. |
| 303 | For the final step, each slave is positioned in its row(s) and column(s) |
| 304 | based on the setting of its I<sticky> flag. |
| 305 | |
| 306 | To compute the minimum size of a layout, the grid geometry manager |
| 307 | first looks at all slaves whose columnspan and rowspan values are one, |
| 308 | and computes the nominal size of each row or column to be either the |
| 309 | I<minsize> for that row or column, or the sum of the I<pad>ding |
| 310 | plus the size of the largest slave, whichever is greater. Then the |
| 311 | slaves whose rowspans or columnspans are greater than one are |
| 312 | examined. If a group of rows or columns need to be increased in size |
| 313 | in order to accommodate these slaves, then extra space is added to each |
| 314 | row or column in the group according to its I<weight>. For each |
| 315 | group whose weights are all zero, the additional space is apportioned |
| 316 | equally. |
| 317 | |
| 318 | For masters whose size is larger than the requested layout, the additional |
| 319 | space is apportioned according to the row and column weights. If all of |
| 320 | the weights are zero, the layout is centered within its master. |
| 321 | For masters whose size is smaller than the requested layout, space is taken |
| 322 | away from columns and rows according to their weights. However, once a |
| 323 | column or row shrinks to its minsize, its weight is taken to be zero. |
| 324 | If more space needs to be removed from a layout than would be permitted, as |
| 325 | when all the rows or columns are at there minimum sizes, the layout is |
| 326 | clipped on the bottom and right. |
| 327 | |
| 328 | =head1 GEOMETRY PROPAGATION |
| 329 | |
| 330 | The grid geometry manager normally computes how large a master must be to |
| 331 | just exactly meet the needs of its slaves, and it sets the |
| 332 | requested width and height of the master to these dimensions. |
| 333 | This causes geometry information to propagate up through a |
| 334 | window hierarchy to a top-level window so that the entire |
| 335 | sub-tree sizes itself to fit the needs of the leaf windows. |
| 336 | However, the B<gridPropagate> method may be used to |
| 337 | turn off propagation for one or more masters. |
| 338 | If propagation is disabled then grid will not set |
| 339 | the requested width and height of the master window. |
| 340 | This may be useful if, for example, you wish for a master |
| 341 | window to have a fixed size that you specify. |
| 342 | |
| 343 | =head1 RESTRICTIONS ON MASTER WINDOWS |
| 344 | |
| 345 | The master for each slave must either be the slave's parent |
| 346 | (the default) or a descendant of the slave's parent. |
| 347 | This restriction is necessary to guarantee that the |
| 348 | slave can be placed over any part of its master that is |
| 349 | visible without danger of the slave being clipped by its parent. |
| 350 | In addition, all slaves in one call to B<grid> must have the same master. |
| 351 | |
| 352 | =head1 STACKING ORDER |
| 353 | |
| 354 | If the master for a slave is not its parent then you must make sure |
| 355 | that the slave is higher in the stacking order than the master. |
| 356 | Otherwise the master will obscure the slave and it will appear as |
| 357 | if the slave hasn't been managed correctly. |
| 358 | The easiest way to make sure the slave is higher than the master is |
| 359 | to create the master window first: the most recently created window |
| 360 | will be highest in the stacking order. |
| 361 | |
| 362 | =head1 CREDITS |
| 363 | |
| 364 | The B<grid> method is based on ideas taken from the I<GridBag> |
| 365 | geometry manager written by Doug. Stein, and the B<blt_table> geometry |
| 366 | manager, written by George Howlett. |
| 367 | |
| 368 | =head1 SEE ALSO |
| 369 | |
| 370 | L<Tk::form|Tk::form> |
| 371 | L<Tk::pack|Tk::pack> |
| 372 | L<Tk::place|Tk::place> |
| 373 | |
| 374 | =head1 KEYWORDS |
| 375 | |
| 376 | geometry manager, location, grid, cell, propagation, size, pack, |
| 377 | master, slave |
| 378 | |
| 379 | =cut |
| 380 | |