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 first unoccupied row if this is the first slave.
135 -rowspan n
137 Insert the slave so that it occupies n rows in the grid.
138 The default is one row. If the next grid command con‐
139 tains ^ characters instead of slaves that line up with
140 the columns of this slave, then the rowspan of this slave
141 is extended by one.
142 -sticky style
144 If a slave's cell is larger than its requested dimen‐
145 sions, this option may be used to position (or stretch)
146 the slave within its cell. Style is a string that con‐
147 tains zero or more of the characters n, s, e or w. The
148 string can optionally contains spaces or commas, but they
149 are ignored. Each letter refers to a side (north, south,
150 east, or west) that the slave will “stick” to. If both n
151 and s (or e and w) are specified, the slave will be
152 stretched to fill the entire height (or width) of its
153 cavity. The sticky option subsumes the combination of
154 -anchor and -fill that is used by pack. The default is
155 “”, which causes the slave to be centered in its cavity,
156 at its requested size.
157 If any of the slaves are already managed by the geometry manager
159 then any unspecified options for them retain their previous val‐
160 ues rather than receiving default values.
161 grid forget slave ?slave ...?
163 Removes each of the slaves from grid for its master and unmaps
164 their windows. The slaves will no longer be managed by the grid
165 geometry manager. The configuration options for that window are
166 forgotten, so that if the slave is managed once more by the grid
167 geometry manager, the initial default settings are used.
168 grid info slave
170 Returns a list whose elements are the current configuration
171 state of the slave given by slave in the same option-value form
172 that might be specified to grid configure. The first two ele‐
173 ments of the list are “-in master” where master is the slave's
174 master.
175 grid location master x y
177 Given x and y values in screen units relative to the master
178 window, the column and row number at that x and y location is
179 returned. For locations that are above or to the left of the
180 grid, -1 is returned.
181 grid propagate master ?boolean?
183 If boolean has a true boolean value such as 1 or on then propa‐
184 gation is enabled for master, which must be a window name (see
185 GEOMETRY PROPAGATION below). If boolean has a false boolean
186 value then propagation is disabled for master. In either of
187 these cases an empty string is returned. If boolean is omitted
188 then the command returns 0 or 1 to indicate whether propagation
189 is currently enabled for master. Propagation is enabled by
190 default.
191 grid rowconfigure master index ?-option value...?
193 Query or set the row properties of the index row of the geometry
194 master, master. The valid options are -minsize, -weight, -uni‐
195 form and -pad. If one or more options are provided, then index
196 may be given as a list of row indices to which the configuration
197 options will operate on. Indices may be integers, window names │
198 or the keyword all. For all the options apply to all rows cur‐ │
199 rently occupied be slave windows. For a window name, that window │
200 must be a slave of this master and the options apply to all rows │
201 currently occupied be the slave. The -minsize option sets the
202 minimum size, in screen units, that will be permitted for this
203 row. The -weight option (an integer value) sets the relative
204 weight for apportioning any extra spaces among rows. A weight
205 of zero (0) indicates the row will not deviate from its
206 requested size. A row whose weight is two will grow at twice
207 the rate as a row of weight one when extra space is allocated to
208 the layout. The -uniform option, when a non-empty value is sup‐
209 plied, places the row in a uniform group with other rows that
210 have the same value for -uniform. The space for rows belonging
211 to a uniform group is allocated so that their sizes are always
212 in strict proportion to their -weight values. See THE GRID
213 ALGORITHM below for further details. The -pad option specifies
214 the number of screen units that will be added to the largest
215 window contained completely in that row when the grid geometry
216 manager requests a size from the containing window. If only an
217 option is specified, with no value, the current value of that
218 option is returned. If only the master window and index is
219 specified, all the current settings are returned in a list of
220 “-option value” pairs.
221 grid remove slave ?slave ...?
223 Removes each of the slaves from grid for its master and unmaps
224 their windows. The slaves will no longer be managed by the grid
225 geometry manager. However, the configuration options for that
226 window are remembered, so that if the slave is managed once more
227 by the grid geometry manager, the previous values are retained.
228 grid size master
230 Returns the size of the grid (in columns then rows) for master.
231 The size is determined either by the slave occupying the largest
232 row or column, or the largest column or row with a minsize,
233 weight, or pad that is non-zero.
234 grid slaves master ?-option value?
236 If no options are supplied, a list of all of the slaves in mas‐
237 ter are returned, most recently manages first. Option can be
238 either -row or -column which causes only the slaves in the row
239 (or column) specified by value to be returned.
240
242 The grid command contains a limited set of capabilities that permit
243 layouts to be created without specifying the row and column information
244 for each slave. This permits slaves to be rearranged, added, or
245 removed without the need to explicitly specify row and column informa‐
246 tion. When no column or row information is specified for a slave,
247 default values are chosen for column, row, columnspan and rowspan at
248 the time the slave is managed. The values are chosen based upon the
249 current layout of the grid, the position of the slave relative to other
250 slaves in the same grid command, and the presence of the characters -,
251 x, and ^ in grid command where slave names are normally expected.
252 - This increases the columnspan of the slave to the left.
254 Several -'s in a row will successively increase the
255 columnspan. A - may not follow a ^ or a x, nor may it be
256 the first slave argument to grid configure.
257 x This leaves an empty column between the slave on the left
259 and the slave on the right.
260 ^ This extends the rowspan of the slave above the ^'s in
262 the grid. The number of ^'s in a row must match the num‐
263 ber of columns spanned by the slave above it.
264
266 The grid geometry manager lays out its slaves in three steps. In the
267 first step, the minimum size needed to fit all of the slaves is com‐
268 puted, then (if propagation is turned on), a request is made of the
269 master window to become that size. In the second step, the requested
270 size is compared against the actual size of the master. If the sizes
271 are different, then spaces is added to or taken away from the layout as
272 needed. For the final step, each slave is positioned in its row(s) and
273 column(s) based on the setting of its sticky flag.
274 To compute the minimum size of a layout, the grid geometry manager
276 first looks at all slaves whose columnspan and rowspan values are one,
277 and computes the nominal size of each row or column to be either the
278 minsize for that row or column, or the sum of the padding plus the size
279 of the largest slave, whichever is greater. After that the rows or
280 columns in each uniform group adapt to each other. Then the slaves
281 whose rowspans or columnspans are greater than one are examined. If a
282 group of rows or columns need to be increased in size in order to
283 accommodate these slaves, then extra space is added to each row or col‐
284 umn in the group according to its weight. For each group whose weights
285 are all zero, the additional space is apportioned equally.
286 When multiple rows or columns belong to a uniform group, the space
288 allocated to them is always in proportion to their weights. (A weight
289 of zero is considered to be 1.) In other words, a row or column con‐
290 figured with -weight 1 -uniform a will have exactly the same size as
291 any other row or column configured with -weight 1 -uniform a. A row or
292 column configured with -weight 2 -uniform b will be exactly twice as
293 large as one that is configured with -weight 1 -uniform b.
294 More technically, each row or column in the group will have a size
296 equal to k*weight for some constant k. The constant k is chosen so
297 that no row or column becomes smaller than its minimum size. For exam‐
298 ple, if all rows or columns in a group have the same weight, then each
299 row or column will have the same size as the largest row or column in
300 the group.
301 For masters whose size is larger than the requested layout, the addi‐ │
303 tional space is apportioned according to the row and column weights. │
304 If all of the weights are zero, the layout is placed within its master │
305 according to the anchor value. For masters whose size is smaller than │
306 the requested layout, space is taken away from columns and rows accord‐ │
307 ing to their weights. However, once a column or row shrinks to its │
308 minsize, its weight is taken to be zero. If more space needs to be │
309 removed from a layout than would be permitted, as when all the rows or │
310 columns are at their minimum sizes, the layout is placed and clipped │
311 according to the anchor value.
312
314 The grid geometry manager normally computes how large a master must be
315 to just exactly meet the needs of its slaves, and it sets the requested
316 width and height of the master to these dimensions. This causes geome‐
317 try information to propagate up through a window hierarchy to a top-
318 level window so that the entire sub-tree sizes itself to fit the needs
319 of the leaf windows. However, the grid propagate command may be used
320 to turn off propagation for one or more masters. If propagation is
321 disabled then grid will not set the requested width and height of the
322 master window. This may be useful if, for example, you wish for a mas‐
323 ter window to have a fixed size that you specify.
324
326 The master for each slave must either be the slave's parent (the
327 default) or a descendant of the slave's parent. This restriction is
328 necessary to guarantee that the slave can be placed over any part of
329 its master that is visible without danger of the slave being clipped by
330 its parent. In addition, all slaves in one call to grid must have the
331 same master.
332
334 If the master for a slave is not its parent then you must make sure
335 that the slave is higher in the stacking order than the master. Other‐
336 wise the master will obscure the slave and it will appear as if the
337 slave has not been managed correctly. The easiest way to make sure the
338 slave is higher than the master is to create the master window first:
339 the most recently created window will be highest in the stacking order.
340
342 The grid command is based on ideas taken from the GridBag geometry man‐
343 ager written by Doug. Stein, and the blt_table geometry manager, writ‐
344 ten by George Howlett.
345
347 A toplevel window containing a text widget and two scrollbars:
348 # Make the widgets
349 toplevel .t
350 text .t.txt -wrap none -xscroll {.t.h set} -yscroll {.t.v set}
351 scrollbar .t.v -orient vertical -command {.t.txt yview}
352 scrollbar .t.h -orient horizontal -command {.t.txt xview}
353 # Lay them out
355 grid .t.txt .t.v -sticky nsew
356 grid .t.h -sticky nsew
357 # Tell the text widget to take all the extra room
359 grid rowconfigure .t .t.txt -weight 1
360 grid columnconfigure .t .t.txt -weight 1
361 Three widgets of equal width, despite their different “natural” widths:
363 button .b -text "Foo"
364 entry .e -variable foo
365 label .l -text "This is a fairly long piece of text"
366 grid .b .e .l -sticky ew
368 grid columnconfigure . "all" -uniform allTheSame
369
371 pack(n), place(n)
372
374 geometry manager, location, grid, cell, propagation, size, pack
375Tk 8.5 grid(n)