| 1 | # Copyright (c) 1990-1994 The Regents of the University of California. |
| 2 | # Copyright (c) 1994-1996 Sun Microsystems, Inc. |
| 3 | # See the file "license.terms" for information on usage and redistribution |
| 4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| 5 | # |
| 6 | # |
| 7 | |
| 8 | =head1 NAME |
| 9 | |
| 10 | Tk::pack - Geometry manager that packs around edges of cavity |
| 11 | |
| 12 | =for category Tk Geometry Management |
| 13 | |
| 14 | =head1 SYNOPSIS |
| 15 | |
| 16 | S< >I<$widget>-E<gt>B<pack>?(I<args>)? |
| 17 | |
| 18 | S< >I<$widget>-E<gt>B<pack>I<Option>?(I<args>)? |
| 19 | |
| 20 | =head1 DESCRIPTION |
| 21 | |
| 22 | The B<pack> method 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 | |
| 26 | In this B<perl> port of Tk it is normal to pack widgets one-at-a-time |
| 27 | using the widget object to be packed to invoke a method call. |
| 28 | This is a slight distortion of underlying Tk interface (which |
| 29 | can handle lists of windows to one pack method call) but has proven |
| 30 | effective in practice. |
| 31 | |
| 32 | The B<pack> method can have any of several forms, depending |
| 33 | on I<Option>: |
| 34 | |
| 35 | =over 4 |
| 36 | |
| 37 | =item I<$slave>-E<gt>B<pack>?(I<options>)? |
| 38 | |
| 39 | The options consist of pairs of arguments that specify how |
| 40 | to manage the slave. |
| 41 | See L<"THE PACKER ALGORITHM"> below for details on how the options |
| 42 | are used by the packer. |
| 43 | The following options are supported: |
| 44 | |
| 45 | =over 8 |
| 46 | |
| 47 | =item B<-after> =E<gt> I<$other> |
| 48 | |
| 49 | I<$other> must be another window. |
| 50 | Use its master as the master for the slave, and insert |
| 51 | the slave just after I<$other> in the packing order. |
| 52 | |
| 53 | =item B<-anchor> =E<gt> I<anchor> |
| 54 | |
| 55 | I<Anchor> must be a valid anchor position such as B<n> |
| 56 | or B<sw>; it specifies where to position each slave in its |
| 57 | parcel. |
| 58 | Defaults to B<center>. |
| 59 | |
| 60 | =item B<-before> =E<gt> I<$other> |
| 61 | |
| 62 | I<$other> must be another window. |
| 63 | Use its master as the master for the slave, and insert |
| 64 | the slave just before I<$other> in the packing order. |
| 65 | |
| 66 | =item B<-expand> =E<gt> I<boolean> |
| 67 | |
| 68 | Specifies whether the slave should be expanded to consume |
| 69 | extra space in their master. |
| 70 | I<Boolean> may have any proper boolean value, such as B<1> |
| 71 | or B<no>. |
| 72 | Defaults to 0. |
| 73 | |
| 74 | =item B<-fill> =E<gt> I<style> |
| 75 | |
| 76 | If a slave's parcel is larger than its requested dimensions, this |
| 77 | option may be used to stretch the slave. |
| 78 | I<Style> must have one of the following values: |
| 79 | |
| 80 | =over 12 |
| 81 | |
| 82 | =item B<none> |
| 83 | |
| 84 | Give the slave its requested dimensions plus any internal padding |
| 85 | requested with B<-ipadx> or B<-ipady>. This is the default. |
| 86 | |
| 87 | =item B<x> |
| 88 | |
| 89 | Stretch the slave horizontally to fill the entire width of its |
| 90 | parcel (except leave external padding as specified by B<-padx>). |
| 91 | |
| 92 | =item B<y> |
| 93 | |
| 94 | Stretch the slave vertically to fill the entire height of its |
| 95 | parcel (except leave external padding as specified by B<-pady>). |
| 96 | |
| 97 | =item B<both> |
| 98 | |
| 99 | Stretch the slave both horizontally and vertically. |
| 100 | |
| 101 | =back |
| 102 | |
| 103 | =item B<-in> =E<gt> I<$master> |
| 104 | |
| 105 | Insert the slave(s) at the end of the packing order for the master |
| 106 | window given by I<$master>. |
| 107 | |
| 108 | =item B<-ipadx> =E<gt> I<amount> |
| 109 | |
| 110 | I<Amount> specifies how much horizontal internal padding to |
| 111 | leave on each side of the slave(s). |
| 112 | I<Amount> must be a valid screen distance, such as B<2> or B<.5c>. |
| 113 | It defaults to 0. |
| 114 | |
| 115 | =item B<-ipady> =E<gt> I<amount> |
| 116 | |
| 117 | I<Amount> specifies how much vertical internal padding to |
| 118 | leave on each side of the slave(s). |
| 119 | I<Amount> defaults to 0. |
| 120 | |
| 121 | =item B<-padx> =E<gt> I<amount> |
| 122 | |
| 123 | I<Amount> specifies how much horizontal external padding to |
| 124 | leave on each side of the slave(s). |
| 125 | I<Amount> defaults to 0. |
| 126 | |
| 127 | =item B<-pady> =E<gt> I<amount> |
| 128 | |
| 129 | I<Amount> specifies how much vertical external padding to |
| 130 | leave on each side of the slave(s). |
| 131 | I<Amount> defaults to 0. |
| 132 | |
| 133 | =item B<-side> =E<gt> I<side> |
| 134 | |
| 135 | Specifies which side of the master the slave(s) will be packed against. |
| 136 | Must be B<left>, B<right>, B<top>, or B<bottom>. |
| 137 | Defaults to B<top>. |
| 138 | |
| 139 | =back |
| 140 | |
| 141 | =back |
| 142 | |
| 143 | If no B<-in>, B<-after> or B<-before> option is specified |
| 144 | then slave will be inserted at the end of the packing list |
| 145 | for its parent unless it is already managed by the packer (in which |
| 146 | case it will be left where it is). |
| 147 | If one of these options is specified then slave will be |
| 148 | inserted at the specified point. |
| 149 | If the slave are already managed by the geometry manager |
| 150 | then any unspecified options for them retain their previous values rather |
| 151 | than receiving default values. |
| 152 | |
| 153 | =over 4 |
| 154 | |
| 155 | =item I<$slave>-E<gt>B<packForget> |
| 156 | |
| 157 | Removes I<slave> from the packing order for its |
| 158 | master and unmaps its window. |
| 159 | The slave will no longer be managed by the packer. |
| 160 | |
| 161 | =item I<$slave>-E<gt>B<packInfo> |
| 162 | |
| 163 | Returns a list whose elements are the current configuration state of |
| 164 | the slave given by I<$slave> in the same option-value form that |
| 165 | might be specified to B<packConfigure>. |
| 166 | The first two elements of the list are ``B<-in>=E<gt>I<$master>'' where |
| 167 | I<$master> is the slave's master. |
| 168 | |
| 169 | =item I<$master>-E<gt>B<packPropagate>?(I<boolean>)? |
| 170 | |
| 171 | If I<boolean> has a true boolean value such as B<1> or B<on> |
| 172 | then propagation is enabled for I<$master>, |
| 173 | (see L<"GEOMETRY PROPAGATION"> below). |
| 174 | If I<boolean> has a false boolean value then propagation is |
| 175 | disabled for I<$master>. |
| 176 | In either of these cases an empty string is returned. |
| 177 | If I<boolean> is omitted then the method returns B<0> or |
| 178 | B<1> to indicate whether propagation is currently enabled |
| 179 | for I<$master>. |
| 180 | Propagation is enabled by default. |
| 181 | |
| 182 | =item I<$master>-E<gt>B<packSlaves> |
| 183 | |
| 184 | Returns a list of all of the slaves in the packing order for I<$master>. |
| 185 | The order of the slaves in the list is the same as their order in |
| 186 | the packing order. |
| 187 | If I<$master> has no slaves then an empty list/string is returned in |
| 188 | array/scalar context, respectively |
| 189 | |
| 190 | =back |
| 191 | |
| 192 | =head1 THE PACKER ALGORITHM |
| 193 | |
| 194 | For each master the packer maintains an ordered list of slaves |
| 195 | called the I<packing list>. |
| 196 | The B<-in>, B<-after>, and B<-before> configuration |
| 197 | options are used to specify the master for each slave and the slave's |
| 198 | position in the packing list. |
| 199 | If none of these options is given for a slave then the slave |
| 200 | is added to the end of the packing list for its parent. |
| 201 | |
| 202 | The packer arranges the slaves for a master by scanning the |
| 203 | packing list in order. |
| 204 | At the time it processes each slave, a rectangular area within |
| 205 | the master is still unallocated. |
| 206 | This area is called the I<cavity>; for the first slave it |
| 207 | is the entire area of the master. |
| 208 | |
| 209 | For each slave the packer carries out the following steps: |
| 210 | |
| 211 | =over 4 |
| 212 | |
| 213 | =item [1] |
| 214 | |
| 215 | The packer allocates a rectangular I<parcel> for the slave |
| 216 | along the side of the cavity given by the slave's B<-side> option. |
| 217 | If the side is top or bottom then the width of the parcel is |
| 218 | the width of the cavity and its height is the requested height |
| 219 | of the slave plus the B<-ipady> and B<-pady> options. |
| 220 | For the left or right side the height of the parcel is |
| 221 | the height of the cavity and the width is the requested width |
| 222 | of the slave plus the B<-ipadx> and B<-padx> options. |
| 223 | The parcel may be enlarged further because of the B<-expand> |
| 224 | option (see L<"EXPANSION"> below) |
| 225 | |
| 226 | =item [2] |
| 227 | |
| 228 | The packer chooses the dimensions of the slave. |
| 229 | The width will normally be the slave's requested width plus |
| 230 | twice its B<-ipadx> option and the height will normally be |
| 231 | the slave's requested height plus twice its B<-ipady> |
| 232 | option. |
| 233 | However, if the B<-fill> option is B<x> or B<both> |
| 234 | then the width of the slave is expanded to fill the width of the parcel, |
| 235 | minus twice the B<-padx> option. |
| 236 | If the B<-fill> option is B<y> or B<both> |
| 237 | then the height of the slave is expanded to fill the width of the parcel, |
| 238 | minus twice the B<-pady> option. |
| 239 | |
| 240 | =item [3] |
| 241 | |
| 242 | The packer positions the slave over its parcel. |
| 243 | If the slave is smaller than the parcel then the B<-anchor> |
| 244 | option determines where in the parcel the slave will be placed. |
| 245 | If B<-padx> or B<-pady> is non-zero, then the given |
| 246 | amount of external padding will always be left between the |
| 247 | slave and the edges of the parcel. |
| 248 | |
| 249 | Once a given slave has been packed, the area of its parcel |
| 250 | is subtracted from the cavity, leaving a smaller rectangular |
| 251 | cavity for the next slave. |
| 252 | If a slave doesn't use all of its parcel, the unused space |
| 253 | in the parcel will not be used by subsequent slaves. |
| 254 | If the cavity should become too small to meet the needs of |
| 255 | a slave then the slave will be given whatever space is |
| 256 | left in the cavity. |
| 257 | If the cavity shrinks to zero size, then all remaining slaves |
| 258 | on the packing list will be unmapped from the screen until |
| 259 | the master window becomes large enough to hold them again. |
| 260 | |
| 261 | =back |
| 262 | |
| 263 | =head1 EXPANSION |
| 264 | |
| 265 | If a master window is so large that there will be extra space |
| 266 | left over after all of its slaves have been packed, then the |
| 267 | extra space is distributed uniformly among all of the slaves |
| 268 | for which the B<-expand> option is set. |
| 269 | Extra horizontal space is distributed among the expandable |
| 270 | slaves whose B<-side> is B<left> or B<right>, |
| 271 | and extra vertical space is distributed among the expandable |
| 272 | slaves whose B<-side> is B<top> or B<bottom>. |
| 273 | |
| 274 | =head1 GEOMETRY PROPAGATION |
| 275 | |
| 276 | The packer normally computes how large a master must be to |
| 277 | just exactly meet the needs of its slaves, and it sets the |
| 278 | requested width and height of the master to these dimensions. |
| 279 | This causes geometry information to propagate up through a |
| 280 | window hierarchy to a top-level window so that the entire |
| 281 | sub-tree sizes itself to fit the needs of the leaf windows. |
| 282 | However, the B<packPropagate> method may be used to |
| 283 | turn off propagation for one or more masters. |
| 284 | If propagation is disabled then the packer will not set |
| 285 | the requested width and height of the packer. |
| 286 | This may be useful if, for example, you wish for a master |
| 287 | window to have a fixed size that you specify. |
| 288 | |
| 289 | =head1 RESTRICTIONS ON MASTER WINDOWS |
| 290 | |
| 291 | The master for each slave must either be the slave's parent |
| 292 | (the default) or a descendant of the slave's parent. |
| 293 | This restriction is necessary to guarantee that the |
| 294 | slave can be placed over any part of its master that is |
| 295 | visible without danger of the slave being clipped by its parent. |
| 296 | |
| 297 | =head1 PACKING ORDER |
| 298 | |
| 299 | If the master for a slave is not its parent then you must make sure |
| 300 | that the slave is higher in the stacking order than the master. |
| 301 | Otherwise the master will obscure the slave and it will appear as |
| 302 | if the slave hasn't been packed correctly. |
| 303 | The easiest way to make sure the slave is higher than the master is |
| 304 | to create the master window first: the most recently created window |
| 305 | will be highest in the stacking order. |
| 306 | Or, you can use the B<raise> and B<lower> methods to change |
| 307 | the stacking order of either the master or the slave. |
| 308 | |
| 309 | =head1 SEE ALSO |
| 310 | |
| 311 | L<Tk::form|Tk::form> |
| 312 | L<Tk::grid|Tk::grid> |
| 313 | L<Tk::place|Tk::place> |
| 314 | |
| 315 | =head1 KEYWORDS |
| 316 | |
| 317 | geometry manager, location, packer, parcel, propagation, size |
| 318 | |
| 319 | =cut |
| 320 | |