tk/doc/pack.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH pack n 4.0 Tk "Tk Built-In Commands"
  12 .BS
  13 '\" Note:  do not modify the .SH NAME line immediately below!
  14 .SH NAME
  15 pack \- Geometry manager that packs around edges of cavity
  16 .SH SYNOPSIS
  17 \fBpack \fIoption arg \fR?\fIarg ...\fR?
  18 .BE
  19
  20 .SH DESCRIPTION
  21 .PP
  22 The \fBpack\fR command is used to communicate with the packer,
  23 a geometry manager that arranges the children of a parent by
  24 packing them in order around the edges of the parent.
  25 The \fBpack\fR command can have any of several forms, depending
  26 on the \fIoption\fR argument:
  27 .TP
  28 \fBpack \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR?
  29 If the first argument to \fBpack\fR is a window name (any value
  30 starting with ``.''), then the command is processed in the same
  31 way as \fBpack configure\fR.
  32 .TP
  33 \fBpack configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR?
  34 The arguments consist of the names of one or more slave windows
  35 followed by pairs of arguments that specify how
  36 to manage the slaves.
  37 See ``THE PACKER ALGORITHM'' below for details on how the options
  38 are used by the packer.
  39 The following options are supported:
  40 .RS
  41 .TP
  42 \fB\-after \fIother\fR
  43 \fIOther\fR must the name of another window.
  44 Use its master as the master for the slaves, and insert
  45 the slaves just after \fIother\fR in the packing order.
  46 .TP
  47 \fB\-anchor \fIanchor\fR
  48 \fIAnchor\fR must be a valid anchor position such as \fBn\fR
  49 or \fBsw\fR; it specifies where to position each slave in its
  50 parcel.
  51 Defaults to \fBcenter\fR.
  52 .TP
  53 \fB\-before \fIother\fR
  54 \fIOther\fR must the name of another window.
  55 Use its master as the master for the slaves, and insert
  56 the slaves just before \fIother\fR in the packing order.
  57 .TP
  58 \fB\-expand \fIboolean\fR
  59 Specifies whether the slaves should be expanded to consume
  60 extra space in their master.
  61 \fIBoolean\fR may have any proper boolean value, such as \fB1\fR
  62 or \fBno\fR.
  63 Defaults to 0.
  64 .TP
  65 \fB\-fill \fIstyle\fR
  66 If a slave's parcel is larger than its requested dimensions, this
  67 option may be used to stretch the slave.
  68 \fIStyle\fR must have one of the following values:
  69 .RS
  70 .TP
  71 \fBnone\fR
  72 Give the slave its requested dimensions plus any internal padding
  73 requested with \fB\-ipadx\fR or \fB\-ipady\fR.  This is the default.
  74 .TP
  75 \fBx\fR
  76 Stretch the slave horizontally to fill the entire width of its
  77 parcel (except leave external padding as specified by \fB\-padx\fR).
  78 .TP
  79 \fBy\fR
  80 Stretch the slave vertically to fill the entire height of its
  81 parcel (except leave external padding as specified by \fB\-pady\fR).
  82 .TP
  83 \fBboth\fR
  84 Stretch the slave both horizontally and vertically.
  85 .RE
  86 .TP
  87 \fB\-in \fIother\fR
  88 Insert the slave(s) at the end of the packing order for the master
  89 window given by \fIother\fR.
  90 .TP
  91 \fB\-ipadx \fIamount\fR
  92 \fIAmount\fR specifies how much horizontal internal padding to
  93 leave on each side of the slave(s).
  94 \fIAmount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR.
  95 It defaults to 0.
  96 .TP
  97 \fB\-ipady \fIamount\fR
  98 \fIAmount\fR specifies how much vertical internal padding to
  99 leave on each side of the slave(s).
 100 \fIAmount\fR  defaults to 0.
 101 .TP
 102 \fB\-padx \fIamount\fR
 103 \fIAmount\fR specifies how much horizontal external padding to
 104 leave on each side of the slave(s).  \fIAmount\fR may be a list
 105 of two values to specify padding for left and right separately.
 106 \fIAmount\fR defaults to 0.
 107 .TP
 108 \fB\-pady \fIamount\fR
 109 \fIAmount\fR specifies how much vertical external padding to
 110 leave on each side of the slave(s).  \fIAmount\fR may be a list
 111 of two values to specify padding for top and bottom separtely.
 112 \fIAmount\fR defaults to 0.
 113 .TP
 114 \fB\-side \fIside\fR
 115 Specifies which side of the master the slave(s) will be packed against.
 116 Must be \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR.
 117 Defaults to \fBtop\fR.
 118 .LP
 119 If no \fB\-in\fR, \fB\-after\fR or \fB\-before\fR option is specified
 120 then each of the slaves will be inserted at the end of the packing list
 121 for its parent unless it is already managed by the packer (in which
 122 case it will be left where it is).
 123 If one of these options is specified then all the slaves will be
 124 inserted at the specified point.
 125 If any of the slaves are already managed by the geometry manager
 126 then any unspecified options for them retain their previous values rather
 127 than receiving default values.
 128 .RE
 129 .TP
 130 \fBpack forget \fIslave \fR?\fIslave ...\fR?
 131 Removes each of the \fIslave\fRs from the packing order for its
 132 master and unmaps their windows.
 133 The slaves will no longer be managed by the packer.
 134 .TP
 135 \fBpack info \fIslave\fR
 136 Returns a list whose elements are the current configuration state of
 137 the slave given by \fIslave\fR in the same option-value form that
 138 might be specified to \fBpack configure\fR.
 139 The first two elements of the list are ``\fB\-in \fImaster\fR'' where
 140 \fImaster\fR is the slave's master.
 141 .TP
 142 \fBpack propagate \fImaster\fR ?\fIboolean\fR?
 143 If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR
 144 then propagation is enabled for \fImaster\fR, which must be a window
 145 name (see ``GEOMETRY PROPAGATION'' below).
 146 If \fIboolean\fR has a false boolean value then propagation is
 147 disabled for \fImaster\fR.
 148 In either of these cases an empty string is returned.
 149 If \fIboolean\fR is omitted then the command returns \fB0\fR or
 150 \fB1\fR to indicate whether propagation is currently enabled
 151 for \fImaster\fR.
 152 Propagation is enabled by default.
 153 .TP
 154 \fBpack slaves \fImaster\fR
 155 Returns a list of all of the slaves in the packing order for \fImaster\fR.
 156 The order of the slaves in the list is the same as their order in
 157 the packing order.
 158 If \fImaster\fR has no slaves then an empty string is returned.
 159
 160 .SH "THE PACKER ALGORITHM"
 161 .PP
 162 For each master the packer maintains an ordered list of slaves
 163 called the \fIpacking list\fR.
 164 The \fB\-in\fR, \fB\-after\fR, and \fB\-before\fR configuration
 165 options are used to specify the master for each slave and the slave's
 166 position in the packing list.
 167 If none of these options is given for a slave then the slave
 168 is added to the end of the packing list for its parent.
 169 .PP
 170 The packer arranges the slaves for a master by scanning the
 171 packing list in order.
 172 At the time it processes each slave, a rectangular area within
 173 the master is still unallocated.
 174 This area is called the \fIcavity\fR;  for the first slave it
 175 is the entire area of the master.
 176 .PP
 177 For each slave the packer carries out the following steps:
 178 .IP [1]
 179 The packer allocates a rectangular \fIparcel\fR for the slave
 180 along the side of the cavity given by the slave's \fB\-side\fR option.
 181 If the side is top or bottom then the width of the parcel is
 182 the width of the cavity and its height is the requested height
 183 of the slave plus the \fB\-ipady\fR and \fB\-pady\fR options.
 184 For the left or right side the height of the parcel is
 185 the height of the cavity and the width is the requested width
 186 of the slave plus the \fB\-ipadx\fR and \fB\-padx\fR options.
 187 The parcel may be enlarged further because of the \fB\-expand\fR
 188 option (see ``EXPANSION'' below)
 189 .IP [2]
 190 The packer chooses the dimensions of the slave.
 191 The width will normally be the slave's requested width plus
 192 twice its \fB\-ipadx\fR option and the height will normally be
 193 the slave's requested height plus twice its \fB\-ipady\fR
 194 option.
 195 However, if the \fB\-fill\fR option is \fBx\fR or \fBboth\fR
 196 then the width of the slave is expanded to fill the width of the parcel,
 197 minus twice the \fB\-padx\fR option.
 198 If the \fB\-fill\fR option is \fBy\fR or \fBboth\fR
 199 then the height of the slave is expanded to fill the width of the parcel,
 200 minus twice the \fB\-pady\fR option.
 201 .IP [3]
 202 The packer positions the slave over its parcel.
 203 If the slave is smaller than the parcel then the \fB\-anchor\fR
 204 option determines where in the parcel the slave will be placed.
 205 If \fB\-padx\fR or \fB\-pady\fR is non-zero, then the given
 206 amount of external padding will always be left between the
 207 slave and the edges of the parcel.
 208 .PP
 209 Once a given slave has been packed, the area of its parcel
 210 is subtracted from the cavity, leaving a smaller rectangular
 211 cavity for the next slave.
 212 If a slave doesn't use all of its parcel, the unused space
 213 in the parcel will not be used by subsequent slaves.
 214 If the cavity should become too small to meet the needs of
 215 a slave then the slave will be given whatever space is
 216 left in the cavity.
 217 If the cavity shrinks to zero size, then all remaining slaves
 218 on the packing list will be unmapped from the screen until
 219 the master window becomes large enough to hold them again.
 220
 221 .SH "EXPANSION"
 222 .PP
 223 If a master window is so large that there will be extra space
 224 left over after all of its slaves have been packed, then the
 225 extra space is distributed uniformly among all of the slaves
 226 for which the \fB\-expand\fR option is set.
 227 Extra horizontal space is distributed among the expandable
 228 slaves whose \fB\-side\fR is \fBleft\fR or \fBright\fR,
 229 and extra vertical space is distributed among the expandable
 230 slaves whose \fB\-side\fR is \fBtop\fR or \fBbottom\fR.
 231
 232 .SH "GEOMETRY PROPAGATION"
 233 .PP
 234 The packer normally computes how large a master must be to
 235 just exactly meet the needs of its slaves, and it sets the
 236 requested width and height of the master to these dimensions.
 237 This causes geometry information to propagate up through a
 238 window hierarchy to a top-level window so that the entire
 239 sub-tree sizes itself to fit the needs of the leaf windows.
 240 However, the \fBpack propagate\fR command may be used to
 241 turn off propagation for one or more masters.
 242 If propagation is disabled then the packer will not set
 243 the requested width and height of the packer.
 244 This may be useful if, for example, you wish for a master
 245 window to have a fixed size that you specify.
 246
 247 .SH "RESTRICTIONS ON MASTER WINDOWS"
 248 .PP
 249 The master for each slave must either be the slave's parent
 250 (the default) or a descendant of the slave's parent.
 251 This restriction is necessary to guarantee that the
 252 slave can be placed over any part of its master that is
 253 visible without danger of the slave being clipped by its parent.
 254
 255 .SH "PACKING ORDER"
 256 .PP
 257 If the master for a slave is not its parent then you must make sure
 258 that the slave is higher in the stacking order than the master.
 259 Otherwise the master will obscure the slave and it will appear as
 260 if the slave hasn't been packed correctly.
 261 The easiest way to make sure the slave is higher than the master is
 262 to create the master window first:  the most recently created window
 263 will be highest in the stacking order.
 264 Or, you can use the \fBraise\fR and \fBlower\fR commands to change
 265 the stacking order of either the master or the slave.
 266
 267 .SH KEYWORDS
 268 geometry manager, location, packer, parcel, propagation, size