summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/grid.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/grid.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/grid.pod409
1 files changed, 409 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/grid.pod b/Master/tlpkg/tlperl/lib/Tk/grid.pod
new file mode 100644
index 00000000000..8db89587a62
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/grid.pod
@@ -0,0 +1,409 @@
+# Copyright (c) 1996 Sun Microsystems, Inc.
+# See the file "license.terms" for information on usage and redistribution
+# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+#
+#
+
+=head1 NAME
+
+Tk::grid - Geometry manager that arranges widgets in a grid
+
+=for category Tk Geometry Management
+
+=head1 SYNOPSIS
+
+S< >I<$widget>-E<gt>B<grid>?(?I<widget> ...,? ?I<arg> ?...>?)?
+
+S< >I<$widget>-E<gt>B<grid>I<Option>?(I<arg> ?,I<arg> ...?)?
+
+=head1 DESCRIPTION
+
+The B<grid> method 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> method can have any of several forms, depending
+on the I<option> argument:
+
+=over 4
+
+=item I<$slave>-E<gt>B<grid>(?I<$slave, ...>??, I<options>?)
+
+The arguments consist of the optional references to more slave windows
+followed by pairs of arguments that specify how to manage the slaves.
+The characters B<->, B<x> and B<^>,
+can be specified instead of a window reference to alter the default
+location of a I<$slave>, as described in L<"RELATIVE PLACEMENT">, below.
+
+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.
+
+The following options are supported:
+
+=over 8
+
+=item B<-column> => I<n>
+
+Insert the I<$slave> so that it occupies the I<n>th column in the grid.
+Column numbers start with 0. If this option is not supplied, then the
+I<$slave> is arranged just to the right of previous slave specified on this
+call to B<grid>, or column "0" if it is the first slave. For each
+B<x> that immediately precedes the I<$slave>, the column position
+is incremented by one. Thus the B<x> represents a blank column
+for this row in the grid.
+
+=item B<-columnspan> => I<n>
+
+Insert the slave so that it occupies I<n> columns in the grid.
+The default is one column, unless the window name is followed by a
+B<->, in which case the columnspan is incremented once for each immediately
+following B<->.
+
+=item B<-in> => I<$other>
+
+Insert the slave(s) in the master
+window given by I<$other>. The default is the first slave's
+parent window.
+
+=item B<-ipadx> => I<amount>
+
+The I<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 I<amount> must be a valid screen distance, such as B<2> or B<'.5c'>.
+It defaults to 0.
+
+=item B<-ipady> => I<amount>
+
+The I<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 I<amount> defaults to 0.
+
+=item B<-padx> => I<amount>
+
+The I<amount> specifies how much horizontal external padding to
+leave on each side of the slave(s), in screen units.
+The I<amount> defaults to 0.
+This space is added outside the slave(s) border.
+
+=item B<-pady> => I<amount>
+
+The I<amount> specifies how much vertical external padding to
+leave on the top and bottom of the slave(s), in screen units.
+The I<amount> defaults to 0.
+This space is added outside the slave(s) border.
+
+=item B<-row> => I<n>
+
+Insert the slave so that it occupies the I<n>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>, or the first unoccupied row if this is the first slave.
+
+=item B<-rowspan> => I<n>
+
+Insert the slave so that it occupies I<n> rows in the grid.
+The default is one row. If the next B<grid> method contains
+B<^> characters instead of I<$slave>s that line up with the columns
+of this I<$slave>, then the B<rowspan> of this I<$slave> is
+extended by one.
+
+=item B<-sticky> => I<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.
+I<Style> is a string that contains zero or more of the characters
+B<n>, B<s>, B<e> or B<w>.
+The string can optionally contain 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> and B<s> (or
+B<e> and B<w>) are specified, the slave will be stretched to fill the entire
+height (or width) of its cavity. The B<sticky> option subsumes the
+combination of B<-anchor> and B<-fill> that is used by L<pack|Tk::pack>.
+The default is B<''>, which causes the slave to be centered in its cavity,
+at its requested size.
+
+=back
+
+=item I<$master>-E<gt>B<gridBbox>(?I<column, row>,? ?I<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 I<column> and I<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 I<column> and I<row>
+arguments are specified, then the bounding box spanning the rows and columns
+indicated is returned.
+
+=item I<$master>-E<gt>B<gridColumnconfigure>(I<index>?, I<-option>=>I<value, ...>?)
+
+Query or set the column properties of the I<index> column of the
+geometry master, I<$master>.
+The valid options are B<-minsize>, B<-weight> and B<-pad>.
+If one or more options are provided, then I<index> may be given as
+a list of column indices to which the configuration options will operate on.
+The B<-minsize> option sets the minimum size, in screen units,
+that will be permitted for this column.
+The B<-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 allocated to the layout.
+The B<-uniform> option, when a
+non-empty value is supplied, places the column in a I<uniform
+group> with other columns that have the same value for B<-uniform>.
+The space for columns belonging to a uniform group is allocated
+so that their sizes are always in strict proportion to their
+B<-weight> values. See I<THE GRID ALGORITHM> below for further
+details.
+The B<-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 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.
+
+=item I<$slave>-E<gt>B<gridConfigure>(?I<$slave, ...>?, I<options>?)
+
+The same as B<grid> method.
+
+=item I<$slave>-E<gt>B<gridForget>?(I<$slave, ...>)?
+
+Removes each of the I<$slave>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.
+
+=item I<$slave>-E<gt>B<gridInfo>
+
+Returns a list whose elements are the current configuration state of
+the slave given by I<$slave> in the same option-value form that
+might be specified to B<gridConfigure>.
+The first two elements of the list are ``B<-in>=>I<$master>'' where
+I<$master> is the slave's master.
+
+=item I<$master>-E<gt>B<gridLocation>(I<x, y>)
+
+Given I<x> and I<y> values in screen units relative to the master window,
+the column and row number at that I<x> and I<y> location is returned.
+For locations that are above or to the left of the grid, B<-1> is returned.
+
+=item I<$master>-E<gt>B<gridPropagate>?(I<boolean>)?
+
+If I<boolean> has a true boolean value such as B<1> or B<on>
+then propagation is enabled for I<$master>, which must be a window
+name (see L<"GEOMETRY PROPAGATION"> below).
+If I<boolean> has a false boolean value then propagation is
+disabled for I<$master>.
+In either of these cases an empty string is returned.
+If I<boolean> is omitted then the method returns B<0> or
+B<1> to indicate whether propagation is currently enabled
+for I<$master>.
+Propagation is enabled by default.
+
+=item I<$master>-E<gt>B<gridRowconfigure>(I<index>?, I<-option>=>I<value, ...>?)
+
+Query or set the row properties of the I<index> row of the
+geometry master, I<$master>.
+The valid options are B<-minsize>, B<-weight> and B<-pad>.
+If one or more options are provided, then I<index> may be given as
+a list of row indeces to which the configuration options will operate on.
+The B<-minsize> option sets the minimum size, in screen units,
+that will be permitted for this row.
+The B<-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 B<-uniform> option, when a non-empty value is supplied, places the
+row in a I<uniform group> with other rows that have the same value
+for B<-uniform>. The space for rows belonging to a uniform group
+is allocated so that their sizes are always in strict proportion
+to their B<-weight> values. See I<THE GRID ALGORITHM> below for
+further details.
+The B<-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 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.
+
+=item I<$slave>-E<gt>B<gridRemove>?(I<$slave, ...>)?
+
+Removes each of the I<$slave>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.
+
+=item I<$master>-E<gt>B<gridSize>
+
+Returns the size of the grid (in columns then rows) for I<$master>.
+The size is determined either by the I<$slave> occupying the largest
+row or column, or the largest column or row with a B<-minsize>,
+B<-weight>, or B<-pad> that is non-zero.
+
+=item I<$master>-E<gt>B<gridSlaves>?(I<-option>=>I<value>)?
+
+If no options are supplied, a list of all of the slaves in I<$master>
+are returned, most recently manages first.
+I<-option> can be either B<-row> or B<-column> which
+causes only the slaves in the row (or column) specified by I<value>
+to be returned.
+
+=back
+
+=head1 RELATIVE PLACEMENT
+
+The B<grid> method 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>,
+default values are chosen for
+B<-column>, B<-row>, B<-columnspan> and B<-rowspan>
+at the time the I<$slave> is managed. The values are chosen
+based upon the current layout of the grid, the position of the I<$slave>
+relative to other I<$slave>s in the same grid method, and the presence
+of the characters B<->, B<^>, and B<^> in B<grid>
+method where I<$slave> names are normally expected.
+
+=over 4
+
+=item B<->
+
+This increases the columnspan of the I<$slave> to the left. Several
+B<->'s in a row will successively increase the columnspan. A B<->
+may not follow a B<^> or a B<x>.
+
+=item B<x>
+
+This leaves an empty column between the I<$slave> on the left and
+the I<$slave> on the right.
+
+=item B<^>
+
+This extends the B<-rowspan> of the I<$slave> above the B<^>'s
+in the grid. The number of B<^>'s in a row must match the number of
+columns spanned by the I<$slave> above it.
+
+=back
+
+=head1 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 space 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> 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
+I<minsize> for that row or column, or the sum of the I<pad>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>. For each
+group whose weights are all zero, the additional space is apportioned
+equally.
+
+When multiple rows or columns belong to a uniform group, the space
+allocated to them is always in proportion to their weights. (A weight
+of zero is considered to be 1.) In other words, a row or column
+configured with B<-weight 1 -uniform> a will have exactly the same size
+as any other row or column configured with B<-weight 1 -uniform a>. A
+row or column configured with B<-weight 2 -uniform b> will be exactly
+twice as large as one that is configured with B<-weight 1 -uniform b>.
+
+More technically, each row or column in the group will have a size
+equal to I<k*weight> for some constant k. The constant k is chosen so
+that no row or column becomes smaller than its minimum size. For
+example, if all rows or columns in a group have the same weight, then
+each row or column will have the same size as the largest row or
+column in the group.
+
+
+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.
+
+=head1 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 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<gridPropagate> method 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.
+
+=head1 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 addition, all slaves in one call to B<grid> must have the same master.
+
+=head1 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.
+
+=head1 CREDITS
+
+The B<grid> method is based on ideas taken from the I<GridBag>
+geometry manager written by Doug. Stein, and the B<blt_table> geometry
+manager, written by George Howlett.
+
+=head1 SEE ALSO
+
+L<Tk::form|Tk::form>
+L<Tk::pack|Tk::pack>
+L<Tk::place|Tk::place>
+
+=head1 KEYWORDS
+
+geometry manager, location, grid, cell, propagation, size, pack,
+master, slave
+
+=cut
+