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 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	start-
	      ing  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 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 indeces 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 command 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
		     {},  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 ?boolean?
	      If  boolean has a	true boolean value such	as 1 or	on then	propa-
	      gation 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 de-
	      fault.

       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 ?-option value?
	      If no options are	supplied, a list of all	of the slaves in  mas-
	      ter  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 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 command, and the presence 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 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 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 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.

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

Tk				      4.1			       grid(n)

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

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

home | help