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, 0 insertions, 409 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/grid.pod b/Master/tlpkg/tlperl/lib/Tk/grid.pod
deleted file mode 100644
index 8db89587a62..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/grid.pod
+++ /dev/null
@@ -1,409 +0,0 @@
-# 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
-