2 '\" Copyright (c) 1996 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
10 .TH grid n 4.1 Tk "Tk Built-In Commands"
12 '\" Note: do not modify the .SH NAME line immediately below!
14 grid \- Geometry manager that arranges widgets in a grid
16 \fBgrid \fIoption arg \fR?\fIarg ...\fR?
21 The \fBgrid\fR command 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 \fBgrid\fR command can have any of several forms, depending
25 on the \fIoption\fR argument:
27 \fBgrid \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR?
28 If the first argument to \fBgrid\fR is a window name (any value
29 starting with ``.''), then the command is processed in the same
30 way as \fBgrid configure\fR.
32 \fBgrid bbox \fImaster\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR?
34 the bounding box (in pixels) of the grid is returned.
35 The return value consists of 4 integers. The first two are the pixel
36 offset from the master window (x then y) of the top-left corner of the
37 grid, and the second two integers are the width and height of the grid,
38 also in pixels. If a single \fIcolumn\fP and \fIrow\fP is specified on
39 the command line, then the bounding box for that cell is returned, where the
40 top left cell is numbered from zero. If both \fIcolumn\fP and \fIrow\fP
41 arguments are specified, then the bounding box spanning the rows and columns
42 indicated is returned.
44 \fBgrid columnconfigure \fImaster index \fR?\fI\-option value...\fR?
45 Query or set the column properties of the \fIindex\fP column of the
46 geometry master, \fImaster\fP.
47 The valid options are \fB\-minsize\fP, \fB\-weight\fP and \fB-pad\fP.
49 If one or more options are provided, then \fIindex\fP may be given as
50 a list of column indeces to which the configuration options will operate on.
52 The \fB\-minsize\fP option sets the minimum size, in screen units,
53 that will be permitted for this column.
54 The \fB\-weight\fP option (an integer value)
55 sets the relative weight for apportioning
56 any extra spaces among
58 A weight of zero (0) indicates the column will not deviate from its requested
59 size. A column whose weight is two will grow at twice the rate as a column
60 of weight one when extra space is allocated to the layout.
61 The \fB-pad\fP option specifies the number of screen units that will be
62 added to the largest window contained completely in that column when the
63 grid geometry manager requests a size from the containing window.
64 If only an option is specified, with no value,
65 the current value of that option is returned.
66 If only the master window and index is specified, all the current settings
67 are returned in an list of "-option value" pairs.
69 \fBgrid configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR?
70 The arguments consist of the names of one or more slave windows
71 followed by pairs of arguments that specify how
73 The characters \fB\-\fP, \fBx\fP and \fB^\fP,
74 can be specified instead of a window name to alter the default
75 location of a \fIslave\fP, as described in the ``RELATIVE PLACEMENT''
77 The following options are supported:
81 Insert the slave so that it occupies the \fIn\fPth column in the grid.
82 Column numbers start with 0. If this option is not supplied, then the
83 slave is arranged just to the right of previous slave specified on this
84 call to \fIgrid\fP, or column "0" if it is the first slave. For each
85 \fBx\fP that immediately precedes the \fIslave\fP, the column position
86 is incremented by one. Thus the \fBx\fP represents a blank column
87 for this row in the grid.
89 \fB\-columnspan \fIn\fR
90 Insert the slave so that it occupies \fIn\fP columns in the grid.
91 The default is one column, unless the window name is followed by a
92 \fB\-\fP, in which case the columnspan is incremented once for each immediately
96 Insert the slave(s) in the master
97 window given by \fIother\fR. The default is the first slave's
100 \fB\-ipadx \fIamount\fR
101 The \fIamount\fR specifies how much horizontal internal padding to
102 leave on each side of the slave(s). This is space is added
103 inside the slave(s) border.
104 The \fIamount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR.
107 \fB\-ipady \fIamount\fR
108 The \fIamount\fR specifies how much vertical internal padding to
109 leave on on the top and bottom of the slave(s).
110 This space is added inside the slave(s) border.
111 The \fIamount\fR defaults to 0.
113 \fB\-padx \fIamount\fR
114 The \fIamount\fR specifies how much horizontal external padding to
115 leave on each side of the slave(s), in screen units.
116 The \fIamount\fR defaults to 0.
117 This space is added outside the slave(s) border.
119 \fB\-pady \fIamount\fR
120 The \fIamount\fR specifies how much vertical external padding to
121 leave on the top and bottom of the slave(s), in screen units.
122 The \fIamount\fR defaults to 0.
123 This space is added outside the slave(s) border.
126 Insert the slave so that it occupies the \fIn\fPth row in the grid.
127 Row numbers start with 0. If this option is not supplied, then the
128 slave is arranged on the same row as the previous slave specified on this
129 call to \fBgrid\fP, or the first unoccupied row if this is the first slave.
132 Insert the slave so that it occupies \fIn\fP rows in the grid.
133 The default is one row. If the next \fBgrid\fP command contains
134 \fB^\fP characters instead of \fIslaves\fP that line up with the columns
135 of this \fIslave\fP, then the \fBrowspan\fP of this \fIslave\fP is
138 \fB\-sticky \fIstyle\fR
139 If a slave's cell is larger than its requested dimensions, this
140 option may be used to position (or stretch) the slave within its cell.
141 \fIStyle\fR is a string that contains zero or more of the characters
142 \fBn\fP, \fBs\fP, \fBe\fP or \fBw\fP.
143 The string can optionally contains spaces or
144 commas, but they are ignored. Each letter refers to a side (north, south,
145 east, or west) that the slave will "stick" to. If both \fBn\fP and \fBs\fP (or
146 \fBe\fP and \fBw\fP) are specified, the slave will be stretched to fill the entire
147 height (or width) of its cavity. The \fBsticky\fP option subsumes the
148 combination of \fB\-anchor\fP and \fB\-fill\fP that is used by \fBpack\fP.
149 The default is \fB{}\fP, which causes the slave to be centered in its cavity,
150 at its requested size.
152 If any of the slaves are already managed by the geometry manager
153 then any unspecified options for them retain their previous values rather
154 than receiving default values.
157 \fBgrid forget \fIslave \fR?\fIslave ...\fR?
158 Removes each of the \fIslave\fRs from grid for its
159 master and unmaps their windows.
160 The slaves will no longer be managed by the grid geometry manager.
161 The configuration options for that window are forgotten, so that if the
162 slave is managed once more by the grid geometry manager, the initial
163 default settings are used.
165 \fBgrid info \fIslave\fR
166 Returns a list whose elements are the current configuration state of
167 the slave given by \fIslave\fR in the same option-value form that
168 might be specified to \fBgrid configure\fR.
169 The first two elements of the list are ``\fB\-in \fImaster\fR'' where
170 \fImaster\fR is the slave's master.
172 \fBgrid location \fImaster x y\fR
173 Given \fIx\fP and \fIy\fP values in screen units relative to the master window,
174 the column and row number at that \fIx\fP and \fIy\fP location is returned.
175 For locations that are above or to the left of the grid, \fB-1\fP is returned.
177 \fBgrid propagate \fImaster\fR ?\fIboolean\fR?
178 If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR
179 then propagation is enabled for \fImaster\fR, which must be a window
180 name (see ``GEOMETRY PROPAGATION'' below).
181 If \fIboolean\fR has a false boolean value then propagation is
182 disabled for \fImaster\fR.
183 In either of these cases an empty string is returned.
184 If \fIboolean\fR is omitted then the command returns \fB0\fR or
185 \fB1\fR to indicate whether propagation is currently enabled
187 Propagation is enabled by default.
189 \fBgrid rowconfigure \fImaster index \fR?\fI\-option value...\fR?
190 Query or set the row properties of the \fIindex\fP row of the
191 geometry master, \fImaster\fP.
192 The valid options are \fB\-minsize\fP, \fB\-weight\fP and \fB-pad\fP.
194 If one or more options are provided, then \fIindex\fP may be given as
195 a list of row indeces to which the configuration options will operate on.
197 The \fB\-minsize\fP option sets the minimum size, in screen units,
198 that will be permitted for this row.
199 The \fB\-weight\fP option (an integer value)
200 sets the relative weight for apportioning
201 any extra spaces among
203 A weight of zero (0) indicates the row will not deviate from its requested
204 size. A row whose weight is two will grow at twice the rate as a row
205 of weight one when extra space is allocated to the layout.
206 The \fB-pad\fP option specifies the number of screen units that will be
207 added to the largest window contained completely in that row when the
208 grid geometry manager requests a size from the containing window.
209 If only an option is specified, with no value,
210 the current value of that option is returned.
211 If only the master window and index is specified, all the current settings
212 are returned in an list of "-option value" pairs.
214 \fBgrid remove \fIslave \fR?\fIslave ...\fR?
215 Removes each of the \fIslave\fRs from grid for its
216 master and unmaps their windows.
217 The slaves will no longer be managed by the grid geometry manager.
218 However, the configuration options for that window are remembered,
220 slave is managed once more by the grid geometry manager, the previous
223 \fBgrid size \fImaster\fR
224 Returns the size of the grid (in columns then rows) for \fImaster\fP.
225 The size is determined either by the \fIslave\fP occupying the largest
226 row or column, or the largest column or row with a \fBminsize\fP,
227 \fBweight\fP, or \fBpad\fP that is non-zero.
229 \fBgrid slaves \fImaster\fR ?\fI\-option value\fR?
230 If no options are supplied, a list of all of the slaves in \fImaster\fR
231 are returned, most recently manages first.
232 \fIOption\fP can be either \fB\-row\fP or \fB\-column\fP which
233 causes only the slaves in the row (or column) specified by \fIvalue\fP
235 .SH "RELATIVE PLACEMENT"
237 The \fBgrid\fP command contains a limited set of capabilities that
238 permit layouts to be created without specifying the row and column
239 information for each slave. This permits slaves to be rearranged,
240 added, or removed without the need to explicitly specify row and
242 When no column or row information is specified for a \fIslave\fP,
243 default values are chosen for
244 \fBcolumn\fP, \fBrow\fP, \fBcolumnspan\fP and \fBrowspan\fP
245 at the time the \fIslave\fP is managed. The values are chosen
246 based upon the current layout of the grid, the position of the \fIslave\fP
247 relative to other \fIslave\fPs in the same grid command, and the presence
248 of the characters \fB\-\fP, \fB^\fP, and \fB^\fP in \fBgrid\fP
249 command where \fIslave\fP names are normally expected.
253 This increases the columnspan of the \fIslave\fP to the left. Several
254 \fB\-\fP's in a row will successively increase the columnspan. A \fB\-\fP
255 may not follow a \fB^\fP or a \fBx\fP.
258 This leaves an empty column between the \fIslave\fP on the left and
259 the \fIslave\fP on the right.
262 This extends the \fBrowspan\fP of the \fIslave\fP above the \fB^\fP's
263 in the grid. The number of \fB^\fP's in a row must match the number of
264 columns spanned by the \fIslave\fP above it.
266 .SH "THE GRID ALGORITHM"
268 The grid geometry manager lays out its slaves in three steps.
269 In the first step, the minimum size needed to fit all of the slaves
270 is computed, then (if propagation is turned on), a request is made
271 of the master window to become that size.
272 In the second step, the requested size is compared against the actual size
273 of the master. If the sizes are different, then spaces is added to or taken
274 away from the layout as needed.
275 For the final step, each slave is positioned in its row(s) and column(s)
276 based on the setting of its \fIsticky\fP flag.
278 To compute the minimum size of a layout, the grid geometry manager
279 first looks at all slaves whose columnspan and rowspan values are one,
280 and computes the nominal size of each row or column to be either the
281 \fIminsize\fP for that row or column, or the sum of the \fIpad\fPding
282 plus the size of the largest slave, whichever is greater. Then the
283 slaves whose rowspans or columnspans are greater than one are
284 examined. If a group of rows or columns need to be increased in size
285 in order to accommodate these slaves, then extra space is added to each
286 row or column in the group according to its \fIweight\fP. For each
287 group whose weights are all zero, the additional space is apportioned
290 For masters whose size is larger than the requested layout, the additional
291 space is apportioned according to the row and column weights. If all of
292 the weights are zero, the layout is centered within its master.
293 For masters whose size is smaller than the requested layout, space is taken
294 away from columns and rows according to their weights. However, once a
295 column or row shrinks to its minsize, its weight is taken to be zero.
296 If more space needs to be removed from a layout than would be permitted, as
297 when all the rows or columns are at there minimum sizes, the layout is
298 clipped on the bottom and right.
299 .SH "GEOMETRY PROPAGATION"
301 The grid geometry manager normally computes how large a master must be to
302 just exactly meet the needs of its slaves, and it sets the
303 requested width and height of the master to these dimensions.
304 This causes geometry information to propagate up through a
305 window hierarchy to a top-level window so that the entire
306 sub-tree sizes itself to fit the needs of the leaf windows.
307 However, the \fBgrid propagate\fR command may be used to
308 turn off propagation for one or more masters.
309 If propagation is disabled then grid will not set
310 the requested width and height of the master window.
311 This may be useful if, for example, you wish for a master
312 window to have a fixed size that you specify.
314 .SH "RESTRICTIONS ON MASTER WINDOWS"
316 The master for each slave must either be the slave's parent
317 (the default) or a descendant of the slave's parent.
318 This restriction is necessary to guarantee that the
319 slave can be placed over any part of its master that is
320 visible without danger of the slave being clipped by its parent.
321 In addition, all slaves in one call to \fBgrid\fP must have the same master.
324 If the master for a slave is not its parent then you must make sure
325 that the slave is higher in the stacking order than the master.
326 Otherwise the master will obscure the slave and it will appear as
327 if the slave hasn't been managed correctly.
328 The easiest way to make sure the slave is higher than the master is
329 to create the master window first: the most recently created window
330 will be highest in the stacking order.
333 The \fBgrid\fP command is based on ideas taken from the \fIGridBag\fP
334 geometry manager written by Doug. Stein, and the \fBblt_table\fR geometry
335 manager, written by George Howlett.
337 geometry manager, location, grid, cell, propagation, size, pack
OSDN Git Service
