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.  If one  or
              more  options are provided, then index may be given
              as a list of column indeces to which the configura-
              tion  options will operate on.  The -minsize 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 col-
              umn  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 completely in that column when the
              grid geometry manager requests a size from the con-
              taining 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 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  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 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 apportioning 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 completely in that row
              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 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
