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.
7 .TH grid n 8.5 Tk "Tk Built-In Commands"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
11 .\" .AP type name in/out ?indent?
12 .\" Start paragraph describing an argument to a library procedure.
13 .\" type is type of argument (int, etc.), in/out is either "in", "out",
14 .\" or "in/out" to describe whether procedure reads or modifies arg,
15 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 .\" needed; use .AS below instead)
19 .\" Give maximum sizes of arguments for setting tab stops. Type and
20 .\" name are examples of largest possible arguments that will be passed
21 .\" to .AP later. If args are omitted, default tab stops are used.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
36 .\" .VS ?version? ?br?
37 .\" Begin vertical sidebar, for use in marking newly-changed parts
38 .\" of man pages. The first argument is ignored and used for recording
39 .\" the version when the .VS was added, so that the sidebars can be
40 .\" found and removed when they reach a certain age. If another argument
41 .\" is present, then a line break is forced before starting the sidebar.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
59 .\" End of list of standard options for a Tk widget.
61 .\" .OP cmdName dbName dbClass
62 .\" Start of description of a specific option. cmdName gives the
63 .\" option's name as specified in the class command, dbName gives
64 .\" the option's name in the option database, and dbClass gives
65 .\" the option's class in the option database.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
276 '\" Note: do not modify the .SH NAME line immediately below!
278 grid \- Geometry manager that arranges widgets in a grid
280 \fBgrid \fIoption arg \fR?\fIarg ...\fR?
284 The \fBgrid\fR command is used to communicate with the grid
285 geometry manager that arranges widgets in rows and columns inside
286 of another window, called the geometry master (or master window).
287 The \fBgrid\fR command can have any of several forms, depending
288 on the \fIoption\fR argument:
290 \fBgrid \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR?
292 If the first argument to \fBgrid\fR is suitable as the first slave
293 argument to \fBgrid configure\fR, either a window name (any value
294 starting with \fB.\fR) or one of the characters \fBx\fR or \fB^\fR
295 (see the \fBRELATIVE PLACEMENT\fR section below), then the command is
296 processed in the same way as \fBgrid configure\fR.
298 \fBgrid anchor \fImaster\fR ?\fIanchor\fR?
300 The anchor value controls how to place the grid within the master
301 when no row/column has any weight. See \fBTHE GRID ALGORITHM\fR below
302 for further details. The default \fIanchor\fR is \fInw\fR.
304 \fBgrid bbox \fImaster\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR?
307 the bounding box (in pixels) of the grid is returned.
308 The return value consists of 4 integers. The first two are the pixel
309 offset from the master window (x then y) of the top-left corner of the
310 grid, and the second two integers are the width and height of the grid,
311 also in pixels. If a single \fIcolumn\fR and \fIrow\fR is specified on
312 the command line, then the bounding box for that cell is returned, where the
313 top left cell is numbered from zero. If both \fIcolumn\fR and \fIrow\fR
314 arguments are specified, then the bounding box spanning the rows and columns
315 indicated is returned.
317 \fBgrid columnconfigure \fImaster index \fR?\fI\-option value...\fR?
319 Query or set the column properties of the \fIindex\fR column of the
320 geometry master, \fImaster\fR.
321 The valid options are \fB\-minsize\fR, \fB\-weight\fR, \fB\-uniform\fR
323 If one or more options are provided, then \fIindex\fR may be given as
324 a list of column indices to which the configuration options will operate on.
325 Indices may be integers, window names or the keyword \fIall\fR. For \fIall\fR
326 the options apply to all columns currently occupied be slave windows. For
327 a window name, that window must be a slave of this master and the options
328 apply to all columns currently occupied be the slave.
329 The \fB\-minsize\fR option sets the minimum size, in screen units,
330 that will be permitted for this column.
331 The \fB\-weight\fR option (an integer value)
332 sets the relative weight for apportioning
333 any extra spaces among
335 A weight of zero (0) indicates the column will not deviate from its requested
336 size. A column whose weight is two will grow at twice the rate as a column
337 of weight one when extra space is allocated to the layout.
338 The \fB\-uniform\fR option, when a non-empty value is supplied, places
339 the column in a \fIuniform group\fR with other columns that have the
340 same value for \fB\-uniform\fR. The space for columns belonging to a
341 uniform group is allocated so that their sizes are always in strict
342 proportion to their \fB\-weight\fR values. See
343 \fBTHE GRID ALGORITHM\fR below for further details.
344 The \fB\-pad\fR option specifies the number of screen units that will be
345 added to the largest window contained completely in that column when the
346 grid geometry manager requests a size from the containing window.
347 If only an option is specified, with no value,
348 the current value of that option is returned.
349 If only the master window and index is specified, all the current settings
350 are returned in a list of
354 \fBgrid configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR?
356 The arguments consist of the names of one or more slave windows
357 followed by pairs of arguments that specify how
358 to manage the slaves.
359 The characters \fB\-\fR, \fBx\fR and \fB^\fR,
360 can be specified instead of a window name to alter the default
361 location of a \fIslave\fR, as described in the \fBRELATIVE PLACEMENT\fR
363 The following options are supported:
368 Insert the slave so that it occupies the \fIn\fRth column in the grid.
369 Column numbers start with 0. If this option is not supplied, then the
370 slave is arranged just to the right of previous slave specified on this
371 call to \fBgrid\fR, or column
373 if it is the first slave. For each
374 \fBx\fR that immediately precedes the \fIslave\fR, the column position
375 is incremented by one. Thus the \fBx\fR represents a blank column
376 for this row in the grid.
378 \fB\-columnspan \fIn\fR
380 Insert the slave so that it occupies \fIn\fR columns in the grid.
381 The default is one column, unless the window name is followed by a
382 \fB\-\fR, in which case the columnspan is incremented once for each immediately
387 Insert the slave(s) in the master
388 window given by \fIother\fR. The default is the first slave's
391 \fB\-ipadx \fIamount\fR
393 The \fIamount\fR specifies how much horizontal internal padding to
394 leave on each side of the slave(s). This is space is added
395 inside the slave(s) border.
396 The \fIamount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR.
399 \fB\-ipady \fIamount\fR
401 The \fIamount\fR specifies how much vertical internal padding to
402 leave on the top and bottom of the slave(s).
403 This space is added inside the slave(s) border.
404 The \fIamount\fR defaults to 0.
406 \fB\-padx \fIamount\fR
408 The \fIamount\fR specifies how much horizontal external padding to
409 leave on each side of the slave(s), in screen units.
410 \fIAmount\fR may be a list
411 of two values to specify padding for left and right separately.
412 The \fIamount\fR defaults to 0.
413 This space is added outside the slave(s) border.
415 \fB\-pady \fIamount\fR
417 The \fIamount\fR specifies how much vertical external padding to
418 leave on the top and bottom of the slave(s), in screen units.
419 \fIAmount\fR may be a list
420 of two values to specify padding for top and bottom separately.
421 The \fIamount\fR defaults to 0.
422 This space is added outside the slave(s) border.
426 Insert the slave so that it occupies the \fIn\fRth row in the grid.
427 Row numbers start with 0. If this option is not supplied, then the
428 slave is arranged on the same row as the previous slave specified on this
429 call to \fBgrid\fR, or the first unoccupied row if this is the first slave.
433 Insert the slave so that it occupies \fIn\fR rows in the grid.
434 The default is one row. If the next \fBgrid\fR command contains
435 \fB^\fR characters instead of \fIslaves\fR that line up with the columns
436 of this \fIslave\fR, then the \fBrowspan\fR of this \fIslave\fR is
439 \fB\-sticky \fIstyle\fR
441 If a slave's cell is larger than its requested dimensions, this
442 option may be used to position (or stretch) the slave within its cell.
443 \fIStyle\fR is a string that contains zero or more of the characters
444 \fBn\fR, \fBs\fR, \fBe\fR or \fBw\fR.
445 The string can optionally contains spaces or
446 commas, but they are ignored. Each letter refers to a side (north, south,
447 east, or west) that the slave will
449 to. If both \fBn\fR and \fBs\fR (or \fBe\fR and \fBw\fR) are
450 specified, the slave will be stretched to fill the entire
451 height (or width) of its cavity. The \fB\-sticky\fR option subsumes the
452 combination of \fB\-anchor\fR and \fB\-fill\fR that is used by \fBpack\fR.
455 which causes the slave to be centered in its cavity, at its requested size.
457 If any of the slaves are already managed by the geometry manager
458 then any unspecified options for them retain their previous values rather
459 than receiving default values.
462 \fBgrid forget \fIslave \fR?\fIslave ...\fR?
464 Removes each of the \fIslave\fRs from grid for its
465 master and unmaps their windows.
466 The slaves will no longer be managed by the grid geometry manager.
467 The configuration options for that window are forgotten, so that if the
468 slave is managed once more by the grid geometry manager, the initial
469 default settings are used.
471 \fBgrid info \fIslave\fR
473 Returns a list whose elements are the current configuration state of
474 the slave given by \fIslave\fR in the same option-value form that
475 might be specified to \fBgrid configure\fR.
476 The first two elements of the list are
477 .QW "\fB\-in \fImaster\fR"
478 where \fImaster\fR is the slave's master.
480 \fBgrid location \fImaster x y\fR
482 Given \fIx\fR and \fIy\fR values in screen units relative to the master window,
483 the column and row number at that \fIx\fR and \fIy\fR location is returned.
484 For locations that are above or to the left of the grid, \fB\-1\fR is
487 \fBgrid propagate \fImaster\fR ?\fIboolean\fR?
489 If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR
490 then propagation is enabled for \fImaster\fR, which must be a window
491 name (see \fBGEOMETRY PROPAGATION\fR below).
492 If \fIboolean\fR has a false boolean value then propagation is
493 disabled for \fImaster\fR.
494 In either of these cases an empty string is returned.
495 If \fIboolean\fR is omitted then the command returns \fB0\fR or
496 \fB1\fR to indicate whether propagation is currently enabled
498 Propagation is enabled by default.
500 \fBgrid rowconfigure \fImaster index \fR?\fI\-option value...\fR?
502 Query or set the row properties of the \fIindex\fR row of the
503 geometry master, \fImaster\fR.
504 The valid options are \fB\-minsize\fR, \fB\-weight\fR, \fB\-uniform\fR
506 If one or more options are provided, then \fIindex\fR may be given as
507 a list of row indices to which the configuration options will operate on.
508 Indices may be integers, window names or the keyword \fIall\fR. For \fIall\fR
509 the options apply to all rows currently occupied be slave windows. For
510 a window name, that window must be a slave of this master and the options
511 apply to all rows currently occupied be the slave.
512 The \fB\-minsize\fR option sets the minimum size, in screen units,
513 that will be permitted for this row.
514 The \fB\-weight\fR option (an integer value)
515 sets the relative weight for apportioning
516 any extra spaces among
518 A weight of zero (0) indicates the row will not deviate from its requested
519 size. A row whose weight is two will grow at twice the rate as a row
520 of weight one when extra space is allocated to the layout.
521 The \fB\-uniform\fR option, when a non-empty value is supplied, places
522 the row in a \fIuniform group\fR with other rows that have the
523 same value for \fB\-uniform\fR. The space for rows belonging to a
524 uniform group is allocated so that their sizes are always in strict
525 proportion to their \fB\-weight\fR values. See
526 \fBTHE GRID ALGORITHM\fR below for further details.
527 The \fB\-pad\fR option specifies the number of screen units that will be
528 added to the largest window contained completely in that row when the
529 grid geometry manager requests a size from the containing window.
530 If only an option is specified, with no value,
531 the current value of that option is returned.
532 If only the master window and index is specified, all the current settings
533 are returned in a list of
537 \fBgrid remove \fIslave \fR?\fIslave ...\fR?
539 Removes each of the \fIslave\fRs from grid for its
540 master and unmaps their windows.
541 The slaves will no longer be managed by the grid geometry manager.
542 However, the configuration options for that window are remembered,
544 slave is managed once more by the grid geometry manager, the previous
547 \fBgrid size \fImaster\fR
549 Returns the size of the grid (in columns then rows) for \fImaster\fR.
550 The size is determined either by the \fIslave\fR occupying the largest
551 row or column, or the largest column or row with a \fB\-minsize\fR,
552 \fB\-weight\fR, or \fB\-pad\fR that is non-zero.
554 \fBgrid slaves \fImaster\fR ?\fI\-option value\fR?
556 If no options are supplied, a list of all of the slaves in \fImaster\fR
557 are returned, most recently manages first.
558 \fIOption\fR can be either \fB\-row\fR or \fB\-column\fR which
559 causes only the slaves in the row (or column) specified by \fIvalue\fR
561 .SH "RELATIVE PLACEMENT"
563 The \fBgrid\fR command contains a limited set of capabilities that
564 permit layouts to be created without specifying the row and column
565 information for each slave. This permits slaves to be rearranged,
566 added, or removed without the need to explicitly specify row and
568 When no column or row information is specified for a \fIslave\fR,
569 default values are chosen for
570 \fB\-column\fR, \fB\-row\fR, \fB\-columnspan\fR and \fB\-rowspan\fR
571 at the time the \fIslave\fR is managed. The values are chosen
572 based upon the current layout of the grid, the position of the \fIslave\fR
573 relative to other \fIslave\fRs in the same grid command, and the presence
574 of the characters \fB\-\fR, \fBx\fR, and \fB^\fR in \fBgrid\fR
575 command where \fIslave\fR names are normally expected.
580 This increases the \fB\-columnspan\fR of the \fIslave\fR to the left. Several
581 \fB\-\fR's in a row will successively increase the number of columns spanned. A \fB\-\fR
582 may not follow a \fB^\fR or a \fBx\fR, nor may it be the first \fIslave\fR
583 argument to \fBgrid configure\fR.
587 This leaves an empty column between the \fIslave\fR on the left and
588 the \fIslave\fR on the right.
592 This extends the \fB\-rowspan\fR of the \fIslave\fR above the \fB^\fR's
593 in the grid. The number of \fB^\fR's in a row must match the number of
594 columns spanned by the \fIslave\fR above it.
596 .SH "THE GRID ALGORITHM"
598 The grid geometry manager lays out its slaves in three steps.
599 In the first step, the minimum size needed to fit all of the slaves
600 is computed, then (if propagation is turned on), a request is made
601 of the master window to become that size.
602 In the second step, the requested size is compared against the actual size
603 of the master. If the sizes are different, then spaces is added to or taken
604 away from the layout as needed.
605 For the final step, each slave is positioned in its row(s) and column(s)
606 based on the setting of its \fIsticky\fR flag.
608 To compute the minimum size of a layout, the grid geometry manager
609 first looks at all slaves whose \fB\-columnspan\fR and \fB\-rowspan\fR values are one,
610 and computes the nominal size of each row or column to be either the
611 \fIminsize\fR for that row or column, or the sum of the \fIpad\fRding
612 plus the size of the largest slave, whichever is greater. After that
613 the rows or columns in each uniform group adapt to each other. Then
614 the slaves whose row-spans or column-spans are greater than one are
615 examined. If a group of rows or columns need to be increased in size
616 in order to accommodate these slaves, then extra space is added to each
617 row or column in the group according to its \fIweight\fR. For each
618 group whose weights are all zero, the additional space is apportioned
621 When multiple rows or columns belong to a uniform group, the space
622 allocated to them is always in proportion to their weights. (A weight
623 of zero is considered to be 1.) In other words, a row or column
624 configured with \fB\-weight 1 \-uniform a\fR will have exactly the same
625 size as any other row or column configured with \fB\-weight 1 \-uniform
626 a\fR. A row or column configured with \fB\-weight 2 \-uniform b\fR will
627 be exactly twice as large as one that is configured with \fB\-weight 1
630 More technically, each row or column in the group will have a size
631 equal to \fIk*weight\fR for some constant \fIk\fR. The constant
632 \fIk\fR is chosen so that no row or column becomes smaller than its
633 minimum size. For example, if all rows or columns in a group have the
634 same weight, then each row or column will have the same size as the
635 largest row or column in the group.
637 For masters whose size is larger than the requested layout, the additional
638 space is apportioned according to the row and column weights. If all of
639 the weights are zero, the layout is placed within its master according to
640 the \fIanchor\fR value.
641 For masters whose size is smaller than the requested layout, space is taken
642 away from columns and rows according to their weights. However, once a
643 column or row shrinks to its minsize, its weight is taken to be zero.
644 If more space needs to be removed from a layout than would be permitted, as
645 when all the rows or columns are at their minimum sizes, the layout is
646 placed and clipped according to the \fIanchor\fR value.
647 .SH "GEOMETRY PROPAGATION"
649 The grid geometry manager normally computes how large a master must be to
650 just exactly meet the needs of its slaves, and it sets the
651 requested width and height of the master to these dimensions.
652 This causes geometry information to propagate up through a
653 window hierarchy to a top-level window so that the entire
654 sub-tree sizes itself to fit the needs of the leaf windows.
655 However, the \fBgrid propagate\fR command may be used to
656 turn off propagation for one or more masters.
657 If propagation is disabled then grid will not set
658 the requested width and height of the master window.
659 This may be useful if, for example, you wish for a master
660 window to have a fixed size that you specify.
661 .SH "RESTRICTIONS ON MASTER WINDOWS"
663 The master for each slave must either be the slave's parent
664 (the default) or a descendant of the slave's parent.
665 This restriction is necessary to guarantee that the
666 slave can be placed over any part of its master that is
667 visible without danger of the slave being clipped by its parent.
668 In addition, all slaves in one call to \fBgrid\fR must have the same master.
671 If the master for a slave is not its parent then you must make sure
672 that the slave is higher in the stacking order than the master.
673 Otherwise the master will obscure the slave and it will appear as
674 if the slave has not been managed correctly.
675 The easiest way to make sure the slave is higher than the master is
676 to create the master window first: the most recently created window
677 will be highest in the stacking order.
680 The \fBgrid\fR command is based on ideas taken from the \fIGridBag\fR
681 geometry manager written by Doug. Stein, and the \fBblt_table\fR geometry
682 manager, written by George Howlett.
685 A toplevel window containing a text widget and two scrollbars:
690 text .t.txt \-wrap none \-xscroll {.t.h set} \-yscroll {.t.v set}
691 scrollbar .t.v \-orient vertical \-command {.t.txt yview}
692 scrollbar .t.h \-orient horizontal \-command {.t.txt xview}
695 \fBgrid\fR .t.txt .t.v \-sticky nsew
696 \fBgrid\fR .t.h \-sticky nsew
698 # Tell the text widget to take all the extra room
699 \fBgrid rowconfigure\fR .t .t.txt \-weight 1
700 \fBgrid columnconfigure\fR .t .t.txt \-weight 1
703 Three widgets of equal width, despite their different
708 button .b \-text "Foo"
709 entry .e \-variable foo
710 label .l \-text "This is a fairly long piece of text"
712 \fBgrid\fR .b .e .l \-sticky ew
713 \fBgrid columnconfigure\fR . "all" \-uniform allTheSame
718 geometry manager, location, grid, cell, propagation, size, pack
OSDN Git Service
