1grid(n) Tk Built-In Commands grid(n)
2______________________________________________________________________________
6
8 grid - Geometry manager that arranges widgets in a grid
9
11 grid option arg ?arg ...?
12______________________________________________________________________________
13
15 The grid command is used to communicate with the grid geometry manager
16 that arranges widgets in rows and columns inside of another window,
17 called the geometry master (or master window). The grid command can
18 have any of several forms, depending on the option argument:
19 grid slave ?slave ...? ?options?
21 If the first argument to grid is suitable as the first slave
22 argument to grid configure, either a window name (any value
23 starting with .) or one of the characters x or ^ (see the RELA‐
24 TIVE PLACEMENT section below), then the command is processed in
25 the same way as grid configure.
26 grid anchor master ?anchor?
28 The anchor value controls how to place the grid within the mas‐
29 ter when no row/column has any weight. See THE GRID ALGORITHM
30 below for further details. The default anchor is nw.
31 grid bbox master ?column row? ?column2 row2?
33 With no arguments, the bounding box (in pixels) of the grid is
34 returned. The return value consists of 4 integers. The first
35 two are the pixel offset from the master window (x then y) of
36 the top-left corner of the grid, and the second two integers are
37 the width and height of the grid, also in pixels. If a single
38 column and row is specified on the command line, then the bound‐
39 ing box for that cell is returned, where the top left cell is
40 numbered from zero. If both column and row arguments are speci‐
41 fied, then the bounding box spanning the rows and columns indi‐
42 cated is returned.
43 grid columnconfigure master index ?-option value...?
45 Query or set the column properties of the index column of the
46 geometry master, master. The valid options are -minsize,
47 -weight, -uniform and -pad. If one or more options are pro‐
48 vided, then index may be given as a list of column indices to
49 which the configuration options will operate on. Indices may be
50 integers, window names or the keyword all. For all the options
51 apply to all columns currently occupied be slave windows. For a
52 window name, that window must be a slave of this master and the
53 options apply to all columns currently occupied be the slave.
54 The -minsize option sets the minimum size, in screen units, that
55 will be permitted for this column. The -weight option (an inte‐
56 ger value) sets the relative weight for apportioning any extra
57 spaces among columns. A weight of zero (0) indicates the column
58 will not deviate from its requested size. A column whose weight
59 is two will grow at twice the rate as a column of weight one
60 when extra space is allocated to the layout. The -uniform
61 option, when a non-empty value is supplied, places the column in
62 a uniform group with other columns that have the same value for
63 -uniform. The space for columns belonging to a uniform group is
64 allocated so that their sizes are always in strict proportion to
65 their -weight values. See THE GRID ALGORITHM below for further
66 details. The -pad option specifies the number of screen units
67 that will be added to the largest window contained completely in
68 that column when the grid geometry manager requests a size from
69 the containing window. If only an option is specified, with no
70 value, the current value of that option is returned. If only
71 the master window and index is specified, all the current set‐
72 tings are returned in a list of “-option value” pairs.
73 grid configure slave ?slave ...? ?options?
75 The arguments consist of the names of one or more slave windows
76 followed by pairs of arguments that specify how to manage the
77 slaves. The characters -, x and ^, can be specified instead of
78 a window name to alter the default location of a slave, as
79 described in the RELATIVE PLACEMENT section, below. The follow‐
80 ing options are supported:
81 -column n
83 Insert the slave so that it occupies the nth column in
84 the grid. Column numbers start with 0. If this option
85 is not supplied, then the slave is arranged just to the
86 right of previous slave specified on this call to grid,
87 or column “0” if it is the first slave. For each x that
88 immediately precedes the slave, the column position is
89 incremented by one. Thus the x represents a blank column
90 for this row in the grid.
91 -columnspan n
93 Insert the slave so that it occupies n columns in the
94 grid. The default is one column, unless the window name
95 is followed by a -, in which case the columnspan is
96 incremented once for each immediately following -.
97 -in other
99 Insert the slave(s) in the master window given by other.
100 The default is the first slave's parent window.
101 -ipadx amount
103 The amount specifies how much horizontal internal padding
104 to leave on each side of the slave(s). This is space is
105 added inside the slave(s) border. The amount must be a
106 valid screen distance, such as 2 or .5c. It defaults to
107 0.
108 -ipady amount
110 The amount specifies how much vertical internal padding
111 to leave on the top and bottom of the slave(s). This
112 space is added inside the slave(s) border. The amount
113 defaults to 0.
114 -padx amount
116 The amount specifies how much horizontal external padding
117 to leave on each side of the slave(s), in screen units.
118 Amount may be a list of two values to specify padding for
119 left and right separately. The amount defaults to 0.
120 This space is added outside the slave(s) border.
121 -pady amount
123 The amount specifies how much vertical external padding
124 to leave on the top and bottom of the slave(s), in screen
125 units. Amount may be a list of two values to specify
126 padding for top and bottom separately. The amount
127 defaults to 0. This space is added outside the slave(s)
128 border.
129 -row n Insert the slave so that it occupies the nth row in the
131 grid. Row numbers start with 0. If this option is not
132 supplied, then the slave is arranged on the same row as
133 the previous slave specified on this call to grid, or the
134 next row after the highest occupied row if this is the
135 first slave.
136 -rowspan n
138 Insert the slave so that it occupies n rows in the grid.
139 The default is one row. If the next grid command con‐
140 tains ^ characters instead of slaves that line up with
141 the columns of this slave, then the rowspan of this slave
142 is extended by one.
143 -sticky style
145 If a slave's cell is larger than its requested dimen‐
146 sions, this option may be used to position (or stretch)
147 the slave within its cell. Style is a string that con‐
148 tains zero or more of the characters n, s, e or w. The
149 string can optionally contains spaces or commas, but they
150 are ignored. Each letter refers to a side (north, south,
151 east, or west) that the slave will “stick” to. If both n
152 and s (or e and w) are specified, the slave will be
153 stretched to fill the entire height (or width) of its
154 cavity. The -sticky option subsumes the combination of
155 -anchor and -fill that is used by pack. The default is
156 “”, which causes the slave to be centered in its cavity,
157 at its requested size.
158 If any of the slaves are already managed by the geometry manager
160 then any unspecified options for them retain their previous val‐
161 ues rather than receiving default values.
162 grid forget slave ?slave ...?
164 Removes each of the slaves from grid for its master and unmaps
165 their windows. The slaves will no longer be managed by the grid
166 geometry manager. The configuration options for that window are
167 forgotten, so that if the slave is managed once more by the grid
168 geometry manager, the initial default settings are used.
169 grid info slave
171 Returns a list whose elements are the current configuration
172 state of the slave given by slave in the same option-value form
173 that might be specified to grid configure. The first two ele‐
174 ments of the list are “-in master” where master is the slave's
175 master.
176 grid location master x y
178 Given x and y values in screen units relative to the master
179 window, the column and row number at that x and y location is
180 returned. For locations that are above or to the left of the
181 grid, -1 is returned.
182 grid propagate master ?boolean?
184 If boolean has a true boolean value such as 1 or on then propa‐
185 gation is enabled for master, which must be a window name (see
186 GEOMETRY PROPAGATION below). If boolean has a false boolean
187 value then propagation is disabled for master. In either of
188 these cases an empty string is returned. If boolean is omitted
189 then the command returns 0 or 1 to indicate whether propagation
190 is currently enabled for master. Propagation is enabled by
191 default.
192 grid rowconfigure master index ?-option value...?
194 Query or set the row properties of the index row of the geometry
195 master, master. The valid options are -minsize, -weight, -uni‐
196 form and -pad. If one or more options are provided, then index
197 may be given as a list of row indices to which the configuration
198 options will operate on. Indices may be integers, window names
199 or the keyword all. For all the options apply to all rows cur‐
200 rently occupied be slave windows. For a window name, that window
201 must be a slave of this master and the options apply to all rows
202 currently occupied be the slave. The -minsize option sets the
203 minimum size, in screen units, that will be permitted for this
204 row. The -weight option (an integer value) sets the relative
205 weight for apportioning any extra spaces among rows. A weight
206 of zero (0) indicates the row will not deviate from its
207 requested size. A row whose weight is two will grow at twice
208 the rate as a row of weight one when extra space is allocated to
209 the layout. The -uniform option, when a non-empty value is sup‐
210 plied, places the row in a uniform group with other rows that
211 have the same value for -uniform. The space for rows belonging
212 to a uniform group is allocated so that their sizes are always
213 in strict proportion to their -weight values. See THE GRID
214 ALGORITHM below for further details. The -pad option specifies
215 the number of screen units that will be added to the largest
216 window contained completely in that row when the grid geometry
217 manager requests a size from the containing window. If only an
218 option is specified, with no value, the current value of that
219 option is returned. If only the master window and index is
220 specified, all the current settings are returned in a list of
221 “-option value” pairs.
222 grid remove slave ?slave ...?
224 Removes each of the slaves from grid for its master and unmaps
225 their windows. The slaves will no longer be managed by the grid
226 geometry manager. However, the configuration options for that
227 window are remembered, so that if the slave is managed once more
228 by the grid geometry manager, the previous values are retained.
229 grid size master
231 Returns the size of the grid (in columns then rows) for master.
232 The size is determined either by the slave occupying the largest
233 row or column, or the largest column or row with a -minsize,
234 -weight, or -pad that is non-zero.
235 grid slaves master ?-option value?
237 If no options are supplied, a list of all of the slaves in mas‐
238 ter are returned, most recently manages first. Option can be
239 either -row or -column which causes only the slaves in the row
240 (or column) specified by value to be returned.
241
243 The grid command contains a limited set of capabilities that permit
244 layouts to be created without specifying the row and column information
245 for each slave. This permits slaves to be rearranged, added, or
246 removed without the need to explicitly specify row and column informa‐
247 tion. When no column or row information is specified for a slave,
248 default values are chosen for -column, -row, -columnspan and -rowspan
249 at the time the slave is managed. The values are chosen based upon the
250 current layout of the grid, the position of the slave relative to other
251 slaves in the same grid command, and the presence of the characters -,
252 x, and ^ in grid command where slave names are normally expected.
253 - This increases the -columnspan of the slave to the left.
255 Several -'s in a row will successively increase the num‐
256 ber of columns spanned. A - may not follow a ^ or a x,
257 nor may it be the first slave argument to grid configure.
258 x This leaves an empty column between the slave on the left
260 and the slave on the right.
261 ^ This extends the -rowspan of the slave above the ^'s in
263 the grid. The number of ^'s in a row must match the num‐
264 ber of columns spanned by the slave above it.
265
267 The grid geometry manager lays out its slaves in three steps. In the
268 first step, the minimum size needed to fit all of the slaves is com‐
269 puted, then (if propagation is turned on), a request is made of the
270 master window to become that size. In the second step, the requested
271 size is compared against the actual size of the master. If the sizes
272 are different, then spaces is added to or taken away from the layout as
273 needed. For the final step, each slave is positioned in its row(s) and
274 column(s) based on the setting of its sticky flag.
275 To compute the minimum size of a layout, the grid geometry manager
277 first looks at all slaves whose -columnspan and -rowspan values are
278 one, and computes the nominal size of each row or column to be either
279 the minsize for that row or column, or the sum of the padding plus the
280 size of the largest slave, whichever is greater. After that the rows
281 or columns in each uniform group adapt to each other. Then the slaves
282 whose row-spans or column-spans are greater than one are examined. If
283 a group of rows or columns need to be increased in size in order to
284 accommodate these slaves, then extra space is added to each row or col‐
285 umn in the group according to its weight. For each group whose weights
286 are all zero, the additional space is apportioned equally.
287 When multiple rows or columns belong to a uniform group, the space
289 allocated to them is always in proportion to their weights. (A weight
290 of zero is considered to be 1.) In other words, a row or column con‐
291 figured with -weight 1 -uniform a will have exactly the same size as
292 any other row or column configured with -weight 1 -uniform a. A row or
293 column configured with -weight 2 -uniform b will be exactly twice as
294 large as one that is configured with -weight 1 -uniform b.
295 More technically, each row or column in the group will have a size
297 equal to k*weight for some constant k. The constant k is chosen so
298 that no row or column becomes smaller than its minimum size. For exam‐
299 ple, if all rows or columns in a group have the same weight, then each
300 row or column will have the same size as the largest row or column in
301 the group.
302 For masters whose size is larger than the requested layout, the addi‐
304 tional space is apportioned according to the row and column weights.
305 If all of the weights are zero, the layout is placed within its master
306 according to the anchor value. For masters whose size is smaller than
307 the requested layout, space is taken away from columns and rows accord‐
308 ing to their weights. However, once a column or row shrinks to its
309 minsize, its weight is taken to be zero. If more space needs to be
310 removed from a layout than would be permitted, as when all the rows or
311 columns are at their minimum sizes, the layout is placed and clipped
312 according to the anchor value.
313
315 The grid geometry manager normally computes how large a master must be
316 to just exactly meet the needs of its slaves, and it sets the requested
317 width and height of the master to these dimensions. This causes geome‐
318 try information to propagate up through a window hierarchy to a top-
319 level window so that the entire sub-tree sizes itself to fit the needs
320 of the leaf windows. However, the grid propagate command may be used
321 to turn off propagation for one or more masters. If propagation is
322 disabled then grid will not set the requested width and height of the
323 master window. This may be useful if, for example, you wish for a mas‐
324 ter window to have a fixed size that you specify.
325
327 The master for each slave must either be the slave's parent (the
328 default) or a descendant of the slave's parent. This restriction is
329 necessary to guarantee that the slave can be placed over any part of
330 its master that is visible without danger of the slave being clipped by
331 its parent. In addition, all slaves in one call to grid must have the
332 same master.
333
335 If the master for a slave is not its parent then you must make sure
336 that the slave is higher in the stacking order than the master. Other‐
337 wise the master will obscure the slave and it will appear as if the
338 slave has not been managed correctly. The easiest way to make sure the
339 slave is higher than the master is to create the master window first:
340 the most recently created window will be highest in the stacking order.
341
343 The grid command is based on ideas taken from the GridBag geometry man‐
344 ager written by Doug. Stein, and the blt_table geometry manager, writ‐
345 ten by George Howlett.
346
348 A toplevel window containing a text widget and two scrollbars:
349 # Make the widgets
351 toplevel .t
352 text .t.txt -wrap none -xscroll {.t.h set} -yscroll {.t.v set}
353 scrollbar .t.v -orient vertical -command {.t.txt yview}
354 scrollbar .t.h -orient horizontal -command {.t.txt xview}
355 # Lay them out
357 grid .t.txt .t.v -sticky nsew
358 grid .t.h -sticky nsew
359 # Tell the text widget to take all the extra room
361 grid rowconfigure .t .t.txt -weight 1
362 grid columnconfigure .t .t.txt -weight 1
363 Three widgets of equal width, despite their different “natural” widths:
365 button .b -text "Foo"
367 entry .e -variable foo
368 label .l -text "This is a fairly long piece of text"
369 grid .b .e .l -sticky ew
371 grid columnconfigure . "all" -uniform allTheSame
372
374 pack(n), place(n)
375
377 geometry manager, location, grid, cell, propagation, size, pack
378Tk 8.5 grid(n)