Commit | Line | Data |
---|---|---|
920dae64 AT |
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 |