344 lines
19 KiB
HTML
344 lines
19 KiB
HTML
<HTML><HEAD><TITLE>Tk Built-In Commands - grid manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="grid.htm#M2" NAME="L558">NAME</A>
|
|
<DL><DD>grid - Geometry manager that arranges widgets in a grid</DL>
|
|
<DD><A HREF="grid.htm#M3" NAME="L559">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>grid </B><I>option arg </I>?<I>arg ...</I>?
|
|
</DL>
|
|
<DD><A HREF="grid.htm#M4" NAME="L560">DESCRIPTION</A>
|
|
<DL>
|
|
<DD><A HREF="grid.htm#M5" NAME="L561"><B>grid </B><I>slave </I>?<I>slave ...</I>? ?<I>options</I>?</A>
|
|
<DD><A HREF="grid.htm#M6" NAME="L562"><B>grid bbox </B><I>master</I> ?<I>column row</I>? ?<I>column2 row2</I>?</A>
|
|
<DD><A HREF="grid.htm#M7" NAME="L563"><B>grid columnconfigure </B><I>master index </I>?<I>-option value...</I>?</A>
|
|
<DD><A HREF="grid.htm#M8" NAME="L564"><B>grid configure </B><I>slave </I>?<I>slave ...</I>? ?<I>options</I>?</A>
|
|
<DL>
|
|
<DD><A HREF="grid.htm#M9" NAME="L565"><B>-column </B><I>n</I></A>
|
|
<DD><A HREF="grid.htm#M10" NAME="L566"><B>-columnspan </B><I>n</I></A>
|
|
<DD><A HREF="grid.htm#M11" NAME="L567"><B>-in </B><I>other</I></A>
|
|
<DD><A HREF="grid.htm#M12" NAME="L568"><B>-ipadx </B><I>amount</I></A>
|
|
<DD><A HREF="grid.htm#M13" NAME="L569"><B>-ipady </B><I>amount</I></A>
|
|
<DD><A HREF="grid.htm#M14" NAME="L570"><B>-padx </B><I>amount</I></A>
|
|
<DD><A HREF="grid.htm#M15" NAME="L571"><B>-pady </B><I>amount</I></A>
|
|
<DD><A HREF="grid.htm#M16" NAME="L572"><B>-row </B><I>n</I></A>
|
|
<DD><A HREF="grid.htm#M17" NAME="L573"><B>-rowspan </B><I>n</I></A>
|
|
<DD><A HREF="grid.htm#M18" NAME="L574"><B>-sticky </B><I>style</I></A>
|
|
</DL>
|
|
<DD><A HREF="grid.htm#M19" NAME="L575"><B>grid forget </B><I>slave </I>?<I>slave ...</I>?</A>
|
|
<DD><A HREF="grid.htm#M20" NAME="L576"><B>grid info </B><I>slave</I></A>
|
|
<DD><A HREF="grid.htm#M21" NAME="L577"><B>grid location </B><I>master x y</I></A>
|
|
<DD><A HREF="grid.htm#M22" NAME="L578"><B>grid propagate </B><I>master</I> ?<I>boolean</I>?</A>
|
|
<DD><A HREF="grid.htm#M23" NAME="L579"><B>grid rowconfigure </B><I>master index </I>?<I>-option value...</I>?</A>
|
|
<DD><A HREF="grid.htm#M24" NAME="L580"><B>grid remove </B><I>slave </I>?<I>slave ...</I>?</A>
|
|
<DD><A HREF="grid.htm#M25" NAME="L581"><B>grid size </B><I>master</I></A>
|
|
<DD><A HREF="grid.htm#M26" NAME="L582"><B>grid slaves </B><I>master</I> ?<I>-option value</I>?</A>
|
|
</DL>
|
|
<DD><A HREF="grid.htm#M27" NAME="L583">RELATIVE PLACEMENT</A>
|
|
<DL>
|
|
<DD><A HREF="grid.htm#M28" NAME="L584"><B>-</B></A>
|
|
<DD><A HREF="grid.htm#M29" NAME="L585"><B>x</B></A>
|
|
<DD><A HREF="grid.htm#M30" NAME="L586"><B>^</B></A>
|
|
</DL>
|
|
<DD><A HREF="grid.htm#M31" NAME="L587">THE GRID ALGORITHM</A>
|
|
<DD><A HREF="grid.htm#M32" NAME="L588">GEOMETRY PROPAGATION</A>
|
|
<DD><A HREF="grid.htm#M33" NAME="L589">RESTRICTIONS ON MASTER WINDOWS</A>
|
|
<DD><A HREF="grid.htm#M34" NAME="L590">STACKING ORDER</A>
|
|
<DD><A HREF="grid.htm#M35" NAME="L591">CREDITS</A>
|
|
<DD><A HREF="grid.htm#M36" NAME="L592">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
grid - Geometry manager that arranges widgets in a grid
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>grid </B><I>option arg </I>?<I>arg ...</I>?<BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
The <B>grid</B> 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 <B>grid</B> command can have any of several forms, depending
|
|
on the <I>option</I> argument:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M5"><B>grid </B><I>slave </I>?<I>slave ...</I>? ?<I>options</I>?</A><DD>
|
|
If the first argument to <B>grid</B> is a window name (any value
|
|
starting with ``.''), then the command is processed in the same
|
|
way as <B>grid configure</B>.
|
|
<P><DT><A NAME="M6"><B>grid bbox </B><I>master</I> ?<I>column row</I>? ?<I>column2 row2</I>?</A><DD>
|
|
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 <I>column</I> and <I>row</I> 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 <I>column</I> and <I>row</I>
|
|
arguments are specified, then the bounding box spanning the rows and columns
|
|
indicated is returned.
|
|
<P><DT><A NAME="M7"><B>grid columnconfigure </B><I>master index </I>?<I>-option value...</I>?</A><DD>
|
|
Query or set the column properties of the <I>index</I> column of the
|
|
geometry master, <I>master</I>.
|
|
The valid options are <B>-minsize</B>, <B>-weight</B> and <B>-pad</B>.
|
|
If one or more options are provided, then <I>index</I> may be given as
|
|
a list of column indeces to which the configuration options will operate on.
|
|
The <B>-minsize</B> option sets the minimum size, in screen units,
|
|
that will be permitted for this column.
|
|
The <B>-weight</B> 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 allocated to the layout.
|
|
The <B>-pad</B> 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 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.
|
|
<P><DT><A NAME="M8"><B>grid configure </B><I>slave </I>?<I>slave ...</I>? ?<I>options</I>?</A><DD>
|
|
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 <B>-</B>, <B>x</B> and <B>^</B>,
|
|
can be specified instead of a window name to alter the default
|
|
location of a <I>slave</I>, as described in the ``RELATIVE PLACEMENT''
|
|
section, below.
|
|
The following options are supported:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M9"><B>-column </B><I>n</I></A><DD>
|
|
Insert the slave so that it occupies the <I>n</I>th 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 <I>grid</I>, or column "0" if it is the first slave. For each
|
|
<B>x</B> that immediately precedes the <I>slave</I>, the column position
|
|
is incremented by one. Thus the <B>x</B> represents a blank column
|
|
for this row in the grid.
|
|
<P><DT><A NAME="M10"><B>-columnspan </B><I>n</I></A><DD>
|
|
Insert the slave so that it occupies <I>n</I> columns in the grid.
|
|
The default is one column, unless the window name is followed by a
|
|
<B>-</B>, in which case the columnspan is incremented once for each immediately
|
|
following <B>-</B>.
|
|
<P><DT><A NAME="M11"><B>-in </B><I>other</I></A><DD>
|
|
Insert the slave(s) in the master
|
|
window given by <I>other</I>. The default is the first slave's
|
|
parent window.
|
|
<P><DT><A NAME="M12"><B>-ipadx </B><I>amount</I></A><DD>
|
|
The <I>amount</I> 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 <I>amount</I> must be a valid screen distance, such as <B>2</B> or <B>.5c</B>.
|
|
It defaults to 0.
|
|
<P><DT><A NAME="M13"><B>-ipady </B><I>amount</I></A><DD>
|
|
The <I>amount</I> 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 <I>amount</I> defaults to 0.
|
|
<P><DT><A NAME="M14"><B>-padx </B><I>amount</I></A><DD>
|
|
The <I>amount</I> specifies how much horizontal external padding to
|
|
leave on each side of the slave(s), in screen units.
|
|
The <I>amount</I> defaults to 0.
|
|
This space is added outside the slave(s) border.
|
|
<P><DT><A NAME="M15"><B>-pady </B><I>amount</I></A><DD>
|
|
The <I>amount</I> specifies how much vertical external padding to
|
|
leave on the top and bottom of the slave(s), in screen units.
|
|
The <I>amount</I> defaults to 0.
|
|
This space is added outside the slave(s) border.
|
|
<P><DT><A NAME="M16"><B>-row </B><I>n</I></A><DD>
|
|
Insert the slave so that it occupies the <I>n</I>th 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 <B>grid</B>, or the first unoccupied row if this is the first slave.
|
|
<P><DT><A NAME="M17"><B>-rowspan </B><I>n</I></A><DD>
|
|
Insert the slave so that it occupies <I>n</I> rows in the grid.
|
|
The default is one row. If the next <B>grid</B> command contains
|
|
<B>^</B> characters instead of <I>slaves</I> that line up with the columns
|
|
of this <I>slave</I>, then the <B>rowspan</B> of this <I>slave</I> is
|
|
extended by one.
|
|
<P><DT><A NAME="M18"><B>-sticky </B><I>style</I></A><DD>
|
|
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.
|
|
<I>Style</I> is a string that contains zero or more of the characters
|
|
<B>n</B>, <B>s</B>, <B>e</B> or <B>w</B>.
|
|
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 <B>n</B> and <B>s</B> (or
|
|
<B>e</B> and <B>w</B>) are specified, the slave will be stretched to fill the entire
|
|
height (or width) of its cavity. The <B>sticky</B> option subsumes the
|
|
combination of <B>-anchor</B> and <B>-fill</B> that is used by <B><A HREF="../TclCmd/pack.htm">pack</A></B>.
|
|
The default is <B>{}</B>, which causes the slave to be centered in its cavity,
|
|
at its requested size.
|
|
</DL><P>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.<DL>
|
|
<P></DL>
|
|
<P><DT><A NAME="M19"><B>grid forget </B><I>slave </I>?<I>slave ...</I>?</A><DD>
|
|
Removes each of the <I>slave</I>s 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.
|
|
<P><DT><A NAME="M20"><B>grid info </B><I>slave</I></A><DD>
|
|
Returns a list whose elements are the current configuration state of
|
|
the slave given by <I>slave</I> in the same option-value form that
|
|
might be specified to <B>grid configure</B>.
|
|
The first two elements of the list are ``<B>-in </B><I>master</I>'' where
|
|
<I>master</I> is the slave's master.
|
|
<P><DT><A NAME="M21"><B>grid location </B><I>master x y</I></A><DD>
|
|
Given <I>x</I> and <I>y</I> values in screen units relative to the master window,
|
|
the column and row number at that <I>x</I> and <I>y</I> location is returned.
|
|
For locations that are above or to the left of the grid, <B>-1</B> is returned.
|
|
<P><DT><A NAME="M22"><B>grid propagate </B><I>master</I> ?<I>boolean</I>?</A><DD>
|
|
If <I>boolean</I> has a true boolean value such as <B>1</B> or <B>on</B>
|
|
then propagation is enabled for <I>master</I>, which must be a window
|
|
name (see ``GEOMETRY PROPAGATION'' below).
|
|
If <I>boolean</I> has a false boolean value then propagation is
|
|
disabled for <I>master</I>.
|
|
In either of these cases an empty string is returned.
|
|
If <I>boolean</I> is omitted then the command returns <B>0</B> or
|
|
<B>1</B> to indicate whether propagation is currently enabled
|
|
for <I>master</I>.
|
|
Propagation is enabled by default.
|
|
<P><DT><A NAME="M23"><B>grid rowconfigure </B><I>master index </I>?<I>-option value...</I>?</A><DD>
|
|
Query or set the row properties of the <I>index</I> row of the
|
|
geometry master, <I>master</I>.
|
|
The valid options are <B>-minsize</B>, <B>-weight</B> and <B>-pad</B>.
|
|
If one or more options are provided, then <I>index</I> may be given as
|
|
a list of row indeces to which the configuration options will operate on.
|
|
The <B>-minsize</B> option sets the minimum size, in screen units,
|
|
that will be permitted for this row.
|
|
The <B>-weight</B> 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 <B>-pad</B> 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.
|
|
<P><DT><A NAME="M24"><B>grid remove </B><I>slave </I>?<I>slave ...</I>?</A><DD>
|
|
Removes each of the <I>slave</I>s 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.
|
|
<P><DT><A NAME="M25"><B>grid size </B><I>master</I></A><DD>
|
|
Returns the size of the grid (in columns then rows) for <I>master</I>.
|
|
The size is determined either by the <I>slave</I> occupying the largest
|
|
row or column, or the largest column or row with a <B>minsize</B>,
|
|
<B>weight</B>, or <B>pad</B> that is non-zero.
|
|
<P><DT><A NAME="M26"><B>grid slaves </B><I>master</I> ?<I>-option value</I>?</A><DD>
|
|
If no options are supplied, a list of all of the slaves in <I>master</I>
|
|
are returned, most recently manages first.
|
|
<I>Option</I> can be either <B>-row</B> or <B>-column</B> which
|
|
causes only the slaves in the row (or column) specified by <I>value</I>
|
|
to be returned.
|
|
<P></DL>
|
|
<H3><A NAME="M27">RELATIVE PLACEMENT</A></H3>
|
|
The <B>grid</B> 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 <I>slave</I>,
|
|
default values are chosen for
|
|
<B>column</B>, <B>row</B>, <B>columnspan</B> and <B>rowspan</B>
|
|
at the time the <I>slave</I> is managed. The values are chosen
|
|
based upon the current layout of the grid, the position of the <I>slave</I>
|
|
relative to other <I>slave</I>s in the same grid command, and the presence
|
|
of the characters <B>-</B>, <B>^</B>, and <B>^</B> in <B>grid</B>
|
|
command where <I>slave</I> names are normally expected.
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M28"><B>-</B></A><DD>
|
|
This increases the columnspan of the <I>slave</I> to the left. Several
|
|
<B>-</B>'s in a row will successively increase the columnspan. A <B>-</B>
|
|
may not follow a <B>^</B> or a <B>x</B>.
|
|
<P><DT><A NAME="M29"><B>x</B></A><DD>
|
|
This leaves an empty column between the <I>slave</I> on the left and
|
|
the <I>slave</I> on the right.
|
|
<P><DT><A NAME="M30"><B>^</B></A><DD>
|
|
This extends the <B>rowspan</B> of the <I>slave</I> above the <B>^</B>'s
|
|
in the grid. The number of <B>^</B>'s in a row must match the number of
|
|
columns spanned by the <I>slave</I> above it.
|
|
<P></DL>
|
|
<H3><A NAME="M31">THE GRID ALGORITHM</A></H3>
|
|
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 <I>sticky</I> flag.
|
|
<P>
|
|
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
|
|
<I>minsize</I> for that row or column, or the sum of the <I>pad</I>ding
|
|
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 <I>weight</I>. For each
|
|
group whose weights are all zero, the additional space is apportioned
|
|
equally.
|
|
<P>
|
|
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.
|
|
<H3><A NAME="M32">GEOMETRY PROPAGATION</A></H3>
|
|
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 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 <B>grid propagate</B> 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.
|
|
|
|
<H3><A NAME="M33">RESTRICTIONS ON MASTER WINDOWS</A></H3>
|
|
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 addition, all slaves in one call to <B>grid</B> must have the same master.
|
|
<H3><A NAME="M34">STACKING ORDER</A></H3>
|
|
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.
|
|
<H3><A NAME="M35">CREDITS</A></H3>
|
|
The <B>grid</B> command is based on ideas taken from the <I>GridBag</I>
|
|
geometry manager written by Doug. Stein, and the <B>blt_table</B> geometry
|
|
manager, written by George Howlett.
|
|
<H3><A NAME="M36">KEYWORDS</A></H3>
|
|
<A href="../Keywords/G.htm#geometry manager">geometry manager</A>, <A href="../Keywords/L.htm#location">location</A>, <A href="../Keywords/G.htm#grid">grid</A>, <A href="../Keywords/C.htm#cell">cell</A>, <A href="../Keywords/P.htm#propagation">propagation</A>, <A href="../Keywords/S.htm#size">size</A>, <A href="../Keywords/P.htm#pack">pack</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|