move tlperl.straw to tlperl

git-svn-id: svn://tug.org/texlive/trunk@18210 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 324 insertions, 0 deletions

diff --git a/Master/tlpkg/tlperl/lib/Tk/pack.pod b/Master/tlpkg/tlperl/lib/Tk/pack.pod
new file mode 100755
index 00000000000..0449556265c
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/pack.pod
@@ -0,0 +1,324 @@
+#  Copyright (c) 1990-1994 The Regents of the University of California.
+#  Copyright (c) 1994-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::pack - Geometry manager that packs around edges of cavity
+
+=for category  Tk Geometry Management
+
+=head1 SYNOPSIS
+
+S<    >I<$widget>-E<gt>B<pack>?(I<args>)?
+
+S<    >I<$widget>-E<gt>B<pack>I<Option>?(I<args>)?
+
+=head1 DESCRIPTION
+
+The B<pack> method is used to communicate with the packer,
+a geometry manager that arranges the children of a parent by
+packing them in order around the edges of the parent.
+
+In this B<perl> port of Tk it is normal to pack widgets one-at-a-time
+using the widget object to be packed to invoke a method call.
+This is a slight distortion of underlying Tk interface (which
+can handle lists of windows to one pack method call) but has proven
+effective in practice.
+
+The B<pack> method can have any of several forms, depending
+on I<Option>:
+
+=over 4
+
+=item I<$slave>-E<gt>B<pack>?(I<options>)?
+
+The options consist of pairs of arguments that specify how
+to manage the slave.
+See L<"THE PACKER ALGORITHM"> below for details on how the options
+are used by the packer.
+The following options are supported:
+
+=over 8
+
+=item B<-after> =E<gt> I<$other>
+
+I<$other> must be another window.
+Use its master as the master for the slave, and insert
+the slave just after I<$other> in the packing order.
+
+=item B<-anchor> =E<gt> I<anchor>
+
+I<Anchor> must be a valid anchor position such as B<n>
+or B<sw>; it specifies where to position each slave in its
+parcel.
+Defaults to B<center>.
+
+=item B<-before> =E<gt> I<$other>
+
+I<$other> must be another window.
+Use its master as the master for the slave, and insert
+the slave just before I<$other> in the packing order.
+
+=item B<-expand> =E<gt> I<boolean>
+
+Specifies whether the slave should be expanded to consume
+extra space in their master.
+I<Boolean> may have any proper boolean value, such as B<1>
+or B<no>.
+Defaults to 0.
+
+=item B<-fill> =E<gt> I<style>
+
+If a slave's parcel is larger than its requested dimensions, this
+option may be used to stretch the slave.
+I<Style> must have one of the following values:
+
+=over 12
+
+=item B<none>
+
+Give the slave its requested dimensions plus any internal padding
+requested with B<-ipadx> or B<-ipady>.  This is the default.
+
+=item B<x>
+
+Stretch the slave horizontally to fill the entire width of its
+parcel (except leave external padding as specified by B<-padx>).
+
+=item B<y>
+
+Stretch the slave vertically to fill the entire height of its
+parcel (except leave external padding as specified by B<-pady>).
+
+=item B<both>
+
+Stretch the slave both horizontally and vertically.
+
+=back
+
+=item B<-in> =E<gt> I<$master>
+
+Insert the slave(s) at the end of the packing order for the master
+window given by I<$master>.
+
+=item B<-ipadx> =E<gt> I<amount>
+
+I<Amount> specifies how much horizontal internal padding to
+leave on each side of the slave(s).
+I<Amount> must be a valid screen distance, such as B<2> or B<.5c>.
+It defaults to 0.
+
+=item B<-ipady> =E<gt> I<amount>
+
+I<Amount> specifies how much vertical internal padding to
+leave on each side of the slave(s).
+I<Amount>  defaults to 0.
+
+=item B<-padx> =E<gt> I<amount>
+
+I<Amount> specifies how much horizontal external padding to
+leave on each side of the slave(s).
+I<Amount> defaults to 0.
+
+=item B<-pady> =E<gt> I<amount>
+
+I<Amount> specifies how much vertical external padding to
+leave on each side of the slave(s).
+I<Amount> defaults to 0.
+
+=item B<-side> =E<gt> I<side>
+
+Specifies which side of the master the slave(s) will be packed against.
+Must be B<left>, B<right>, B<top>, or B<bottom>.
+Defaults to B<top>.
+
+=back
+
+=back
+
+If no B<-in>, B<-after> or B<-before> option is specified
+then slave will be inserted at the end of the packing list
+for its parent unless it is already managed by the packer (in which
+case it will be left where it is).
+If one of these options is specified then slave will be
+inserted at the specified point.
+If the slave are already managed by the geometry manager
+then any unspecified options for them retain their previous values rather
+than receiving default values.
+
+=over 4
+
+=item I<$slave>-E<gt>B<packConfigure>?(I<options>)?
+
+Same as B<pack>.
+
+=item I<$slave>-E<gt>B<packForget>
+
+Removes I<slave> from the packing order for its
+master and unmaps its window.
+The slave will no longer be managed by the packer.
+
+=item I<$slave>-E<gt>B<packInfo>
+
+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<packConfigure>.
+The first two elements of the list are ``B<-in>=E<gt>I<$master>'' where
+I<$master> is the slave's master.
+
+=item I<$master>-E<gt>B<packPropagate>?(I<boolean>)?
+
+If I<boolean> has a true boolean value such as B<1> or B<on>
+then propagation is enabled for I<$master>,
+(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<packSlaves>
+
+Returns a list of all of the slaves in the packing order for I<$master>.
+The order of the slaves in the list is the same as their order in
+the packing order.
+If I<$master> has no slaves then an empty list/string is returned in
+array/scalar context, respectively
+
+=back
+
+=head1 THE PACKER ALGORITHM
+
+For each master the packer maintains an ordered list of slaves
+called the I<packing list>.
+The B<-in>, B<-after>, and B<-before> configuration
+options are used to specify the master for each slave and the slave's
+position in the packing list.
+If none of these options is given for a slave then the slave
+is added to the end of the packing list for its parent.
+
+The packer arranges the slaves for a master by scanning the
+packing list in order.
+At the time it processes each slave, a rectangular area within
+the master is still unallocated.
+This area is called the I<cavity>;  for the first slave it
+is the entire area of the master.
+
+For each slave the packer carries out the following steps:
+
+=over 4
+
+=item [1]
+
+The packer allocates a rectangular I<parcel> for the slave
+along the side of the cavity given by the slave's B<-side> option.
+If the side is top or bottom then the width of the parcel is
+the width of the cavity and its height is the requested height
+of the slave plus the B<-ipady> and B<-pady> options.
+For the left or right side the height of the parcel is
+the height of the cavity and the width is the requested width
+of the slave plus the B<-ipadx> and B<-padx> options.
+The parcel may be enlarged further because of the B<-expand>
+option (see L<"EXPANSION"> below)
+
+=item [2]
+
+The packer chooses the dimensions of the slave.
+The width will normally be the slave's requested width plus
+twice its B<-ipadx> option and the height will normally be
+the slave's requested height plus twice its B<-ipady>
+option.
+However, if the B<-fill> option is B<x> or B<both>
+then the width of the slave is expanded to fill the width of the parcel,
+minus twice the B<-padx> option.
+If the B<-fill> option is B<y> or B<both>
+then the height of the slave is expanded to fill the width of the parcel,
+minus twice the B<-pady> option.
+
+=item [3]
+
+The packer positions the slave over its parcel.
+If the slave is smaller than the parcel then the B<-anchor>
+option determines where in the parcel the slave will be placed.
+If B<-padx> or B<-pady> is non-zero, then the given
+amount of external padding will always be left between the
+slave and the edges of the parcel.
+
+Once a given slave has been packed, the area of its parcel
+is subtracted from the cavity, leaving a smaller rectangular
+cavity for the next slave.
+If a slave doesn't use all of its parcel, the unused space
+in the parcel will not be used by subsequent slaves.
+If the cavity should become too small to meet the needs of
+a slave then the slave will be given whatever space is
+left in the cavity.
+If the cavity shrinks to zero size, then all remaining slaves
+on the packing list will be unmapped from the screen until
+the master window becomes large enough to hold them again.
+
+=back
+
+=head1 EXPANSION
+
+If a master window is so large that there will be extra space
+left over after all of its slaves have been packed, then the
+extra space is distributed uniformly among all of the slaves
+for which the B<-expand> option is set.
+Extra horizontal space is distributed among the expandable
+slaves whose B<-side> is B<left> or B<right>,
+and extra vertical space is distributed among the expandable
+slaves whose B<-side> is B<top> or B<bottom>.
+
+=head1 GEOMETRY PROPAGATION
+
+The packer 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<packPropagate> method may be used to
+turn off propagation for one or more masters.
+If propagation is disabled then the packer will not set
+the requested width and height of the packer.
+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.
+
+=head1 PACKING 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 packed 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.
+Or, you can use the B<raise> and B<lower> methods to change
+the stacking order of either the master or the slave.
+
+=head1 SEE ALSO
+
+L<Tk::form|Tk::form>
+L<Tk::grid|Tk::grid>
+L<Tk::place|Tk::place>
+
+=head1 KEYWORDS
+
+geometry manager, location, packer, parcel, propagation, size
+
+=cut
+