Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PACK 1" | |
132 | .TH PACK 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | Tk::pack \- Geometry manager that packs around edges of cavity | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | \&\ \fI$widget\fR\->\fBpack\fR?(\fIargs\fR)? | |
138 | .PP | |
139 | \&\ \fI$widget\fR\->\fBpack\fR\fIOption\fR?(\fIargs\fR)? | |
140 | .SH "DESCRIPTION" | |
141 | .IX Header "DESCRIPTION" | |
142 | The \fBpack\fR method is used to communicate with the packer, | |
143 | a geometry manager that arranges the children of a parent by | |
144 | packing them in order around the edges of the parent. | |
145 | .PP | |
146 | In this \fBperl\fR port of Tk it is normal to pack widgets one-at-a-time | |
147 | using the widget object to be packed to invoke a method call. | |
148 | This is a slight distortion of underlying Tk interface (which | |
149 | can handle lists of windows to one pack method call) but has proven | |
150 | effective in practice. | |
151 | .PP | |
152 | The \fBpack\fR method can have any of several forms, depending | |
153 | on \fIOption\fR: | |
154 | .IP "\fI$slave\fR\->\fBpack\fR?(\fIoptions\fR)?" 4 | |
155 | .IX Item "$slave->pack?(options)?" | |
156 | The options consist of pairs of arguments that specify how | |
157 | to manage the slave. | |
158 | See \*(L"\s-1THE\s0 \s-1PACKER\s0 \s-1ALGORITHM\s0\*(R" below for details on how the options | |
159 | are used by the packer. | |
160 | The following options are supported: | |
161 | .RS 4 | |
162 | .IP "\fB\-after\fR => \fI$other\fR" 8 | |
163 | .IX Item "-after => $other" | |
164 | \&\fI$other\fR must be another window. | |
165 | Use its master as the master for the slave, and insert | |
166 | the slave just after \fI$other\fR in the packing order. | |
167 | .IP "\fB\-anchor\fR => \fIanchor\fR" 8 | |
168 | .IX Item "-anchor => anchor" | |
169 | \&\fIAnchor\fR must be a valid anchor position such as \fBn\fR | |
170 | or \fBsw\fR; it specifies where to position each slave in its | |
171 | parcel. | |
172 | Defaults to \fBcenter\fR. | |
173 | .IP "\fB\-before\fR => \fI$other\fR" 8 | |
174 | .IX Item "-before => $other" | |
175 | \&\fI$other\fR must be another window. | |
176 | Use its master as the master for the slave, and insert | |
177 | the slave just before \fI$other\fR in the packing order. | |
178 | .IP "\fB\-expand\fR => \fIboolean\fR" 8 | |
179 | .IX Item "-expand => boolean" | |
180 | Specifies whether the slave should be expanded to consume | |
181 | extra space in their master. | |
182 | \&\fIBoolean\fR may have any proper boolean value, such as \fB1\fR | |
183 | or \fBno\fR. | |
184 | Defaults to 0. | |
185 | .IP "\fB\-fill\fR => \fIstyle\fR" 8 | |
186 | .IX Item "-fill => style" | |
187 | If a slave's parcel is larger than its requested dimensions, this | |
188 | option may be used to stretch the slave. | |
189 | \&\fIStyle\fR must have one of the following values: | |
190 | .RS 8 | |
191 | .IP "\fBnone\fR" 12 | |
192 | .IX Item "none" | |
193 | Give the slave its requested dimensions plus any internal padding | |
194 | requested with \fB\-ipadx\fR or \fB\-ipady\fR. This is the default. | |
195 | .IP "\fBx\fR" 12 | |
196 | .IX Item "x" | |
197 | Stretch the slave horizontally to fill the entire width of its | |
198 | parcel (except leave external padding as specified by \fB\-padx\fR). | |
199 | .IP "\fBy\fR" 12 | |
200 | .IX Item "y" | |
201 | Stretch the slave vertically to fill the entire height of its | |
202 | parcel (except leave external padding as specified by \fB\-pady\fR). | |
203 | .IP "\fBboth\fR" 12 | |
204 | .IX Item "both" | |
205 | Stretch the slave both horizontally and vertically. | |
206 | .RE | |
207 | .RS 8 | |
208 | .RE | |
209 | .IP "\fB\-in\fR => \fI$master\fR" 8 | |
210 | .IX Item "-in => $master" | |
211 | Insert the slave(s) at the end of the packing order for the master | |
212 | window given by \fI$master\fR. | |
213 | .IP "\fB\-ipadx\fR => \fIamount\fR" 8 | |
214 | .IX Item "-ipadx => amount" | |
215 | \&\fIAmount\fR specifies how much horizontal internal padding to | |
216 | leave on each side of the slave(s). | |
217 | \&\fIAmount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. | |
218 | It defaults to 0. | |
219 | .IP "\fB\-ipady\fR => \fIamount\fR" 8 | |
220 | .IX Item "-ipady => amount" | |
221 | \&\fIAmount\fR specifies how much vertical internal padding to | |
222 | leave on each side of the slave(s). | |
223 | \&\fIAmount\fR defaults to 0. | |
224 | .IP "\fB\-padx\fR => \fIamount\fR" 8 | |
225 | .IX Item "-padx => amount" | |
226 | \&\fIAmount\fR specifies how much horizontal external padding to | |
227 | leave on each side of the slave(s). | |
228 | \&\fIAmount\fR defaults to 0. | |
229 | .IP "\fB\-pady\fR => \fIamount\fR" 8 | |
230 | .IX Item "-pady => amount" | |
231 | \&\fIAmount\fR specifies how much vertical external padding to | |
232 | leave on each side of the slave(s). | |
233 | \&\fIAmount\fR defaults to 0. | |
234 | .IP "\fB\-side\fR => \fIside\fR" 8 | |
235 | .IX Item "-side => side" | |
236 | Specifies which side of the master the slave(s) will be packed against. | |
237 | Must be \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. | |
238 | Defaults to \fBtop\fR. | |
239 | .RE | |
240 | .RS 4 | |
241 | .RE | |
242 | .PP | |
243 | If no \fB\-in\fR, \fB\-after\fR or \fB\-before\fR option is specified | |
244 | then slave will be inserted at the end of the packing list | |
245 | for its parent unless it is already managed by the packer (in which | |
246 | case it will be left where it is). | |
247 | If one of these options is specified then slave will be | |
248 | inserted at the specified point. | |
249 | If the slave are already managed by the geometry manager | |
250 | then any unspecified options for them retain their previous values rather | |
251 | than receiving default values. | |
252 | .IP "\fI$slave\fR\->\fBpackForget\fR" 4 | |
253 | .IX Item "$slave->packForget" | |
254 | Removes \fIslave\fR from the packing order for its | |
255 | master and unmaps its window. | |
256 | The slave will no longer be managed by the packer. | |
257 | .IP "\fI$slave\fR\->\fBpackInfo\fR" 4 | |
258 | .IX Item "$slave->packInfo" | |
259 | Returns a list whose elements are the current configuration state of | |
260 | the slave given by \fI$slave\fR in the same option-value form that | |
261 | might be specified to \fBpackConfigure\fR. | |
262 | The first two elements of the list are ``\fB\-in\fR=>\fI$master\fR'' where | |
263 | \&\fI$master\fR is the slave's master. | |
264 | .IP "\fI$master\fR\->\fBpackPropagate\fR?(\fIboolean\fR)?" 4 | |
265 | .IX Item "$master->packPropagate?(boolean)?" | |
266 | If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR | |
267 | then propagation is enabled for \fI$master\fR, | |
268 | (see \*(L"\s-1GEOMETRY\s0 \s-1PROPAGATION\s0\*(R" below). | |
269 | If \fIboolean\fR has a false boolean value then propagation is | |
270 | disabled for \fI$master\fR. | |
271 | In either of these cases an empty string is returned. | |
272 | If \fIboolean\fR is omitted then the method returns \fB0\fR or | |
273 | \&\fB1\fR to indicate whether propagation is currently enabled | |
274 | for \fI$master\fR. | |
275 | Propagation is enabled by default. | |
276 | .IP "\fI$master\fR\->\fBpackSlaves\fR" 4 | |
277 | .IX Item "$master->packSlaves" | |
278 | Returns a list of all of the slaves in the packing order for \fI$master\fR. | |
279 | The order of the slaves in the list is the same as their order in | |
280 | the packing order. | |
281 | If \fI$master\fR has no slaves then an empty list/string is returned in | |
282 | array/scalar context, respectively | |
283 | .SH "THE PACKER ALGORITHM" | |
284 | .IX Header "THE PACKER ALGORITHM" | |
285 | For each master the packer maintains an ordered list of slaves | |
286 | called the \fIpacking list\fR. | |
287 | The \fB\-in\fR, \fB\-after\fR, and \fB\-before\fR configuration | |
288 | options are used to specify the master for each slave and the slave's | |
289 | position in the packing list. | |
290 | If none of these options is given for a slave then the slave | |
291 | is added to the end of the packing list for its parent. | |
292 | .PP | |
293 | The packer arranges the slaves for a master by scanning the | |
294 | packing list in order. | |
295 | At the time it processes each slave, a rectangular area within | |
296 | the master is still unallocated. | |
297 | This area is called the \fIcavity\fR; for the first slave it | |
298 | is the entire area of the master. | |
299 | .PP | |
300 | For each slave the packer carries out the following steps: | |
301 | .IP "[1]" 4 | |
302 | .IX Item "[1]" | |
303 | The packer allocates a rectangular \fIparcel\fR for the slave | |
304 | along the side of the cavity given by the slave's \fB\-side\fR option. | |
305 | If the side is top or bottom then the width of the parcel is | |
306 | the width of the cavity and its height is the requested height | |
307 | of the slave plus the \fB\-ipady\fR and \fB\-pady\fR options. | |
308 | For the left or right side the height of the parcel is | |
309 | the height of the cavity and the width is the requested width | |
310 | of the slave plus the \fB\-ipadx\fR and \fB\-padx\fR options. | |
311 | The parcel may be enlarged further because of the \fB\-expand\fR | |
312 | option (see \*(L"\s-1EXPANSION\s0\*(R" below) | |
313 | .IP "[2]" 4 | |
314 | .IX Item "[2]" | |
315 | The packer chooses the dimensions of the slave. | |
316 | The width will normally be the slave's requested width plus | |
317 | twice its \fB\-ipadx\fR option and the height will normally be | |
318 | the slave's requested height plus twice its \fB\-ipady\fR | |
319 | option. | |
320 | However, if the \fB\-fill\fR option is \fBx\fR or \fBboth\fR | |
321 | then the width of the slave is expanded to fill the width of the parcel, | |
322 | minus twice the \fB\-padx\fR option. | |
323 | If the \fB\-fill\fR option is \fBy\fR or \fBboth\fR | |
324 | then the height of the slave is expanded to fill the width of the parcel, | |
325 | minus twice the \fB\-pady\fR option. | |
326 | .IP "[3]" 4 | |
327 | .IX Item "[3]" | |
328 | The packer positions the slave over its parcel. | |
329 | If the slave is smaller than the parcel then the \fB\-anchor\fR | |
330 | option determines where in the parcel the slave will be placed. | |
331 | If \fB\-padx\fR or \fB\-pady\fR is non\-zero, then the given | |
332 | amount of external padding will always be left between the | |
333 | slave and the edges of the parcel. | |
334 | .Sp | |
335 | Once a given slave has been packed, the area of its parcel | |
336 | is subtracted from the cavity, leaving a smaller rectangular | |
337 | cavity for the next slave. | |
338 | If a slave doesn't use all of its parcel, the unused space | |
339 | in the parcel will not be used by subsequent slaves. | |
340 | If the cavity should become too small to meet the needs of | |
341 | a slave then the slave will be given whatever space is | |
342 | left in the cavity. | |
343 | If the cavity shrinks to zero size, then all remaining slaves | |
344 | on the packing list will be unmapped from the screen until | |
345 | the master window becomes large enough to hold them again. | |
346 | .SH "EXPANSION" | |
347 | .IX Header "EXPANSION" | |
348 | If a master window is so large that there will be extra space | |
349 | left over after all of its slaves have been packed, then the | |
350 | extra space is distributed uniformly among all of the slaves | |
351 | for which the \fB\-expand\fR option is set. | |
352 | Extra horizontal space is distributed among the expandable | |
353 | slaves whose \fB\-side\fR is \fBleft\fR or \fBright\fR, | |
354 | and extra vertical space is distributed among the expandable | |
355 | slaves whose \fB\-side\fR is \fBtop\fR or \fBbottom\fR. | |
356 | .SH "GEOMETRY PROPAGATION" | |
357 | .IX Header "GEOMETRY PROPAGATION" | |
358 | The packer normally computes how large a master must be to | |
359 | just exactly meet the needs of its slaves, and it sets the | |
360 | requested width and height of the master to these dimensions. | |
361 | This causes geometry information to propagate up through a | |
362 | window hierarchy to a top-level window so that the entire | |
363 | sub-tree sizes itself to fit the needs of the leaf windows. | |
364 | However, the \fBpackPropagate\fR method may be used to | |
365 | turn off propagation for one or more masters. | |
366 | If propagation is disabled then the packer will not set | |
367 | the requested width and height of the packer. | |
368 | This may be useful if, for example, you wish for a master | |
369 | window to have a fixed size that you specify. | |
370 | .SH "RESTRICTIONS ON MASTER WINDOWS" | |
371 | .IX Header "RESTRICTIONS ON MASTER WINDOWS" | |
372 | The master for each slave must either be the slave's parent | |
373 | (the default) or a descendant of the slave's parent. | |
374 | This restriction is necessary to guarantee that the | |
375 | slave can be placed over any part of its master that is | |
376 | visible without danger of the slave being clipped by its parent. | |
377 | .SH "PACKING ORDER" | |
378 | .IX Header "PACKING ORDER" | |
379 | If the master for a slave is not its parent then you must make sure | |
380 | that the slave is higher in the stacking order than the master. | |
381 | Otherwise the master will obscure the slave and it will appear as | |
382 | if the slave hasn't been packed correctly. | |
383 | The easiest way to make sure the slave is higher than the master is | |
384 | to create the master window first: the most recently created window | |
385 | will be highest in the stacking order. | |
386 | Or, you can use the \fBraise\fR and \fBlower\fR methods to change | |
387 | the stacking order of either the master or the slave. | |
388 | .SH "SEE ALSO" | |
389 | .IX Header "SEE ALSO" | |
390 | Tk::form | |
391 | Tk::grid | |
392 | Tk::place | |
393 | .SH "KEYWORDS" | |
394 | .IX Header "KEYWORDS" | |
395 | geometry manager, location, packer, parcel, propagation, size |