NAME
       grid - Geometry manager that arranges widgets in a grid

SYNOPSIS
       grid option arg ?arg ...?


DESCRIPTION
       The  grid  command  is  used  to communicate with the grid
       geometry manager that arranges widgets in rows and columns
       inside  of  another window, called the geometry master (or
       master window).  The grid command can have any of  several
       forms, depending on the option argument:

       grid slave ?slave ...? ?options?
              If the first argument to grid is a window name (any
              value starting with ``.''),  then  the  command  is
              processed in the same way as grid configure.

       grid bbox master ?column row? ?column2 row2?
              With  no arguments, the bounding box (in pixels) of
              the grid is returned.  The return value consists of
              4  integers.   The  first  two are the pixel offset
              from the master window (x then y) of  the  top-left
              corner of the grid, and the second two integers are
              the width and height of the grid, also  in  pixels.
              If a single column and row is specified on the com-
              mand line, then the bounding box for that  cell  is
              returned,  where the top left cell is numbered from
              zero.  If both column and row arguments are  speci-
              fied,  then  the bounding box spanning the rows and
              columns indicated is returned.

       grid columnconfigure master index ?-option value...?
              Query or set the column  properties  of  the  index
              column  of  the geometry master, master.  The valid
              options are -minsize, -weight and -pad.  The  -min-
              size option sets the minimum size, in screen units,
              that  will  be  permitted  for  this  column.   The
              -weight option (an integer value) sets the relative
              weight for  apportioning  any  extra  spaces  among
              columns.  A weight of zero (0) indicates the column
              will not deviate from its requested size.  A column
              whose  weight is two will grow at twice the rate as
              a column of weight one when extra  space  is  allo-
              cated to the layout.  The -pad option specifies the
              number of screen units that will be  added  to  the
              largest  window contained completely in that column
              when the grid geometry manager requests a size from
              the containing window.  If only an option is speci-
              fied, with no value,  the  current  value  of  that
              option  is returned.  If only the master window and
              index is specified, all the  current  settings  are
              returned in an list of "-option value" pairs.
       grid configure slave ?slave ...? ?options?
              The  arguments  consist of the names of one or more
              slave windows followed by pairs of  arguments  that
              specify  how  to manage the slaves.  The characters
              -,  x and ^, can be specified instead of  a  window
              name  to  alter the default location of a slave, as
              described in the  ``RELATIVE  PLACEMENT''  section,
              below.  The following options are supported:

              -column n
                     Insert the slave so that it occupies the nth
                     column in the grid.   Column  numbers  start
                     with  0.   If  this  option is not supplied,
                     then the slave is arranged just to the right
                     of  previous slave specified on this call to
                     grid, or column  "0"  if  it  is  the  first
                     slave.  For each x that immediately precedes
                     the slave, the  column  position  is  incre-
                     mented  by  one.   Thus  the  x represents a
                     blank column for this row in the grid.

              -columnspan n
                     Insert the  slave  so  that  it  occupies  n
                     columns  in  the  grid.   The default is one
                     column, unless the window name  is  followed
                     by  a  -,  in  which  case the columnspan is
                     incremented once for each  immediately  fol-
                     lowing -.

              -in other
                     Insert  the  slave(s)  in  the master window
                     given by other.  The default  is  the  first
                     slave's parent window.

              -ipadx amount
                     The  amount  specifies  how  much horizontal
                     internal padding to leave on  each  side  of
                     the slave(s).  This is space is added inside
                     the slave(s) border.  The amount must  be  a
                     valid screen distance, such as 2 or .5c.  It
                     defaults to 0.

              -ipady amount
                     The  amount  specifies  how  much   vertical
                     internal  padding to leave on on the top and
                     bottom of the slave(s).  This space is added
                     inside  the  slave(s)  border.   The  amount
                     defaults to 0.

              -padx amount
                     The amount  specifies  how  much  horizontal
                     external  padding  to  leave on each side of
                     the slave(s), in screen units.   The  amount
                     defaults  to 0.  This space is added outside
                     the slave(s) border.

              -pady amount
                     The  amount  specifies  how  much   vertical
                     external  padding  to  leave  on the top and
                     bottom of the  slave(s),  in  screen  units.
                     The  amount  defaults  to  0.  This space is
                     added outside the slave(s) border.

              -row n Insert the slave so that it occupies the nth
                     row  in the grid.  Row numbers start with 0.
                     If this option is  not  supplied,  then  the
                     slave  is  arranged  on  the same row as the
                     previous slave specified  on  this  call  to
                     grid, or the first unoccupied row if this is
                     the first slave.

              -rowspan n
                     Insert the slave so that it occupies n  rows
                     in  the  grid.   The default is one row.  If
                     the next grid command contains ^  characters
                     instead  of  slaves  that  line  up with the
                     columns of this slave, then the  rowspan  of
                     this slave is extended by one.

              -sticky style
                     If   a  slave's  cell  is  larger  than  its
                     requested dimensions,  this  option  may  be
                     used  to  position  (or  stretch)  the slave
                     within its cell.  Style  is  a  string  that
                     contains  zero  or more of the characters n,
                     s, e or w.  The string can  optionally  con-
                     tains   spaces   or  commas,  but  they  are
                     ignored.   Each  letter  refers  to  a  side
                     (north, south, east, or west) that the slave
                     will "stick" to.  If both n and s (or e  and
                     w)   are   specified,   the  slave  will  be
                     stretched to  fill  the  entire  height  (or
                     width)  of  its  cavity.   The sticky option
                     subsumes  the  combination  of  -anchor  and
                     -fill  that is used by pack.  The default is
                     {}, which causes the slave to be centered in
                     its cavity, at its requested size.

              If  any  of  the  slaves are already managed by the
              geometry manager then any unspecified  options  for
              them  retain  their  previous  values  rather  than
              receiving default values.

       grid forget slave ?slave ...?
              Removes each of the slaves from grid for its master
              and  unmaps  their  windows.   The  slaves  will no
              longer be managed by  the  grid  geometry  manager.
              The  configuration  options  for  that  window  are
              forgotten, so that if the  slave  is  managed  once
              more  by  the  grid  geometry  manager, the initial
              default settings are used.

       grid info slave
              Returns a list whose elements are the current  con-
              figuration state of the slave given by slave in the
              same option-value form that might be  specified  to
              grid configure.  The first two elements of the list
              are ``-in master'' where master is the slave's mas-
              ter.

       grid location master x y
              Given   x  and y values in screen units relative to
              the master window, the column  and  row  number  at
              that  x  and y location is returned.  For locations
              that are above or to the left of the  grid,  -1  is
              returned.

       grid propagate master ?boolean?
              If boolean has a true boolean value such as 1 or on
              then propagation is enabled for master, which  must
              be  a  window  name  (see  ``GEOMETRY PROPAGATION''
              below).  If boolean has a false boolean value  then
              propagation  is  disabled for master.  In either of
              these  cases  an  empty  string  is  returned.   If
              boolean  is omitted then the command returns 0 or 1
              to  indicate  whether  propagation   is   currently
              enabled  for  master.   Propagation  is  enabled by
              default.

       grid rowconfigure master index ?-option value...?
              Query or set the row properties of the index row of
              the geometry master, master.  The valid options are
              -minsize, -weight and -pad.   The  -minsize  option
              sets  the  minimum size, in screen units, that will
              be permitted for this row.  The -weight option  (an
              integer  value) sets the relative weight for appor-
              tioning any extra spaces among rows.  A  weight  of
              zero  (0)  indicates  the row will not deviate from
              its requested size.  A row whose weight is two will
              grow  at twice the rate as a row of weight one when
              extra space is allocated to the layout.   The  -pad
              option  specifies  the  number of screen units that
              will be added to the largest window contained  com-
              pletely  in that row when the grid geometry manager
              requests a size from  the  containing  window.   If
              only  an  option  is  specified, with no value, the
              current value of that option is returned.  If  only
              the  master  window and index is specified, all the
              current  settings  are  returned  in  an  list   of
              "-option value" pairs.
       grid remove slave ?slave ...?
              Removes each of the slaves from grid for its master
              and unmaps  their  windows.   The  slaves  will  no
              longer  be  managed  by  the grid geometry manager.
              However, the configuration options for that  window
              are  remembered,  so  that  if the slave is managed
              once more by the grid geometry manager, the  previ-
              ous values are retained.

       grid size master
              Returns the size of the grid (in columns then rows)
              for master.  The size is determined either  by  the
              slave  occupying  the largest row or column, or the
              largest column or row with a  minsize,  weight,  or
              pad that is non-zero.

       grid slaves master ?-option value?
              If  no  options  are supplied, a list of all of the
              slaves in master are returned, most  recently  man-
              ages  first.   Option can be either -row or -column
              which causes only the slaves in the row (or column)
              specified by value to be returned.

RELATIVE PLACEMENT
       The  grid  command  contains a limited set of capabilities
       that permit layouts to be created without  specifying  the
       row  and  column information for each slave.  This permits
       slaves to be rearranged, added,  or  removed  without  the
       need  to  explicitly  specify  row and column information.
       When no column or  row  information  is  specified  for  a
       slave,   default   values  are  chosen  for  column,  row,
       columnspan and rowspan at the time the slave  is  managed.
       The values are chosen based upon the current layout of the
       grid, the position of the slave relative to  other  slaves
       in  the same grid command, and the presence of the charac-
       ters -, ^, and ^ in grid command  where  slave  names  are
       normally expected.

              -      This  increases  the columnspan of the slave
                     to the left.  Several -'s in a row will suc-
                     cessively  increase  the columnspan. A - may
                     not follow a ^ or a x.

              x      This leaves  an  empty  column  between  the
                     slave  on  the  left  and  the  slave on the
                     right.

              ^      This extends the rowspan of the slave  above
                     the ^'s in the grid.  The number of ^'s in a
                     row must match the number of columns spanned
                     by the slave above it.

THE GRID ALGORITHM
       The  grid  geometry  manager  lays out its slaves in three
       steps.  In the first step, the minimum size needed to  fit
       all  of  the  slaves  is computed, then (if propagation is
       turned on), a request is made  of  the  master  window  to
       become  that size.  In the second step, the requested size
       is compared against the actual size of the master.  If the
       sizes are different, then spaces is added to or taken away
       from the layout as needed.  For the final step, each slave
       is  positioned  in  its  row(s) and column(s) based on the
       setting of its sticky flag.

       To compute the minimum size of a layout, the grid geometry
       manager  first  looks  at  all slaves whose columnspan and
       rowspan values are one, and computes the nominal  size  of
       each  row  or column to be either the minsize for that row
       or column, or the sum of the padding plus the size of  the
       largest  slave,  whichever  is  greater.   Then the slaves
       whose rowspans or columnspans are  greater  than  one  are
       examined.   If  a  group  of  rows  or  columns need to be
       increased in size in order to  accommodate  these  slaves,
       then  extra  space  is  added to each row or column in the
       group according to  its  weight.   For  each  group  whose
       weights  are all zero, the additional space is apportioned
       equally.

       For masters whose size is larger than the  requested  lay-
       out,  the additional space is apportioned according to the
       row and column weights.  If all of the weights  are  zero,
       the  layout  is  centered  within its master.  For masters
       whose size is smaller than the requested layout, space  is
       taken  away  from  columns  and  rows  according  to their
       weights.  However, once a column or  row  shrinks  to  its
       minsize,  its  weight  is taken to be zero.  If more space
       needs to be removed from a layout than would be permitted,
       as  when  all  the  rows  or  columns are at there minimum
       sizes, the layout is clipped on the bottom and right.

GEOMETRY PROPAGATION
       The grid geometry manager normally computes  how  large  a
       master  must  be  to  just  exactly  meet the needs of its
       slaves, and it sets the requested width and height of  the
       master to these dimensions.  This causes geometry informa-
       tion to propagate up through a window hierarchy to a  top-
       level  window  so that the entire sub-tree sizes itself to
       fit the needs of the  leaf  windows.   However,  the  grid
       propagate  command may be used to turn off propagation for
       one or more masters.  If propagation is disabled then grid
       will  not set the requested width and height of the master
       window.  This may be useful if, for example, you wish  for
       a master window to have a fixed size that you specify.


RESTRICTIONS ON MASTER WINDOWS
       The  master for each slave must either be the slave's par-
       ent (the default) or a descendant of the  slave's  parent.
       This  restriction is necessary to guarantee that the slave
       can be placed over any part of its master that is  visible
       without  danger  of the slave being clipped by its parent.
       In addition, all slaves in one call to grid must have  the
       same master.

STACKING ORDER
       If  the master for a slave is not its parent then you must
       make sure that the slave is higher in the  stacking  order
       than  the  master.   Otherwise the master will obscure the
       slave and it will appear as if the slave hasn't been  man-
       aged correctly.  The easiest way to make sure the slave is
       higher than the master is  to  create  the  master  window
       first:   the  most recently created window will be highest
       in the stacking order.

CREDITS
       The grid command is based on ideas taken from the  GridBag
       geometry manager written by Doug. Stein, and the blt_table
       geometry manager, written by George Howlett.

KEYWORDS
       geometry manager, location, grid, cell, propagation, size,
       pack
