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