Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1996 Sun Microsystems, Inc. |
2 | # See the file "license.terms" for information on usage and redistribution | |
3 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
4 | # | |
5 | # | |
6 | ||
7 | =head1 NAME | |
8 | ||
9 | Tk::grid - Geometry manager that arranges widgets in a grid | |
10 | ||
11 | =for category Tk Geometry Management | |
12 | ||
13 | =head1 SYNOPSIS | |
14 | ||
15 | S< >I<$widget>-E<gt>B<grid>?(?I<widget> ...,? ?I<arg> ?...>?)? | |
16 | ||
17 | S< >I<$widget>-E<gt>B<grid>I<Option>?(I<arg> ?,I<arg> ...?)? | |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
21 | The B<grid> method is used to communicate with the grid | |
22 | geometry manager that arranges widgets in rows and columns inside | |
23 | of another window, called the geometry master (or master window). | |
24 | The B<grid> method can have any of several forms, depending | |
25 | on the I<option> argument: | |
26 | ||
27 | =over 4 | |
28 | ||
29 | =item I<$slave>-E<gt>B<grid>(?I<$slave, ...>??, I<options>?) | |
30 | ||
31 | The arguments consist of the optional references to more slave windows | |
32 | followed by pairs of arguments that specify how to manage the slaves. | |
33 | The characters B<->, B<x> and B<^>, | |
34 | can be specified instead of a window reference to alter the default | |
35 | location of a I<$slave>, as described in L<"RELATIVE PLACEMENT">, below. | |
36 | ||
37 | If any of the slaves are already managed by the geometry manager | |
38 | then any unspecified options for them retain their previous values rather | |
39 | than receiving default values. | |
40 | ||
41 | The following options are supported: | |
42 | ||
43 | =over 8 | |
44 | ||
45 | =item B<-column> => I<n> | |
46 | ||
47 | Insert the I<$slave> so that it occupies the I<n>th column in the grid. | |
48 | Column numbers start with 0. If this option is not supplied, then the | |
49 | I<$slave> is arranged just to the right of previous slave specified on this | |
50 | call to B<grid>, or column "0" if it is the first slave. For each | |
51 | B<x> that immediately precedes the I<$slave>, the column position | |
52 | is incremented by one. Thus the B<x> represents a blank column | |
53 | for this row in the grid. | |
54 | ||
55 | =item B<-columnspan> => I<n> | |
56 | ||
57 | Insert the slave so that it occupies I<n> columns in the grid. | |
58 | The default is one column, unless the window name is followed by a | |
59 | B<->, in which case the columnspan is incremented once for each immediately | |
60 | following B<->. | |
61 | ||
62 | =item B<-in> => I<$other> | |
63 | ||
64 | Insert the slave(s) in the master | |
65 | window given by I<$other>. The default is the first slave's | |
66 | parent window. | |
67 | ||
68 | =item B<-ipadx> => I<amount> | |
69 | ||
70 | The I<amount> specifies how much horizontal internal padding to | |
71 | leave on each side of the slave(s). This is space is added | |
72 | inside the slave(s) border. | |
73 | The I<amount> must be a valid screen distance, such as B<2> or B<'.5c'>. | |
74 | It defaults to 0. | |
75 | ||
76 | =item B<-ipady> => I<amount> | |
77 | ||
78 | The I<amount> specifies how much vertical internal padding to | |
79 | leave on on the top and bottom of the slave(s). | |
80 | This space is added inside the slave(s) border. | |
81 | The I<amount> defaults to 0. | |
82 | ||
83 | =item B<-padx> => I<amount> | |
84 | ||
85 | The I<amount> specifies how much horizontal external padding to | |
86 | leave on each side of the slave(s), in screen units. | |
87 | The I<amount> defaults to 0. | |
88 | This space is added outside the slave(s) border. | |
89 | ||
90 | =item B<-pady> => I<amount> | |
91 | ||
92 | The I<amount> specifies how much vertical external padding to | |
93 | leave on the top and bottom of the slave(s), in screen units. | |
94 | The I<amount> defaults to 0. | |
95 | This space is added outside the slave(s) border. | |
96 | ||
97 | =item B<-row> => I<n> | |
98 | ||
99 | Insert the slave so that it occupies the I<n>th row in the grid. | |
100 | Row numbers start with 0. If this option is not supplied, then the | |
101 | slave is arranged on the same row as the previous slave specified on this | |
102 | call to B<grid>, or the first unoccupied row if this is the first slave. | |
103 | ||
104 | =item B<-rowspan> => I<n> | |
105 | ||
106 | Insert the slave so that it occupies I<n> rows in the grid. | |
107 | The default is one row. If the next B<grid> method contains | |
108 | B<^> characters instead of I<$slave>s that line up with the columns | |
109 | of this I<$slave>, then the B<rowspan> of this I<$slave> is | |
110 | extended by one. | |
111 | ||
112 | =item B<-sticky> => I<style> | |
113 | ||
114 | If a slave's cell is larger than its requested dimensions, this | |
115 | option may be used to position (or stretch) the slave within its cell. | |
116 | I<Style> is a string that contains zero or more of the characters | |
117 | B<n>, B<s>, B<e> or B<w>. | |
118 | The string can optionally contain spaces or | |
119 | commas, but they are ignored. Each letter refers to a side (north, south, | |
120 | east, or west) that the slave will "stick" to. If both B<n> and B<s> (or | |
121 | B<e> and B<w>) are specified, the slave will be stretched to fill the entire | |
122 | height (or width) of its cavity. The B<sticky> option subsumes the | |
123 | combination of B<-anchor> and B<-fill> that is used by L<pack|Tk::pack>. | |
124 | The default is B<''>, which causes the slave to be centered in its cavity, | |
125 | at its requested size. | |
126 | ||
127 | =back | |
128 | ||
129 | =item I<$master>-E<gt>B<gridBbox>(?I<column, row>,? ?I<column2, row2>?) | |
130 | ||
131 | With no arguments, | |
132 | the bounding box (in pixels) of the grid is returned. | |
133 | The return value consists of 4 integers. The first two are the pixel | |
134 | offset from the master window (x then y) of the top-left corner of the | |
135 | grid, and the second two integers are the width and height of the grid, | |
136 | also in pixels. If a single I<column> and I<row> is specified on | |
137 | the command line, then the bounding box for that cell is returned, where the | |
138 | top left cell is numbered from zero. If both I<column> and I<row> | |
139 | arguments are specified, then the bounding box spanning the rows and columns | |
140 | indicated is returned. | |
141 | ||
142 | =item I<$master>-E<gt>B<gridColumnconfigure>(I<index>?, I<-option>=>I<value, ...>?) | |
143 | ||
144 | Query or set the column properties of the I<index> column of the | |
145 | geometry master, I<$master>. | |
146 | The valid options are B<-minsize>, B<-weight> and B<-pad>. | |
147 | If one or more options are provided, then I<index> may be given as | |
148 | a list of column indices to which the configuration options will operate on. | |
149 | The B<-minsize> option sets the minimum size, in screen units, | |
150 | that will be permitted for this column. | |
151 | The B<-weight> option (an integer value) | |
152 | sets the relative weight for apportioning | |
153 | any extra spaces among | |
154 | columns. | |
155 | A weight of zero (0) indicates the column will not deviate from its requested | |
156 | size. A column whose weight is two will grow at twice the rate as a column | |
157 | of weight one when extra space is allocated to the layout. | |
158 | The B<-pad> option specifies the number of screen units that will be | |
159 | added to the largest window contained completely in that column when the | |
160 | grid geometry manager requests a size from the containing window. | |
161 | If only an option is specified, with no value, | |
162 | the current value of that option is returned. | |
163 | If only the master window and index is specified, all the current settings | |
164 | are returned in an list of "-option value" pairs. | |
165 | ||
166 | =item I<$slave>-E<gt>B<gridConfigure>(?I<$slave, ...>?, I<options>?) | |
167 | ||
168 | The same as B<grid> method. | |
169 | ||
170 | =item I<$slave>-E<gt>B<gridForget>?(I<$slave, ...>)? | |
171 | ||
172 | Removes each of the I<$slave>s from grid for its | |
173 | master and unmaps their windows. | |
174 | The slaves will no longer be managed by the grid geometry manager. | |
175 | The configuration options for that window are forgotten, so that if the | |
176 | slave is managed once more by the grid geometry manager, the initial | |
177 | default settings are used. | |
178 | ||
179 | =item I<$slave>-E<gt>B<gridInfo> | |
180 | ||
181 | Returns a list whose elements are the current configuration state of | |
182 | the slave given by I<$slave> in the same option-value form that | |
183 | might be specified to B<gridConfigure>. | |
184 | The first two elements of the list are ``B<-in>=>I<$master>'' where | |
185 | I<$master> is the slave's master. | |
186 | ||
187 | =item I<$master>-E<gt>B<gridLocation>(I<x, y>) | |
188 | ||
189 | Given I<x> and I<y> values in screen units relative to the master window, | |
190 | the column and row number at that I<x> and I<y> location is returned. | |
191 | For locations that are above or to the left of the grid, B<-1> is returned. | |
192 | ||
193 | =item I<$master>-E<gt>B<gridPropagate>?(I<boolean>)? | |
194 | ||
195 | If I<boolean> has a true boolean value such as B<1> or B<on> | |
196 | then propagation is enabled for I<$master>, which must be a window | |
197 | name (see L<"GEOMETRY PROPAGATION"> below). | |
198 | If I<boolean> has a false boolean value then propagation is | |
199 | disabled for I<$master>. | |
200 | In either of these cases an empty string is returned. | |
201 | If I<boolean> is omitted then the method returns B<0> or | |
202 | B<1> to indicate whether propagation is currently enabled | |
203 | for I<$master>. | |
204 | Propagation is enabled by default. | |
205 | ||
206 | =item I<$master>-E<gt>B<gridRowconfigure>(I<index>?, I<-option>=>I<value, ...>?) | |
207 | ||
208 | Query or set the row properties of the I<index> row of the | |
209 | geometry master, I<$master>. | |
210 | The valid options are B<-minsize>, B<-weight> and B<-pad>. | |
211 | If one or more options are provided, then I<index> may be given as | |
212 | a list of row indeces to which the configuration options will operate on. | |
213 | The B<-minsize> option sets the minimum size, in screen units, | |
214 | that will be permitted for this row. | |
215 | The B<-weight> option (an integer value) | |
216 | sets the relative weight for apportioning | |
217 | any extra spaces among | |
218 | rows. | |
219 | A weight of zero (0) indicates the row will not deviate from its requested | |
220 | size. A row whose weight is two will grow at twice the rate as a row | |
221 | of weight one when extra space is allocated to the layout. | |
222 | The B<-pad> option specifies the number of screen units that will be | |
223 | added to the largest window contained completely in that row when the | |
224 | grid geometry manager requests a size from the containing window. | |
225 | If only an option is specified, with no value, | |
226 | the current value of that option is returned. | |
227 | If only the master window and index is specified, all the current settings | |
228 | are returned in an list of "option-value" pairs. | |
229 | ||
230 | =item I<$slave>-E<gt>B<gridRemove>?(I<$slave, ...>)? | |
231 | ||
232 | Removes each of the I<$slave>s from grid for its | |
233 | master and unmaps their windows. | |
234 | The slaves will no longer be managed by the grid geometry manager. | |
235 | However, the configuration options for that window are remembered, | |
236 | so that if the | |
237 | slave is managed once more by the grid geometry manager, the previous | |
238 | values are retained. | |
239 | ||
240 | =item I<$master>-E<gt>B<gridSize> | |
241 | ||
242 | Returns the size of the grid (in columns then rows) for I<$master>. | |
243 | The size is determined either by the I<$slave> occupying the largest | |
244 | row or column, or the largest column or row with a B<-minsize>, | |
245 | B<-weight>, or B<-pad> that is non-zero. | |
246 | ||
247 | =item I<$master>-E<gt>B<gridSlaves>?(I<-option>=>I<value>)? | |
248 | ||
249 | If no options are supplied, a list of all of the slaves in I<$master> | |
250 | are returned, most recently manages first. | |
251 | I<-option> can be either B<-row> or B<-column> which | |
252 | causes only the slaves in the row (or column) specified by I<value> | |
253 | to be returned. | |
254 | ||
255 | =back | |
256 | ||
257 | =head1 RELATIVE PLACEMENT | |
258 | ||
259 | The B<grid> method contains a limited set of capabilities that | |
260 | permit layouts to be created without specifying the row and column | |
261 | information for each slave. This permits slaves to be rearranged, | |
262 | added, or removed without the need to explicitly specify row and | |
263 | column information. | |
264 | When no column or row information is specified for a I<$slave>, | |
265 | default values are chosen for | |
266 | B<-column>, B<-row>, B<-columnspan> and B<-rowspan> | |
267 | at the time the I<$slave> is managed. The values are chosen | |
268 | based upon the current layout of the grid, the position of the I<$slave> | |
269 | relative to other I<$slave>s in the same grid method, and the presence | |
270 | of the characters B<->, B<^>, and B<^> in B<grid> | |
271 | method where I<$slave> names are normally expected. | |
272 | ||
273 | =over 4 | |
274 | ||
275 | =item B<-> | |
276 | ||
277 | This increases the columnspan of the I<$slave> to the left. Several | |
278 | B<->'s in a row will successively increase the columnspan. A B<-> | |
279 | may not follow a B<^> or a B<x>. | |
280 | ||
281 | =item B<x> | |
282 | ||
283 | This leaves an empty column between the I<$slave> on the left and | |
284 | the I<$slave> on the right. | |
285 | ||
286 | =item B<^> | |
287 | ||
288 | This extends the B<-rowspan> of the I<$slave> above the B<^>'s | |
289 | in the grid. The number of B<^>'s in a row must match the number of | |
290 | columns spanned by the I<$slave> above it. | |
291 | ||
292 | =back | |
293 | ||
294 | =head1 THE GRID ALGORITHM | |
295 | ||
296 | The grid geometry manager lays out its slaves in three steps. | |
297 | In the first step, the minimum size needed to fit all of the slaves | |
298 | is computed, then (if propagation is turned on), a request is made | |
299 | of the master window to become that size. | |
300 | In the second step, the requested size is compared against the actual size | |
301 | of the master. If the sizes are different, then space is added to or taken | |
302 | away from the layout as needed. | |
303 | For the final step, each slave is positioned in its row(s) and column(s) | |
304 | based on the setting of its I<sticky> flag. | |
305 | ||
306 | To compute the minimum size of a layout, the grid geometry manager | |
307 | first looks at all slaves whose columnspan and rowspan values are one, | |
308 | and computes the nominal size of each row or column to be either the | |
309 | I<minsize> for that row or column, or the sum of the I<pad>ding | |
310 | plus the size of the largest slave, whichever is greater. Then the | |
311 | slaves whose rowspans or columnspans are greater than one are | |
312 | examined. If a group of rows or columns need to be increased in size | |
313 | in order to accommodate these slaves, then extra space is added to each | |
314 | row or column in the group according to its I<weight>. For each | |
315 | group whose weights are all zero, the additional space is apportioned | |
316 | equally. | |
317 | ||
318 | For masters whose size is larger than the requested layout, the additional | |
319 | space is apportioned according to the row and column weights. If all of | |
320 | the weights are zero, the layout is centered within its master. | |
321 | For masters whose size is smaller than the requested layout, space is taken | |
322 | away from columns and rows according to their weights. However, once a | |
323 | column or row shrinks to its minsize, its weight is taken to be zero. | |
324 | If more space needs to be removed from a layout than would be permitted, as | |
325 | when all the rows or columns are at there minimum sizes, the layout is | |
326 | clipped on the bottom and right. | |
327 | ||
328 | =head1 GEOMETRY PROPAGATION | |
329 | ||
330 | The grid geometry manager normally computes how large a master must be to | |
331 | just exactly meet the needs of its slaves, and it sets the | |
332 | requested width and height of the master to these dimensions. | |
333 | This causes geometry information to propagate up through a | |
334 | window hierarchy to a top-level window so that the entire | |
335 | sub-tree sizes itself to fit the needs of the leaf windows. | |
336 | However, the B<gridPropagate> method may be used to | |
337 | turn off propagation for one or more masters. | |
338 | If propagation is disabled then grid will not set | |
339 | the requested width and height of the master window. | |
340 | This may be useful if, for example, you wish for a master | |
341 | window to have a fixed size that you specify. | |
342 | ||
343 | =head1 RESTRICTIONS ON MASTER WINDOWS | |
344 | ||
345 | The master for each slave must either be the slave's parent | |
346 | (the default) or a descendant of the slave's parent. | |
347 | This restriction is necessary to guarantee that the | |
348 | slave can be placed over any part of its master that is | |
349 | visible without danger of the slave being clipped by its parent. | |
350 | In addition, all slaves in one call to B<grid> must have the same master. | |
351 | ||
352 | =head1 STACKING ORDER | |
353 | ||
354 | If the master for a slave is not its parent then you must make sure | |
355 | that the slave is higher in the stacking order than the master. | |
356 | Otherwise the master will obscure the slave and it will appear as | |
357 | if the slave hasn't been managed correctly. | |
358 | The easiest way to make sure the slave is higher than the master is | |
359 | to create the master window first: the most recently created window | |
360 | will be highest in the stacking order. | |
361 | ||
362 | =head1 CREDITS | |
363 | ||
364 | The B<grid> method is based on ideas taken from the I<GridBag> | |
365 | geometry manager written by Doug. Stein, and the B<blt_table> geometry | |
366 | manager, written by George Howlett. | |
367 | ||
368 | =head1 SEE ALSO | |
369 | ||
370 | L<Tk::form|Tk::form> | |
371 | L<Tk::pack|Tk::pack> | |
372 | L<Tk::place|Tk::place> | |
373 | ||
374 | =head1 KEYWORDS | |
375 | ||
376 | geometry manager, location, grid, cell, propagation, size, pack, | |
377 | master, slave | |
378 | ||
379 | =cut | |
380 |