tk4.2 User Commands - grid






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 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  command  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  specified,  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 -minsize  option  sets
          the minimum size, in screen units, that will be permit-
          ted 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) indi-
          cates  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
          allocated to the layout.  The -pad option specifies the  |
          number  of screen units that will be added to the larg-  |
          est window contained completely in that column when the  |
          grid geometry manager requests a size from the contain-  |
          ing 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 immedi-
               ately precedes the slave, the column  position  is
               incremented 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 immedi-
               ately following -.

          -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 charac-
               ters 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  configura-
          tion  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  confi-
          guration  state of the slave given by slave in the same
          option-value form that might be specified to grid  con-
          figure.   The  first two elements of the list are ``-in
          master'' where master is the slave's master.

     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 -min-
          size, -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 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 con-  |
          tained 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 previous 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 manages 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 expli-
     citly 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  rela-
     tive to other slaves in the same grid command, and the pres-
     ence of the characters -, ^, 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 successively
               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  com-
     pared  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 larg-
     est  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  layout,
     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 mas-
     ter  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 information to pro-
     pagate 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  parent
     (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  addi-  |
     tion, all slaves in one call to grid must have the same mas-  |
     ter.


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 managed
     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