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