1grid(n)                      Tk Built-In Commands                      grid(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       grid - Geometry manager that arranges widgets in a grid
9

SYNOPSIS

11       grid option arg ?arg ...?
12______________________________________________________________________________
13

DESCRIPTION

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
20       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
27       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
32       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
44       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
74       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
82              -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
92              -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
98              -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
102              -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
109              -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
115              -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
122              -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
130              -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
137              -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
144              -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
159              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
163       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
170       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
177       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
183       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
193       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
223       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
230       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
236       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

RELATIVE PLACEMENT

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
254              -      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
259              x      This leaves an empty column between the slave on the left
260                     and the slave on the right.
261
262              ^      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

THE GRID ALGORITHM

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
276       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
288       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
296       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
303       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

GEOMETRY PROPAGATION

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

RESTRICTIONS ON MASTER WINDOWS

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

STACKING ORDER

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

CREDITS

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

EXAMPLES

348       A toplevel window containing a text widget and two scrollbars:
349
350              # 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
356              # Lay them out
357              grid .t.txt .t.v -sticky nsew
358              grid .t.h        -sticky nsew
359
360              # 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
364       Three widgets of equal width, despite their different “natural” widths:
365
366              button .b -text "Foo"
367              entry .e -variable foo
368              label .l -text "This is a fairly long piece of text"
369
370              grid .b .e .l -sticky ew
371              grid columnconfigure . "all" -uniform allTheSame
372

SEE ALSO

374       pack(n), place(n)
375

KEYWORDS

377       geometry manager, location, grid, cell, propagation, size, pack
378
379
380
381Tk                                    8.5                              grid(n)
Impressum