1# Copyright (c) 1990-1994 The Regents of the University of California. 2# Copyright (c) 1994-1996 Sun Microsystems, Inc. 3# Copyright (c) 2003 Dmitry Karasik 4# 5# This software is copyrighted by the Regents of the University of 6# California, Sun Microsystems, Inc., and other parties. The following 7# terms apply to all files associated with the software unless explicitly 8# disclaimed in individual files. 9# 10# The authors hereby grant permission to use, copy, modify, distribute, 11# and license this software and its documentation for any purpose, provided 12# that existing copyright notices are retained in all copies and that this 13# notice is included verbatim in any distributions. No written agreement, 14# license, or royalty fee is required for any of the authorized uses. 15# Modifications to this software may be copyrighted by their authors 16# and need not follow the licensing terms described here, provided that 17# the new terms are clearly indicated on the first page of each file where 18# they apply. 19# 20# IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY 21# FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES 22# ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY 23# DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE 24# POSSIBILITY OF SUCH DAMAGE. 25# 26# THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, 27# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, 28# FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE 29# IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE 30# NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR 31# MODIFICATIONS. 32# 33# RESTRICTED RIGHTS: Use, duplication or disclosure by the government 34# is subject to the restrictions as set forth in subparagraph (c) (1) (ii) 35# of the Rights in Technical Data and Computer Software Clause as DFARS 36# 252.227-7013 and FAR 52.227-19. 37 38 39=head1 NAME 40 41Prima::Widget::pack - Geometry manager that packs around edges of cavity 42 43=head1 SYNOPSIS 44 45 $widget-> pack( args); 46 47 $widget-> packInfo( args); 48 $widget-> geometry( gt::Pack); 49 50 51=head1 DESCRIPTION 52 53The B<pack> method is used to communicate with the packer, 54a geometry manager that arranges the children of a owner by 55packing them in order around the edges of the owner. 56 57In this port of B<Tk::pack> it is normal to pack widgets one-at-a-time 58using the widget object to be packed to invoke a method call. 59This is a slight distortion of the original Tcl-Tk interface (which 60can handle lists of windows to one pack method call) but Tk reports 61that it has proven effective in practice. 62 63The B<pack> method can have any of several forms, depending 64on I<Option>: 65 66=over 4 67 68=item pack %OPTIONS 69 70The options consist of pairs of arguments that specify how 71to manage the slave. 72See L<"The packer algorithm"> below for details on how the options 73are used by the packer. 74The following options are supported: 75 76=over 8 77 78=item B<after> =E<gt> I<$other> 79 80I<$other> must be another window. 81Use its master as the master for the slave, and insert 82the slave just after I<$other> in the packing order. 83 84=item B<anchor> =E<gt> I<anchor> 85 86I<Anchor> must be a valid anchor position such as B<n> 87or B<sw>; it specifies where to position each slave in its 88parcel. 89Defaults to B<center>. 90 91=item B<before> =E<gt> I<$other> 92 93I<$other> must be another window. 94Use its master as the master for the slave, and insert 95the slave just before I<$other> in the packing order. 96 97=item B<expand> =E<gt> I<boolean> 98 99Specifies whether the slave should be expanded to consume 100extra space in their master. 101I<Boolean> may have any proper boolean value, such as B<1> 102or B<no>. 103Defaults to 0. 104 105=item B<fill> =E<gt> I<style> 106 107If a slave's parcel is larger than its requested dimensions, this 108option may be used to stretch the slave. 109I<Style> must have one of the following values: 110 111=over 12 112 113=item B<none> 114 115Give the slave its requested dimensions plus any internal padding 116requested with B<-ipadx> or B<-ipady>. This is the default. 117 118=item B<x> 119 120Stretch the slave horizontally to fill the entire width of its 121parcel (except leave external padding as specified by B<-padx>). 122 123=item B<y> 124 125Stretch the slave vertically to fill the entire height of its 126parcel (except leave external padding as specified by B<-pady>). 127 128=item B<both> 129 130Stretch the slave both horizontally and vertically. 131 132=back 133 134=item B<in> =E<gt> I<$master> 135 136Insert the slave(s) at the end of the packing order for the master 137window given by I<$master>. Currently, only the immediate owner 138can be accepted as master. 139 140=item B<ipad> =E<gt> I<amount> 141 142I<Amount> specifies how much both horizontal and vertical internal padding to 143leave on each side of the slave(s). 144I<Amount> must be a valid screen distance, such as B<2> or B<.5c>. 145It defaults to 0. 146 147=item B<ipadx> =E<gt> I<amount> 148 149I<Amount> specifies how much horizontal internal padding to 150leave on each side of the slave(s). 151I<Amount> must be a valid screen distance, such as B<2> or B<.5c>. 152It defaults to 0. 153 154=item B<ipady> =E<gt> I<amount> 155 156I<Amount> specifies how much vertical internal padding to 157leave on each side of the slave(s). 158I<Amount> defaults to 0. 159 160=item B<pad> =E<gt> I<amount> 161 162I<Amount> specifies how much horizontal and vertical external padding to 163leave on each side of the slave(s). 164I<Amount> defaults to 0. 165 166=item B<padx> =E<gt> I<amount> 167 168I<Amount> specifies how much horizontal external padding to 169leave on each side of the slave(s). 170I<Amount> defaults to 0. 171 172=item B<pady> =E<gt> I<amount> 173 174I<Amount> specifies how much vertical external padding to 175leave on each side of the slave(s). 176I<Amount> defaults to 0. 177 178=item B<side> =E<gt> I<side> 179 180Specifies which side of the master the slave(s) will be packed against. 181Must be B<left>, B<right>, B<top>, or B<bottom>. 182Defaults to B<top>. 183 184=back 185 186=back 187 188If no B<in>, B<after> or B<before> option is specified 189then slave will be inserted at the end of the packing list 190for its owner unless it is already managed by the packer (in which 191case it will be left where it is). 192If one of these options is specified then slave will be 193inserted at the specified point. 194If the slave are already managed by the geometry manager 195then any unspecified options for them retain their previous values rather 196than receiving default values. 197 198=over 4 199 200=item packForget 201 202Removes I<slave> from the packing order for its 203master and unmaps its window. 204The slave will no longer be managed by the packer. 205 206=item packInfo [ %OPTIONS ] 207 208In get-mode, returns a list whose elements are the current configuration state of 209the slave given by I<$slave>. 210The first two elements of the list are ``B<in>=E<gt>I<$master>'' where 211I<$master> is the slave's master. 212 213In set-mode, sets all B<pack> parameters, but does not set 214widget geometry property to C<gt::Pack>. 215 216=item packPropagate BOOLEAN 217 218If I<boolean> has a true boolean value 219then propagation is enabled for I<$master>, 220(see L<"Geometry propagation"> below). 221If I<boolean> has a false boolean value then propagation is 222disabled for I<$master>. 223If I<boolean> is omitted then the method returns B<0> or 224B<1> to indicate whether propagation is currently enabled 225for I<$master>. 226 227Propagation is enabled by default. 228 229=item packSlaves 230 231Returns a list of all of the slaves in the packing order for I<$master>. 232The order of the slaves in the list is the same as their order in 233the packing order. 234If I<$master> has no slaves then an empty list/string is returned in 235array/scalar context, respectively 236 237=back 238 239=head1 The packer algorithm 240 241For each master the packer maintains an ordered list of slaves 242called the I<packing list>. 243The B<in>, B<after>, and B<before> configuration 244options are used to specify the master for each slave and the slave's 245position in the packing list. 246If none of these options is given for a slave then the slave 247is added to the end of the packing list for its owner. 248 249The packer arranges the slaves for a master by scanning the 250packing list in order. 251At the time it processes each slave, a rectangular area within 252the master is still unallocated. 253This area is called the I<cavity>; for the first slave it 254is the entire area of the master. 255 256For each slave the packer carries out the following steps: 257 258=over 4 259 260=item * 261 262The packer allocates a rectangular I<parcel> for the slave 263along the side of the cavity given by the slave's B<side> option. 264If the side is top or bottom then the width of the parcel is 265the width of the cavity and its height is the requested height 266of the slave plus the B<ipady> and B<pady> options. 267For the left or right side the height of the parcel is 268the height of the cavity and the width is the requested width 269of the slave plus the B<ipadx> and B<padx> options. 270The parcel may be enlarged further because of the B<expand> 271option (see L<"Expansion"> below) 272 273=item * 274 275The packer chooses the dimensions of the slave. 276The width will normally be the slave's requested width plus 277twice its B<ipadx> option and the height will normally be 278the slave's requested height plus twice its B<ipady> 279option. 280However, if the B<fill> option is B<x> or B<both> 281then the width of the slave is expanded to fill the width of the parcel, 282minus twice the B<padx> option. 283If the B<fill> option is B<y> or B<both> 284then the height of the slave is expanded to fill the width of the parcel, 285minus twice the B<pady> option. 286 287=item * 288 289The packer positions the slave over its parcel. 290If the slave is smaller than the parcel then the B<-anchor> 291option determines where in the parcel the slave will be placed. 292If B<padx> or B<pady> is non-zero, then the given 293amount of external padding will always be left between the 294slave and the edges of the parcel. 295 296Once a given slave has been packed, the area of its parcel 297is subtracted from the cavity, leaving a smaller rectangular 298cavity for the next slave. 299If a slave doesn't use all of its parcel, the unused space 300in the parcel will not be used by subsequent slaves. 301If the cavity should become too small to meet the needs of 302a slave then the slave will be given whatever space is 303left in the cavity. 304If the cavity shrinks to zero size, then all remaining slaves 305on the packing list will be unmapped from the screen until 306the master window becomes large enough to hold them again. 307 308=back 309 310=head1 Expansion 311 312If a master window is so large that there will be extra space 313left over after all of its slaves have been packed, then the 314extra space is distributed uniformly among all of the slaves 315for which the B<expand> option is set. 316Extra horizontal space is distributed among the expandable 317slaves whose B<side> is B<left> or B<right>, 318and extra vertical space is distributed among the expandable 319slaves whose B<side> is B<top> or B<bottom>. 320 321=head1 Geometry propagation 322 323The packer normally computes how large a master must be to 324just exactly meet the needs of its slaves, and it sets the 325requested width and height of the master to these dimensions. 326This causes geometry information to propagate up through a 327window hierarchy to a top-level window so that the entire 328sub-tree sizes itself to fit the needs of the leaf windows. 329However, the B<packPropagate> method may be used to 330turn off propagation for one or more masters. 331If propagation is disabled then the packer will not set 332the requested width and height. 333This may be useful if, for example, you wish for a master 334window to have a fixed size that you specify. 335 336=head1 Restrictions on master windows 337 338The master for each slave must not be a child of the slave, 339and must not be present in any other list of slaves that 340directly or indirectly refers to the slave. 341 342=head1 Packing order 343 344If the master for a slave is not its owner then you must make sure 345that the slave is higher in the stacking order than the master. 346Otherwise the master will obscure the slave and it will appear as 347if the slave hasn't been packed correctly. 348The easiest way to make sure the slave is higher than the master is 349to create the master window first: the most recently created window 350will be highest in the stacking order. 351Or, you can use the B<bring_to_front> and B<send_to_back> methods to change 352the stacking order of either the master or the slave. 353 354=head1 SEE ALSO 355 356L<Prima>, L<Prima::Widget> 357 358L<Tk::pack|Tk::pack> 359L<Tk::place|Tk::place> 360 361=cut 362