Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
grid(n)			     Tk	Built-In Commands		       grid(n)

NAME
       grid - Geometry manager that arranges widgets in	a grid

SYNOPSIS
       (grid option arg	?arg ...?)

DESCRIPTION
       The  grid  procedure is used to communicate with	the grid geometry man-
       ager that arranges widgets in rows and columns inside of	 another  win-
       dow, called the geometry	master (or master window).  The	grid procedure
       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	start-
	      ing with ``.''), then the	procedure is processed in the same way
	      as grid configure.

       (grid 'bbox master)

       (grid 'bbox master column row)

       (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	bound-
	      ing 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	 indi-
	      cated 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 in-
	      dex may be given as a list of column indexes to which  the  con-
	      figuration  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 column of weight one when extra space	is al-
	      located 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  re-
	      quests  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 '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  de-
	      scribed  in the ``RELATIVE PLACEMENT'' section, below.  The fol-
	      lowing 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
		     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 in-
		     cremented once for	each immediately 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	procedure con-
		     tains ^ 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	dimen-
		     sions,  this  option may be used to position (or stretch)
		     the slave within its cell.	 Style	is a string that  con-
		     tains  zero  or more of the characters n, s, e or w.  The
		     string can	optionally contains 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
		     the  empty	 string, 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 val-
	      ues 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	 configuration
	      state  of	the slave given	by slave in the	same option-value form
	      that might be specified to grid configure.  The first  two  ele-
	      ments 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)

       (grid 'propagate	master boolean)
	      If  boolean has a	true boolean value then	propagation is enabled
	      for master, which	must be	a window name (see ``GEOMETRY PROPAGA-
	      TION'' below).  If boolean has a false boolean value then	propa-
	      gation is	disabled for master.  In  either  of  these  cases  an
	      empty  list  is returned.	 If boolean is omitted then the	proce-
	      dure returns #f or #t to indicate	whether	 propagation  is  cur-
	      rently enabled for master.  Propagation is enabled by default.

       (grid 'rowconfigure master index	)

       (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  op-
	      tions  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 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 re-
	      turned 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)

       (grid 'slaves master :option value)
	      If  no options are supplied, a list of all of the	slaves in mas-
	      ter are returned,	most recently managed 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	procedure 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  re-
       moved  without  the  need to explicitly specify row and column informa-
       tion.  When no column or	row information	is specified for a slave,  de-
       fault  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	procedure, and the presence of the  characters	:,  ^,
       and ^ in	grid procedure 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 num-
		     ber 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 com-
       puted, 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 layout,  the	 addi-
       tional  space  is  apportioned according	to the row and column weights.
       If all of the weights are zero, the layout is centered within its  mas-
       ter.   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 mini-
       mum 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	geome-
       try  information	 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 procedure 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 mas-
       ter 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 de-
       fault) or a descendant of the slave's parent.  This restriction is nec-
       essary  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.	Other-
       wise 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 man-
       ager written by Doug. Stein, and	the blt_table geometry manager,	 writ-
       ten by George Howlett.

SEE ALSO
       pack, place

STk				      3.1			       grid(n)

NAME | SYNOPSIS | DESCRIPTION | RELATIVE PLACEMENT | THE GRID ALGORITHM | GEOMETRY PROPAGATION | RESTRICTIONS ON MASTER WINDOWS | STACKING ORDER | CREDITS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=stk_grid&manpath=FreeBSD+5.2-RELEASE+and+Ports>

home | help