265 lines
10 KiB
Plaintext
265 lines
10 KiB
Plaintext
'\"
|
|
'\" Copyright (c) 1990-1994 The Regents of the University of California.
|
|
'\" Copyright (c) 1994 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" @(#) pack.n 1.16 95/06/22 14:07:50
|
|
'\"
|
|
.so STk-man.macros
|
|
.TH pack n 3.1 STk "Tk Built-In Commands"
|
|
.BS
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
|
.SH NAME
|
|
pack \- Geometry manager that packs around edges of cavity
|
|
.SH SYNOPSIS
|
|
(\fBpack \fIoption arg \fR?\fIarg ...\fR?)
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The \fBpack\fR procedure 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.
|
|
The \fBpack\fR procedure can have any of several forms, depending
|
|
on the \fIoption\fR argument:
|
|
.TP
|
|
(\fBpack \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR?)
|
|
If the first argument to \fBpack\fR is a window name (any value
|
|
starting with ``.''), then the procedure is processed in the same
|
|
way as \fBpack configure\fR.
|
|
.TP
|
|
(\fBpack 'configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR?)
|
|
The arguments consist of the names of one or more slave windows
|
|
followed by pairs of arguments that specify how
|
|
to manage the slaves.
|
|
See ``THE PACKER ALGORITHM'' below for details on how the options
|
|
are used by the packer.
|
|
The following options are supported:
|
|
.RS
|
|
.TP
|
|
\fB:after \fIother\fR
|
|
\fIOther\fR must the name of another window.
|
|
Use its master as the master for the slaves, and insert
|
|
the slaves just after \fIother\fR in the packing order.
|
|
.TP
|
|
\fB:anchor \fIanchor\fR
|
|
\fIAnchor\fR must be a valid anchor position such as \fBn\fR
|
|
or \fBsw\fR; it specifies where to position each slave in its
|
|
parcel.
|
|
Defaults to \fBcenter\fR.
|
|
.TP
|
|
\fB:before \fIother\fR
|
|
\fIOther\fR must the name of another window.
|
|
Use its master as the master for the slaves, and insert
|
|
the slaves just before \fIother\fR in the packing order.
|
|
.TP
|
|
\fB:expand \fIboolean\fR
|
|
Specifies whether the slaves should be expanded to consume
|
|
extra space in their master.
|
|
\fIBoolean\fR may have any proper boolean value. Defaults to #f.
|
|
.TP
|
|
\fB:fill \fIstyle\fR
|
|
If a slave's parcel is larger than its requested dimensions, this
|
|
option may be used to stretch the slave.
|
|
\fIStyle\fR must have one of the following values:
|
|
.RS
|
|
.TP
|
|
\fBnone\fR
|
|
Give the slave its requested dimensions plus any internal padding
|
|
requested with \fB:ipadx\fR or \fB:ipady\fR. This is the default.
|
|
.TP
|
|
\fBx\fR
|
|
Stretch the slave horizontally to fill the entire width of its
|
|
parcel (except leave external padding as specified by \fB:padx\fR).
|
|
.TP
|
|
\fBy\fR
|
|
Stretch the slave vertically to fill the entire height of its
|
|
parcel (except leave external padding as specified by \fB:pady\fR).
|
|
.TP
|
|
\fBboth\fR
|
|
Stretch the slave both horizontally and vertically.
|
|
.RE
|
|
.TP
|
|
\fB:in \fIother\fR
|
|
Insert the slave(s) at the end of the packing order for the master
|
|
window given by \fIother\fR.
|
|
.TP
|
|
\fB:ipadx \fIamount\fR
|
|
\fIAmount\fR specifies how much horizontal internal padding to
|
|
leave on each side of the slave(s).
|
|
\fIAmount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR.
|
|
It defaults to 0.
|
|
.TP
|
|
\fB:ipady \fIamount\fR
|
|
\fIAmount\fR specifies how much vertical internal padding to
|
|
leave on each side of the slave(s).
|
|
\fIAmount\fR defaults to 0.
|
|
.TP
|
|
\fB:padx \fIamount\fR
|
|
\fIAmount\fR specifies how much horizontal external padding to
|
|
leave on each side of the slave(s).
|
|
\fIAmount\fR defaults to 0.
|
|
.TP
|
|
\fB:pady \fIamount\fR
|
|
\fIAmount\fR specifies how much vertical external padding to
|
|
leave on each side of the slave(s).
|
|
\fIAmount\fR defaults to 0.
|
|
.TP
|
|
\fB:side \fIside\fR
|
|
Specifies which side of the master the slave(s) will be packed against.
|
|
Must be \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR.
|
|
Defaults to \fBtop\fR.
|
|
.LP
|
|
If no \fB:in\fR, \fB:after\fR or \fB:before\fR option is specified
|
|
then each of the slaves 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 all the slaves will be
|
|
inserted at the specified point.
|
|
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.
|
|
.RE
|
|
.TP
|
|
(\fBpack 'forget \fIslave \fR?\fIslave ...\fR?)
|
|
Removes each of the \fIslave\fRs from the packing order for its
|
|
master and unmaps their windows.
|
|
The slaves will no longer be managed by the packer.
|
|
.TP
|
|
(\fBpack 'info \fIslave\fR)
|
|
Returns a list whose elements are the current configuration state of
|
|
the slave given by \fIslave\fR in the same option-value form that
|
|
might be specified to \fBpack configure\fR.
|
|
The first two elements of the list are ``\fB:in \fImaster\fR'' where
|
|
\fImaster\fR is the slave's master.
|
|
.TP
|
|
(\fBpack 'propagate \fImaster\fR ?\fIboolean\fR?)
|
|
If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR
|
|
then propagation is enabled for \fImaster\fR, which must be a window
|
|
name (see ``GEOMETRY PROPAGATION'' below).
|
|
If \fIboolean\fR has a false boolean value then propagation is
|
|
disabled for \fImaster\fR.
|
|
In either of these cases an empty string is returned.
|
|
If \fIboolean\fR is omitted then the procedure returns \fB#f\fR or
|
|
\fB#t\fR to indicate whether propagation is currently enabled
|
|
for \fImaster\fR.
|
|
Propagation is enabled by default.
|
|
.TP
|
|
(\fBpack 'slaves \fImaster\fR)
|
|
Returns a list of all of the slaves in the packing order for \fImaster\fR.
|
|
The order of the slaves in the list is the same as their order in
|
|
the packing order.
|
|
If \fImaster\fR has no slaves then an empty string is returned.
|
|
|
|
.SH "THE PACKER ALGORITHM"
|
|
.PP
|
|
For each master the packer maintains an ordered list of slaves
|
|
called the \fIpacking list\fR.
|
|
The \fB:in\fR, \fB:after\fR, and \fB:before\fR 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.
|
|
.PP
|
|
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 \fIcavity\fR; for the first slave it
|
|
is the entire area of the master.
|
|
.PP
|
|
For each slave the packer carries out the following steps:
|
|
.IP [1]
|
|
The packer allocates a rectangular \fIparcel\fR for the slave
|
|
along the side of the cavity given by the slave's \fB:side\fR 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 \fB:ipady\fR and \fB:pady\fR 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 \fB:ipadx\fR and \fB:padx\fR options.
|
|
The parcel may be enlarged further because of the \fB:expand\fR
|
|
option (see ``EXPANSION'' below)
|
|
.IP [2]
|
|
The packer chooses the dimensions of the slave.
|
|
The width will normally be the slave's requested width plus
|
|
twice its \fB:ipadx\fR option and the height will normally be
|
|
the slave's requested height plus twice its \fB:ipady\fR
|
|
option.
|
|
However, if the \fB:fill\fR option is \fBx\fR or \fBboth\fR
|
|
then the width of the slave is expanded to fill the width of the parcel,
|
|
minus twice the \fB:padx\fR option.
|
|
If the \fB:fill\fR option is \fBy\fR or \fBboth\fR
|
|
then the height of the slave is expanded to fill the width of the parcel,
|
|
minus twice the \fB:pady\fR option.
|
|
.IP [3]
|
|
The packer positions the slave over its parcel.
|
|
If the slave is smaller than the parcel then the \fB:anchor\fR
|
|
option determines where in the parcel the slave will be placed.
|
|
If \fB:padx\fR or \fB:pady\fR is non-zero, then the given
|
|
amount of external padding will always be left between the
|
|
slave and the edges of the parcel.
|
|
.PP
|
|
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.
|
|
|
|
.SH "EXPANSION"
|
|
.PP
|
|
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 \fB:expand\fR option is set.
|
|
Extra horizontal space is distributed among the expandable
|
|
slaves whose \fB:side\fR is \fBleft\fR or \fBright\fR,
|
|
and extra vertical space is distributed among the expandable
|
|
slaves whose \fB:side\fR is \fBtop\fR or \fBbottom\fR.
|
|
|
|
.SH "GEOMETRY PROPAGATION"
|
|
.PP
|
|
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 \fBpack propagate\fR procedure 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.
|
|
|
|
.SH "RESTRICTIONS ON MASTER WINDOWS"
|
|
.PP
|
|
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.
|
|
|
|
.SH "PACKING ORDER"
|
|
.PP
|
|
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 \fBraise\fR and \fBlower\fR procedures to change
|
|
the stacking order of either the master or the slave.
|
|
|
|
.SH SEE ALSO
|
|
grid, place
|