| 1 | '\" |
| 2 | '\" Copyright (c) 1996 Sun Microsystems, Inc. |
| 3 | '\" |
| 4 | '\" See the file "license.terms" for information on usage and redistribution |
| 5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| 6 | '\" |
| 7 | '\" RCS: @(#) $Id: grid.n,v 1.5.4.3 2004/10/29 07:52:08 dkf Exp $ |
| 8 | '\" |
| 9 | '\" The definitions below are for supplemental macros used in Tcl/Tk |
| 10 | '\" manual entries. |
| 11 | '\" |
| 12 | '\" .AP type name in/out ?indent? |
| 13 | '\" Start paragraph describing an argument to a library procedure. |
| 14 | '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| 15 | '\" or "in/out" to describe whether procedure reads or modifies arg, |
| 16 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| 17 | '\" needed; use .AS below instead) |
| 18 | '\" |
| 19 | '\" .AS ?type? ?name? |
| 20 | '\" Give maximum sizes of arguments for setting tab stops. Type and |
| 21 | '\" name are examples of largest possible arguments that will be passed |
| 22 | '\" to .AP later. If args are omitted, default tab stops are used. |
| 23 | '\" |
| 24 | '\" .BS |
| 25 | '\" Start box enclosure. From here until next .BE, everything will be |
| 26 | '\" enclosed in one large box. |
| 27 | '\" |
| 28 | '\" .BE |
| 29 | '\" End of box enclosure. |
| 30 | '\" |
| 31 | '\" .CS |
| 32 | '\" Begin code excerpt. |
| 33 | '\" |
| 34 | '\" .CE |
| 35 | '\" End code excerpt. |
| 36 | '\" |
| 37 | '\" .VS ?version? ?br? |
| 38 | '\" Begin vertical sidebar, for use in marking newly-changed parts |
| 39 | '\" of man pages. The first argument is ignored and used for recording |
| 40 | '\" the version when the .VS was added, so that the sidebars can be |
| 41 | '\" found and removed when they reach a certain age. If another argument |
| 42 | '\" is present, then a line break is forced before starting the sidebar. |
| 43 | '\" |
| 44 | '\" .VE |
| 45 | '\" End of vertical sidebar. |
| 46 | '\" |
| 47 | '\" .DS |
| 48 | '\" Begin an indented unfilled display. |
| 49 | '\" |
| 50 | '\" .DE |
| 51 | '\" End of indented unfilled display. |
| 52 | '\" |
| 53 | '\" .SO |
| 54 | '\" Start of list of standard options for a Tk widget. The |
| 55 | '\" options follow on successive lines, in four columns separated |
| 56 | '\" by tabs. |
| 57 | '\" |
| 58 | '\" .SE |
| 59 | '\" End of list of standard options for a Tk widget. |
| 60 | '\" |
| 61 | '\" .OP cmdName dbName dbClass |
| 62 | '\" Start of description of a specific option. cmdName gives the |
| 63 | '\" option's name as specified in the class command, dbName gives |
| 64 | '\" the option's name in the option database, and dbClass gives |
| 65 | '\" the option's class in the option database. |
| 66 | '\" |
| 67 | '\" .UL arg1 arg2 |
| 68 | '\" Print arg1 underlined, then print arg2 normally. |
| 69 | '\" |
| 70 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| 71 | '\" |
| 72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| 73 | .if t .wh -1.3i ^B |
| 74 | .nr ^l \n(.l |
| 75 | .ad b |
| 76 | '\" # Start an argument description |
| 77 | .de AP |
| 78 | .ie !"\\$4"" .TP \\$4 |
| 79 | .el \{\ |
| 80 | . ie !"\\$2"" .TP \\n()Cu |
| 81 | . el .TP 15 |
| 82 | .\} |
| 83 | .ta \\n()Au \\n()Bu |
| 84 | .ie !"\\$3"" \{\ |
| 85 | \&\\$1 \\fI\\$2\\fP (\\$3) |
| 86 | .\".b |
| 87 | .\} |
| 88 | .el \{\ |
| 89 | .br |
| 90 | .ie !"\\$2"" \{\ |
| 91 | \&\\$1 \\fI\\$2\\fP |
| 92 | .\} |
| 93 | .el \{\ |
| 94 | \&\\fI\\$1\\fP |
| 95 | .\} |
| 96 | .\} |
| 97 | .. |
| 98 | '\" # define tabbing values for .AP |
| 99 | .de AS |
| 100 | .nr )A 10n |
| 101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| 102 | .nr )B \\n()Au+15n |
| 103 | .\" |
| 104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| 105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| 106 | .. |
| 107 | .AS Tcl_Interp Tcl_CreateInterp in/out |
| 108 | '\" # BS - start boxed text |
| 109 | '\" # ^y = starting y location |
| 110 | '\" # ^b = 1 |
| 111 | .de BS |
| 112 | .br |
| 113 | .mk ^y |
| 114 | .nr ^b 1u |
| 115 | .if n .nf |
| 116 | .if n .ti 0 |
| 117 | .if n \l'\\n(.lu\(ul' |
| 118 | .if n .fi |
| 119 | .. |
| 120 | '\" # BE - end boxed text (draw box now) |
| 121 | .de BE |
| 122 | .nf |
| 123 | .ti 0 |
| 124 | .mk ^t |
| 125 | .ie n \l'\\n(^lu\(ul' |
| 126 | .el \{\ |
| 127 | .\" Draw four-sided box normally, but don't draw top of |
| 128 | .\" box if the box started on an earlier page. |
| 129 | .ie !\\n(^b-1 \{\ |
| 130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 131 | .\} |
| 132 | .el \}\ |
| 133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 134 | .\} |
| 135 | .\} |
| 136 | .fi |
| 137 | .br |
| 138 | .nr ^b 0 |
| 139 | .. |
| 140 | '\" # VS - start vertical sidebar |
| 141 | '\" # ^Y = starting y location |
| 142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| 143 | .de VS |
| 144 | .if !"\\$2"" .br |
| 145 | .mk ^Y |
| 146 | .ie n 'mc \s12\(br\s0 |
| 147 | .el .nr ^v 1u |
| 148 | .. |
| 149 | '\" # VE - end of vertical sidebar |
| 150 | .de VE |
| 151 | .ie n 'mc |
| 152 | .el \{\ |
| 153 | .ev 2 |
| 154 | .nf |
| 155 | .ti 0 |
| 156 | .mk ^t |
| 157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| 158 | .sp -1 |
| 159 | .fi |
| 160 | .ev |
| 161 | .\} |
| 162 | .nr ^v 0 |
| 163 | .. |
| 164 | '\" # Special macro to handle page bottom: finish off current |
| 165 | '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| 166 | '\" # page bottom macro. |
| 167 | .de ^B |
| 168 | .ev 2 |
| 169 | 'ti 0 |
| 170 | 'nf |
| 171 | .mk ^t |
| 172 | .if \\n(^b \{\ |
| 173 | .\" Draw three-sided box if this is the box's first page, |
| 174 | .\" draw two sides but no top otherwise. |
| 175 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 176 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 177 | .\} |
| 178 | .if \\n(^v \{\ |
| 179 | .nr ^x \\n(^tu+1v-\\n(^Yu |
| 180 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| 181 | .\} |
| 182 | .bp |
| 183 | 'fi |
| 184 | .ev |
| 185 | .if \\n(^b \{\ |
| 186 | .mk ^y |
| 187 | .nr ^b 2 |
| 188 | .\} |
| 189 | .if \\n(^v \{\ |
| 190 | .mk ^Y |
| 191 | .\} |
| 192 | .. |
| 193 | '\" # DS - begin display |
| 194 | .de DS |
| 195 | .RS |
| 196 | .nf |
| 197 | .sp |
| 198 | .. |
| 199 | '\" # DE - end display |
| 200 | .de DE |
| 201 | .fi |
| 202 | .RE |
| 203 | .sp |
| 204 | .. |
| 205 | '\" # SO - start of list of standard options |
| 206 | .de SO |
| 207 | .SH "STANDARD OPTIONS" |
| 208 | .LP |
| 209 | .nf |
| 210 | .ta 5.5c 11c |
| 211 | .ft B |
| 212 | .. |
| 213 | '\" # SE - end of list of standard options |
| 214 | .de SE |
| 215 | .fi |
| 216 | .ft R |
| 217 | .LP |
| 218 | See the \\fBoptions\\fR manual entry for details on the standard options. |
| 219 | .. |
| 220 | '\" # OP - start of full description for a single option |
| 221 | .de OP |
| 222 | .LP |
| 223 | .nf |
| 224 | .ta 4c |
| 225 | Command-Line Name: \\fB\\$1\\fR |
| 226 | Database Name: \\fB\\$2\\fR |
| 227 | Database Class: \\fB\\$3\\fR |
| 228 | .fi |
| 229 | .IP |
| 230 | .. |
| 231 | '\" # CS - begin code excerpt |
| 232 | .de CS |
| 233 | .RS |
| 234 | .nf |
| 235 | .ta .25i .5i .75i 1i |
| 236 | .. |
| 237 | '\" # CE - end code excerpt |
| 238 | .de CE |
| 239 | .fi |
| 240 | .RE |
| 241 | .. |
| 242 | .de UL |
| 243 | \\$1\l'|0\(ul'\\$2 |
| 244 | .. |
| 245 | .TH grid n 8.4 Tk "Tk Built-In Commands" |
| 246 | .BS |
| 247 | '\" Note: do not modify the .SH NAME line immediately below! |
| 248 | .SH NAME |
| 249 | grid \- Geometry manager that arranges widgets in a grid |
| 250 | .SH SYNOPSIS |
| 251 | \fBgrid \fIoption arg \fR?\fIarg ...\fR? |
| 252 | .BE |
| 253 | |
| 254 | .SH DESCRIPTION |
| 255 | .PP |
| 256 | The \fBgrid\fR command is used to communicate with the grid |
| 257 | geometry manager that arranges widgets in rows and columns inside |
| 258 | of another window, called the geometry master (or master window). |
| 259 | The \fBgrid\fR command can have any of several forms, depending |
| 260 | on the \fIoption\fR argument: |
| 261 | .TP |
| 262 | \fBgrid \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? |
| 263 | If the first argument to \fBgrid\fR is suitable as the first slave |
| 264 | argument to \fBgrid configure\fR, either a window name (any value |
| 265 | starting with \fB.\fP) or one of the characters \fBx\fP or \fB^\fP |
| 266 | (see the \fBRELATIVE PLACEMENT\fR section below), then the command is |
| 267 | processed in the same way as \fBgrid configure\fR. |
| 268 | .TP |
| 269 | \fBgrid bbox \fImaster\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR? |
| 270 | With no arguments, |
| 271 | the bounding box (in pixels) of the grid is returned. |
| 272 | The return value consists of 4 integers. The first two are the pixel |
| 273 | offset from the master window (x then y) of the top-left corner of the |
| 274 | grid, and the second two integers are the width and height of the grid, |
| 275 | also in pixels. If a single \fIcolumn\fP and \fIrow\fP is specified on |
| 276 | the command line, then the bounding box for that cell is returned, where the |
| 277 | top left cell is numbered from zero. If both \fIcolumn\fP and \fIrow\fP |
| 278 | arguments are specified, then the bounding box spanning the rows and columns |
| 279 | indicated is returned. |
| 280 | .TP |
| 281 | \fBgrid columnconfigure \fImaster index \fR?\fI\-option value...\fR? |
| 282 | Query or set the column properties of the \fIindex\fP column of the |
| 283 | geometry master, \fImaster\fP. |
| 284 | .VS 8.4 |
| 285 | The valid options are \fB\-minsize\fP, \fB\-weight\fP, \fB\-uniform\fP |
| 286 | and \fB-pad\fP. |
| 287 | .VE 8.4 |
| 288 | If one or more options are provided, then \fIindex\fP may be given as |
| 289 | a list of column indices to which the configuration options will operate on. |
| 290 | The \fB\-minsize\fP option sets the minimum size, in screen units, |
| 291 | that will be permitted for this column. |
| 292 | The \fB\-weight\fP option (an integer value) |
| 293 | sets the relative weight for apportioning |
| 294 | any extra spaces among |
| 295 | columns. |
| 296 | A weight of zero (0) indicates the column will not deviate from its requested |
| 297 | size. A column whose weight is two will grow at twice the rate as a column |
| 298 | of weight one when extra space is allocated to the layout. |
| 299 | .VS 8.4 |
| 300 | The \fB-uniform\fP option, when a non-empty value is supplied, places |
| 301 | the column in a \fIuniform group\fP with other columns that have the |
| 302 | same value for \fB-uniform\fP. The space for columns belonging to a |
| 303 | uniform group is allocated so that their sizes are always in strict |
| 304 | proportion to their \fB-weight\fP values. See |
| 305 | \fBTHE GRID ALGORITHM\fR below for further details. |
| 306 | .VE 8.4 |
| 307 | The \fB-pad\fP option specifies the number of screen units that will be |
| 308 | added to the largest window contained completely in that column when the |
| 309 | grid geometry manager requests a size from the containing window. |
| 310 | If only an option is specified, with no value, |
| 311 | the current value of that option is returned. |
| 312 | If only the master window and index is specified, all the current settings |
| 313 | are returned in a list of "-option value" pairs. |
| 314 | .TP |
| 315 | \fBgrid configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? |
| 316 | The arguments consist of the names of one or more slave windows |
| 317 | followed by pairs of arguments that specify how |
| 318 | to manage the slaves. |
| 319 | The characters \fB\-\fP, \fBx\fP and \fB^\fP, |
| 320 | can be specified instead of a window name to alter the default |
| 321 | location of a \fIslave\fP, as described in the \fBRELATIVE PLACEMENT\fR |
| 322 | section, below. |
| 323 | The following options are supported: |
| 324 | .RS |
| 325 | .TP |
| 326 | \fB\-column \fIn\fR |
| 327 | Insert the slave so that it occupies the \fIn\fPth column in the grid. |
| 328 | Column numbers start with 0. If this option is not supplied, then the |
| 329 | slave is arranged just to the right of previous slave specified on this |
| 330 | call to \fIgrid\fP, or column "0" if it is the first slave. For each |
| 331 | \fBx\fP that immediately precedes the \fIslave\fP, the column position |
| 332 | is incremented by one. Thus the \fBx\fP represents a blank column |
| 333 | for this row in the grid. |
| 334 | .TP |
| 335 | \fB\-columnspan \fIn\fR |
| 336 | Insert the slave so that it occupies \fIn\fP columns in the grid. |
| 337 | The default is one column, unless the window name is followed by a |
| 338 | \fB\-\fP, in which case the columnspan is incremented once for each immediately |
| 339 | following \fB\-\fP. |
| 340 | .TP |
| 341 | \fB\-in \fIother\fR |
| 342 | Insert the slave(s) in the master |
| 343 | window given by \fIother\fR. The default is the first slave's |
| 344 | parent window. |
| 345 | .TP |
| 346 | \fB\-ipadx \fIamount\fR |
| 347 | The \fIamount\fR specifies how much horizontal internal padding to |
| 348 | leave on each side of the slave(s). This is space is added |
| 349 | inside the slave(s) border. |
| 350 | The \fIamount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. |
| 351 | It defaults to 0. |
| 352 | .TP |
| 353 | \fB\-ipady \fIamount\fR |
| 354 | The \fIamount\fR specifies how much vertical internal padding to |
| 355 | leave on the top and bottom of the slave(s). |
| 356 | This space is added inside the slave(s) border. |
| 357 | The \fIamount\fR defaults to 0. |
| 358 | .TP |
| 359 | \fB\-padx \fIamount\fR |
| 360 | The \fIamount\fR specifies how much horizontal external padding to |
| 361 | leave on each side of the slave(s), in screen units. |
| 362 | \fIAmount\fR may be a list |
| 363 | of two values to specify padding for left and right separately. |
| 364 | The \fIamount\fR defaults to 0. |
| 365 | This space is added outside the slave(s) border. |
| 366 | .TP |
| 367 | \fB\-pady \fIamount\fR |
| 368 | The \fIamount\fR specifies how much vertical external padding to |
| 369 | leave on the top and bottom of the slave(s), in screen units. |
| 370 | \fIAmount\fR may be a list |
| 371 | of two values to specify padding for top and bottom separately. |
| 372 | The \fIamount\fR defaults to 0. |
| 373 | This space is added outside the slave(s) border. |
| 374 | .TP |
| 375 | \fB\-row \fIn\fR |
| 376 | Insert the slave so that it occupies the \fIn\fPth row in the grid. |
| 377 | Row numbers start with 0. If this option is not supplied, then the |
| 378 | slave is arranged on the same row as the previous slave specified on this |
| 379 | call to \fBgrid\fP, or the first unoccupied row if this is the first slave. |
| 380 | .TP |
| 381 | \fB\-rowspan \fIn\fR |
| 382 | Insert the slave so that it occupies \fIn\fP rows in the grid. |
| 383 | The default is one row. If the next \fBgrid\fP command contains |
| 384 | \fB^\fP characters instead of \fIslaves\fP that line up with the columns |
| 385 | of this \fIslave\fP, then the \fBrowspan\fP of this \fIslave\fP is |
| 386 | extended by one. |
| 387 | .TP |
| 388 | \fB\-sticky \fIstyle\fR |
| 389 | If a slave's cell is larger than its requested dimensions, this |
| 390 | option may be used to position (or stretch) the slave within its cell. |
| 391 | \fIStyle\fR is a string that contains zero or more of the characters |
| 392 | \fBn\fP, \fBs\fP, \fBe\fP or \fBw\fP. |
| 393 | The string can optionally contains spaces or |
| 394 | commas, but they are ignored. Each letter refers to a side (north, south, |
| 395 | east, or west) that the slave will "stick" to. If both \fBn\fP and \fBs\fP (or |
| 396 | \fBe\fP and \fBw\fP) are specified, the slave will be stretched to fill the entire |
| 397 | height (or width) of its cavity. The \fBsticky\fP option subsumes the |
| 398 | combination of \fB\-anchor\fP and \fB\-fill\fP that is used by \fBpack\fP. |
| 399 | The default is \fB{}\fP, which causes the slave to be centered in its cavity, |
| 400 | at its requested size. |
| 401 | .LP |
| 402 | If any of the slaves are already managed by the geometry manager |
| 403 | then any unspecified options for them retain their previous values rather |
| 404 | than receiving default values. |
| 405 | .RE |
| 406 | .TP |
| 407 | \fBgrid forget \fIslave \fR?\fIslave ...\fR? |
| 408 | Removes each of the \fIslave\fRs from grid for its |
| 409 | master and unmaps their windows. |
| 410 | The slaves will no longer be managed by the grid geometry manager. |
| 411 | The configuration options for that window are forgotten, so that if the |
| 412 | slave is managed once more by the grid geometry manager, the initial |
| 413 | default settings are used. |
| 414 | .TP |
| 415 | \fBgrid info \fIslave\fR |
| 416 | Returns a list whose elements are the current configuration state of |
| 417 | the slave given by \fIslave\fR in the same option-value form that |
| 418 | might be specified to \fBgrid configure\fR. |
| 419 | The first two elements of the list are ``\fB\-in \fImaster\fR'' where |
| 420 | \fImaster\fR is the slave's master. |
| 421 | .TP |
| 422 | \fBgrid location \fImaster x y\fR |
| 423 | Given \fIx\fP and \fIy\fP values in screen units relative to the master window, |
| 424 | the column and row number at that \fIx\fP and \fIy\fP location is returned. |
| 425 | For locations that are above or to the left of the grid, \fB-1\fP is returned. |
| 426 | .TP |
| 427 | \fBgrid propagate \fImaster\fR ?\fIboolean\fR? |
| 428 | If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR |
| 429 | then propagation is enabled for \fImaster\fR, which must be a window |
| 430 | name (see \fBGEOMETRY PROPAGATION\fR below). |
| 431 | If \fIboolean\fR has a false boolean value then propagation is |
| 432 | disabled for \fImaster\fR. |
| 433 | In either of these cases an empty string is returned. |
| 434 | If \fIboolean\fR is omitted then the command returns \fB0\fR or |
| 435 | \fB1\fR to indicate whether propagation is currently enabled |
| 436 | for \fImaster\fR. |
| 437 | Propagation is enabled by default. |
| 438 | .TP |
| 439 | \fBgrid rowconfigure \fImaster index \fR?\fI\-option value...\fR? |
| 440 | Query or set the row properties of the \fIindex\fP row of the |
| 441 | geometry master, \fImaster\fP. |
| 442 | .VS 8.4 |
| 443 | The valid options are \fB\-minsize\fP, \fB\-weight\fP, \fB\-uniform\fP |
| 444 | and \fB-pad\fP. |
| 445 | .VE 8.4 |
| 446 | If one or more options are provided, then \fIindex\fP may be given as |
| 447 | a list of row indices to which the configuration options will operate on. |
| 448 | The \fB\-minsize\fP option sets the minimum size, in screen units, |
| 449 | that will be permitted for this row. |
| 450 | The \fB\-weight\fP option (an integer value) |
| 451 | sets the relative weight for apportioning |
| 452 | any extra spaces among |
| 453 | rows. |
| 454 | A weight of zero (0) indicates the row will not deviate from its requested |
| 455 | size. A row whose weight is two will grow at twice the rate as a row |
| 456 | of weight one when extra space is allocated to the layout. |
| 457 | .VS 8.4 |
| 458 | The \fB-uniform\fP option, when a non-empty value is supplied, places |
| 459 | the row in a \fIuniform group\fP with other rows that have the |
| 460 | same value for \fB-uniform\fP. The space for rows belonging to a |
| 461 | uniform group is allocated so that their sizes are always in strict |
| 462 | proportion to their \fB-weight\fP values. See |
| 463 | \fBTHE GRID ALGORITHM\fR below for further details. |
| 464 | .VE 8.4 |
| 465 | The \fB-pad\fP option specifies the number of screen units that will be |
| 466 | added to the largest window contained completely in that row when the |
| 467 | grid geometry manager requests a size from the containing window. |
| 468 | If only an option is specified, with no value, |
| 469 | the current value of that option is returned. |
| 470 | If only the master window and index is specified, all the current settings |
| 471 | are returned in a list of "-option value" pairs. |
| 472 | .TP |
| 473 | \fBgrid remove \fIslave \fR?\fIslave ...\fR? |
| 474 | Removes each of the \fIslave\fRs from grid for its |
| 475 | master and unmaps their windows. |
| 476 | The slaves will no longer be managed by the grid geometry manager. |
| 477 | However, the configuration options for that window are remembered, |
| 478 | so that if the |
| 479 | slave is managed once more by the grid geometry manager, the previous |
| 480 | values are retained. |
| 481 | .TP |
| 482 | \fBgrid size \fImaster\fR |
| 483 | Returns the size of the grid (in columns then rows) for \fImaster\fP. |
| 484 | The size is determined either by the \fIslave\fP occupying the largest |
| 485 | row or column, or the largest column or row with a \fBminsize\fP, |
| 486 | \fBweight\fP, or \fBpad\fP that is non-zero. |
| 487 | .TP |
| 488 | \fBgrid slaves \fImaster\fR ?\fI\-option value\fR? |
| 489 | If no options are supplied, a list of all of the slaves in \fImaster\fR |
| 490 | are returned, most recently manages first. |
| 491 | \fIOption\fP can be either \fB\-row\fP or \fB\-column\fP which |
| 492 | causes only the slaves in the row (or column) specified by \fIvalue\fP |
| 493 | to be returned. |
| 494 | .SH "RELATIVE PLACEMENT" |
| 495 | .PP |
| 496 | The \fBgrid\fP command contains a limited set of capabilities that |
| 497 | permit layouts to be created without specifying the row and column |
| 498 | information for each slave. This permits slaves to be rearranged, |
| 499 | added, or removed without the need to explicitly specify row and |
| 500 | column information. |
| 501 | When no column or row information is specified for a \fIslave\fP, |
| 502 | default values are chosen for |
| 503 | \fBcolumn\fP, \fBrow\fP, \fBcolumnspan\fP and \fBrowspan\fP |
| 504 | at the time the \fIslave\fP is managed. The values are chosen |
| 505 | based upon the current layout of the grid, the position of the \fIslave\fP |
| 506 | relative to other \fIslave\fPs in the same grid command, and the presence |
| 507 | of the characters \fB\-\fP, \fBx\fP, and \fB^\fP in \fBgrid\fP |
| 508 | command where \fIslave\fP names are normally expected. |
| 509 | .RS |
| 510 | .TP |
| 511 | \fB\-\fP |
| 512 | This increases the columnspan of the \fIslave\fP to the left. Several |
| 513 | \fB\-\fP's in a row will successively increase the columnspan. A \fB\-\fP |
| 514 | may not follow a \fB^\fP or a \fBx\fP, nor may it be the first \fIslave\fP |
| 515 | argument to \fBgrid configure\fR. |
| 516 | .TP |
| 517 | \fBx\fP |
| 518 | This leaves an empty column between the \fIslave\fP on the left and |
| 519 | the \fIslave\fP on the right. |
| 520 | .TP |
| 521 | \fB^\fP |
| 522 | This extends the \fBrowspan\fP of the \fIslave\fP above the \fB^\fP's |
| 523 | in the grid. The number of \fB^\fP's in a row must match the number of |
| 524 | columns spanned by the \fIslave\fP above it. |
| 525 | .RE |
| 526 | .SH "THE GRID ALGORITHM" |
| 527 | .PP |
| 528 | The grid geometry manager lays out its slaves in three steps. |
| 529 | In the first step, the minimum size needed to fit all of the slaves |
| 530 | is computed, then (if propagation is turned on), a request is made |
| 531 | of the master window to become that size. |
| 532 | In the second step, the requested size is compared against the actual size |
| 533 | of the master. If the sizes are different, then spaces is added to or taken |
| 534 | away from the layout as needed. |
| 535 | For the final step, each slave is positioned in its row(s) and column(s) |
| 536 | based on the setting of its \fIsticky\fP flag. |
| 537 | .PP |
| 538 | To compute the minimum size of a layout, the grid geometry manager |
| 539 | first looks at all slaves whose columnspan and rowspan values are one, |
| 540 | and computes the nominal size of each row or column to be either the |
| 541 | \fIminsize\fP for that row or column, or the sum of the \fIpad\fPding |
| 542 | plus the size of the largest slave, whichever is greater. After that |
| 543 | the rows or columns in each uniform group adapt to each other. Then |
| 544 | the slaves whose rowspans or columnspans are greater than one are |
| 545 | examined. If a group of rows or columns need to be increased in size |
| 546 | in order to accommodate these slaves, then extra space is added to each |
| 547 | row or column in the group according to its \fIweight\fP. For each |
| 548 | group whose weights are all zero, the additional space is apportioned |
| 549 | equally. |
| 550 | .PP |
| 551 | When multiple rows or columns belong to a uniform group, the space |
| 552 | allocated to them is always in proportion to their weights. (A weight |
| 553 | of zero is considered to be 1.) In other words, a row or column |
| 554 | configured with \fB-weight 1 -uniform a\fP will have exactly the same |
| 555 | size as any other row or column configured with \fB-weight 1 -uniform |
| 556 | a\fP. A row or column configured with \fB-weight 2 -uniform b\fR will |
| 557 | be exactly twice as large as one that is configured with \fB-weight 1 |
| 558 | -uniform b\fP. |
| 559 | .PP |
| 560 | More technically, each row or column in the group will have a size |
| 561 | equal to \fIk*weight\fP for some constant \fIk\fP. The constant |
| 562 | \fIk\fP is chosen so that no row or column becomes smaller than its |
| 563 | minimum size. For example, if all rows or columns in a group have the |
| 564 | same weight, then each row or column will have the same size as the |
| 565 | largest row or column in the group. |
| 566 | .PP |
| 567 | For masters whose size is larger than the requested layout, the additional |
| 568 | space is apportioned according to the row and column weights. If all of |
| 569 | the weights are zero, the layout is centered within its master. |
| 570 | For masters whose size is smaller than the requested layout, space is taken |
| 571 | away from columns and rows according to their weights. However, once a |
| 572 | column or row shrinks to its minsize, its weight is taken to be zero. |
| 573 | If more space needs to be removed from a layout than would be permitted, as |
| 574 | when all the rows or columns are at their minimum sizes, the layout is |
| 575 | clipped on the bottom and right. |
| 576 | .SH "GEOMETRY PROPAGATION" |
| 577 | .PP |
| 578 | The grid geometry manager normally computes how large a master must be to |
| 579 | just exactly meet the needs of its slaves, and it sets the |
| 580 | requested width and height of the master to these dimensions. |
| 581 | This causes geometry information to propagate up through a |
| 582 | window hierarchy to a top-level window so that the entire |
| 583 | sub-tree sizes itself to fit the needs of the leaf windows. |
| 584 | However, the \fBgrid propagate\fR command may be used to |
| 585 | turn off propagation for one or more masters. |
| 586 | If propagation is disabled then grid will not set |
| 587 | the requested width and height of the master window. |
| 588 | This may be useful if, for example, you wish for a master |
| 589 | window to have a fixed size that you specify. |
| 590 | .SH "RESTRICTIONS ON MASTER WINDOWS" |
| 591 | .PP |
| 592 | The master for each slave must either be the slave's parent |
| 593 | (the default) or a descendant of the slave's parent. |
| 594 | This restriction is necessary to guarantee that the |
| 595 | slave can be placed over any part of its master that is |
| 596 | visible without danger of the slave being clipped by its parent. |
| 597 | In addition, all slaves in one call to \fBgrid\fP must have the same master. |
| 598 | .SH "STACKING ORDER" |
| 599 | .PP |
| 600 | If the master for a slave is not its parent then you must make sure |
| 601 | that the slave is higher in the stacking order than the master. |
| 602 | Otherwise the master will obscure the slave and it will appear as |
| 603 | if the slave hasn't been managed correctly. |
| 604 | The easiest way to make sure the slave is higher than the master is |
| 605 | to create the master window first: the most recently created window |
| 606 | will be highest in the stacking order. |
| 607 | .SH CREDITS |
| 608 | .PP |
| 609 | The \fBgrid\fP command is based on ideas taken from the \fIGridBag\fP |
| 610 | geometry manager written by Doug. Stein, and the \fBblt_table\fR geometry |
| 611 | manager, written by George Howlett. |
| 612 | .SH EXAMPLES |
| 613 | A toplevel window containing a text widget and two scrollbars: |
| 614 | .CS |
| 615 | # Make the widgets |
| 616 | toplevel .t |
| 617 | text .t.txt \-wrap none \-xscroll {.t.h set} \-yscroll {.t.v set} |
| 618 | scrollbar .t.v \-orient vertical \-command {.t.txt xview} |
| 619 | scrollbar .t.h \-orient horizontal \-command {.t.txt xview} |
| 620 | # Lay them out |
| 621 | \fBgrid\fR .t.txt .t.v \-sticky nsew |
| 622 | \fBgrid\fR .t.h \-sticky nsew |
| 623 | # Tell the text widget to take all the extra room |
| 624 | \fBgrid rowconfigure\fR .t 0 \-weight 1 |
| 625 | \fBgrid columnconfigure\fR .t 0 \-weight 1 |
| 626 | .CE |
| 627 | .PP |
| 628 | Three widgets of equal width, despite their different "natural" widths: |
| 629 | .CS |
| 630 | button .b \-text "Foo" |
| 631 | entry .e \-variable foo |
| 632 | label .l \-text "This is a fairly long piece of text" |
| 633 | \fBgrid\fR .b .e .l \-sticky ew |
| 634 | \fBgrid columnconfigure\fR . {0 1 2} \-uniform allTheSame |
| 635 | .CE |
| 636 | |
| 637 | .SH "SEE ALSO" |
| 638 | pack(n), place(n) |
| 639 | |
| 640 | .SH KEYWORDS |
| 641 | geometry manager, location, grid, cell, propagation, size, pack |