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 suitable as the
              first slave argument to grid  configure,  either  a
              window  name  (any value starting with .) or one of
              the characters x or ^ (see  the  ``RELATIVE  PLACE-
              MENT''  section  below),  then  the command is pro-
              cessed 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, -uniform and -pad.
              If one or more options are provided, then index may
              be  given  as a list of column indeces to which the
              configuration options will operate on.   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 -uniform option, when a
              non-empty value is supplied, places the column in a
              uniform group with other columns that have the same
              value for -uniform.  The space for columns  belong-
              ing  to  a uniform group is allocated so that their
              sizes are always  in  strict  proportion  to  their
              -weight  values.   See ``THE GRID ALGORITHM'' below
              for further details.  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.  Amount may
                     be a list of two values to  specify  padding
                     for  left  and right separately.  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.
                     Amount may be a list of two values to  spec-
                     ify  padding  for top and bottom separately.
                     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  for-
              gotten,  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,  -uniform  and -pad.  If one or
              more options are provided, then index may be  given
              as a list of row indeces to which the configuration
              options will operate on.  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  -uni-
              form  option,  when  a non-empty value is supplied,
              places the row in a uniform group with  other  rows
              that  have  the same value for -uniform.  The space
              for rows belonging to a uniform group is  allocated
              so that their sizes are always in strict proportion
              to their -weight  values.   See  ``THE  GRID  ALGO-
              RITHM'' below for further details.  The -pad option
              specifies the number of screen units that  will  be
              added to the largest window contained completely 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 -, x, 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, nor  may  it  be  the
                     first slave argument to grid configure.

              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.  After that the  rows
       or  columns  in  each  uniform  group adapt to each other.
       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.

       When multiple rows or columns belong to a  uniform  group,
       the  space  allocated  to  them is always in proportion to
       their weights. (A weight of zero is considered to  be  1.)
       In  other words, a row or column configured with -weight 1
       -uniform a will have exactly the same size  as  any  other
       row or column configured with -weight 1 -uniform a.  A row
       or column configured with -weight 2  -uniform  b  will  be
       exactly  twice  as  large  as  one that is configured with
       -weight 1 -uniform b.

       More technically, each row or column  in  the  group  will
       have  a  size  equal to k*weight for some constant k.  The
       constant k is chosen so that  no  row  or  column  becomes
       smaller  than  its minimum size.  For example, if all rows
       or columns in a group have the same weight, then each  row
       or  column  will  have the same size as the largest row or
       column in the group.

       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,
