Commit | Line | Data |
---|---|---|
86530b38 AT |
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 |