diff options
Diffstat (limited to 'man/9/grid')
| -rw-r--r-- | man/9/grid | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/man/9/grid b/man/9/grid new file mode 100644 index 00000000..95b84204 --- /dev/null +++ b/man/9/grid @@ -0,0 +1,332 @@ +.TH GRID 9 +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +grid \- Geometry manager that arranges widgets in a grid +.SH SYNOPSIS +\f5grid \fIoption arg \fR?\fIarg ...\fR? + +.SH DESCRIPTION +.PP +The \f5grid\fR command is used to communicate with the grid +geometry manager that arranges widgets in rows and columns inside +of another window, called the geometry master (or master window). +The \f5grid\fR command can have any of several forms, depending +on the \fIoption\fR argument: +.TP +\f5grid bbox \fImaster\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR? +With no arguments, +the bounding box (in pixels) of the grid is returned. +The return value consists of 4 integers. The first two are the pixel +offset from the master window (x then y) of the top-left corner of the +grid, and the second two integers are the bottom-right corner of the grid, +also in pixels. If a single \fIcolumn\fP and \fIrow\fP is specified on +the command line, then the bounding box for that cell is returned, where the +top left cell is numbered from zero. If both \fIcolumn\fP and \fIrow\fP +arguments are specified, then the bounding box spanning the rows and columns +indicated is returned. +.TP +\f5grid cellinfo \fImaster column row\fR +Returns a list giving information about the slave +currently held in the grid cell specified by +\fIcolumn\fP and \fIrow\fP. +The first element of the list is the name of the slave, +and the rest have the same option-value form that +might be specified to \f5grid configure\fR +(the same form as returned by \f5grid info\fR). +.TP +\f5grid columnconfigure \fImaster index \fR?\fI-option value...\fR? +Set the column properties of the \fIindex\fP column of the +geometry master, \fImaster\fP. +The valid options are \f5-minsize\fP, \f5-weight\fP, \f5-pad\fP and \f5-name\fP. +If one or more options are provided, then \fIindex\fP may be given as +a list of column indices to which the configuration options will operate on. +The \f5-minsize\fP option sets the minimum size, in screen units, +that will be permitted for this column. +The \f5-weight\fP option (an integer value) +sets the relative weight for apportioning +any extra spaces among +columns. +A weight of zero (0) indicates the column will not deviate from its requested +size. A column whose weight is two will grow at twice the rate as a column +of weight one when extra space is allocated to the layout. +The \f5-pad\fP option specifies a pad distance that will be +added either side of the column; adjacent columns merge their padding, +creating a pad sized to the larger of the pads on either column. +The \f5-name\fP option associates a name with the column, which can +then be used as an index to refer to that column. +.TP +\f5grid \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? +The arguments consist of the names of one or more slave windows +followed by pairs of arguments that specify how +to manage the slaves. +The characters \f5-\fP, \f5x\fP and \f5^\fP, +can be specified instead of a window name to alter the default +location of a \fIslave\fP, as described in the ``RELATIVE PLACEMENT'' +section, below. +The following options are supported: +.RS +.TP +\f5-column \fIindex\fR +Insert the slave so that it occupies the \fIindex\fPth column in the grid. +Column numbers start with 0. If this option is not supplied, then the +slave is arranged just to the right of previous slave specified on this +call to \fIgrid\fP, or column "0" if it is the first slave. For each +\f5x\fP that immediately precedes the \fIslave\fP, the column position +is incremented by one. Thus the \f5x\fP represents a blank column +for this row in the grid. +.TP +\f5-columnspan \fIn\fR +Insert the slave so that it occupies \fIn\fP columns in the grid. +The default is one column, unless the window name is followed by a +\f5-\fP, in which case the columnspan is incremented once for each immediately +following \f5-\fP. +.TP +\f5-in \fIother\fR +Insert the slave(s) in the master +window given by \fIother\fR. The default is the first slave's +parent window. +.TP +\f5-ipadx \fIamount\fR +The \fIamount\fR specifies how much horizontal internal padding to +leave on each side of the slave(s). This is space is added +inside the slave(s) border. +The \fIamount\fR must be a valid screen distance, such as \f52\fR or \f5.5c\fR. +It defaults to 0. +.TP +\f5-ipady \fIamount\fR +The \fIamount\fR specifies how much vertical internal padding to +leave on on the top and bottom of the slave(s). +This space is added inside the slave(s) border. +The \fIamount\fR defaults to 0. +.TP +\f5-padx \fIamount\fR +The \fIamount\fR specifies how much horizontal external padding to +leave on each side of the slave(s), in screen units. +The \fIamount\fR defaults to 0. +This space is added outside the slave(s) border. +.TP +\f5-pady \fIamount\fR +The \fIamount\fR specifies how much vertical external padding to +leave on the top and bottom of the slave(s), in screen units. +The \fIamount\fR defaults to 0. +This space is added outside the slave(s) border. +.TP +\f5-row \fIindex\fR +Insert the slave so that it occupies the \fIindex\fPth row in the grid. +Row numbers start with 0. If this option is not supplied, then the +slave is arranged on the same row as the previous slave specified on this +call to \f5grid\fP, or the first unoccupied row if this is the first slave. +.TP +\f5-rowspan \fIn\fR +Insert the slave so that it occupies \fIn\fP rows in the grid. +The default is one row. If the next \f5grid\fP command contains +\f5^\fP characters instead of \fIslaves\fP that line up with the columns +of this \fIslave\fP, then the \f5rowspan\fP of this \fIslave\fP is +extended by one. +.TP +\f5-sticky \fIstyle\fR +If a slave's cell is larger than its requested dimensions, this +option may be used to position (or stretch) the slave within its cell. +\fIStyle\fR is a string that contains zero or more of the characters +\f5n\fP, \f5s\fP, \f5e\fP or \f5w\fP. +The string can optionally contains spaces or +commas, but they are ignored. Each letter refers to a side (north, south, +east, or west) that the slave will "stick" to. If both \f5n\fP and \f5s\fP (or +\f5e\fP and \f5w\fP) are specified, the slave will be stretched to fill the entire +height (or width) of its cavity. The \f5sticky\fP option subsumes the +combination of \f5-anchor\fP and \f5-fill\fP that is used by \f5pack\fP. +The default is \f5{}\fP, which causes the slave to be centered in its cavity, +at its requested size. +.LP +If any of the slaves are already managed by the geometry manager +then any unspecified options for them retain their previous values rather +than receiving default values. +.LP +It is an error if any \fIslave\fP covers an area already covered by an +existing slave of the grid. +.RE +.TP +\f5grid columndelete \fImaster index0 \fR?\fIindex1\fR? +Deletes columns from \fIindex0\fP up to but not including \fIindex1\fP, +If \fIindex1\fP is not given, it defaults to \fIindex0\fP+1. +The deleted columns may not contain cells spanned by +slaves outside the deleted columns. +.TP +\f5grid columnindex \fImaster index\fP +Returns \fIindex\fP as a numerical index into the column. +.TP +\f5grid columninsert \fImaster index \fR?\fIcount\fR? +Inserts \fIcount\fP (default 1) new columns just before \fIindex\fP. +The inserted rows may not split a spanning cell. +.TP +\f5grid forget \fIslave \fR?\fIslave ...\fR? +Removes each of the \fIslave\fRs from grid for its +master and unmaps their windows. +The slaves will no longer be managed by the grid geometry manager. +The configuration options for that window are forgotten, so that if the +slave is managed once more by the grid geometry manager, the initial +default settings are used. +.TP +\f5grid info \fIslave\fR +Returns a list whose elements are the current configuration state of +the slave given by \fIslave\fR in the same option-value form that +might be specified to \f5grid configure\fR. +The first two elements of the list are ``\f5-in \fImaster\fR'' where +\fImaster\fR is the slave's master. +.TP +\f5grid location \fImaster x y\fR +Given \fIx\fP and \fIy\fP values in screen units relative to the master window, +the column and row number at that \fIx\fP and \fIy\fP location is returned. +For locations that are above or to the left of the grid, \f5-1\fP is returned. +.TP +\f5grid propagate \fImaster\fR ?\fIboolean\fR? +If \fIboolean\fR has a true boolean value such as \f51\fR or \f5on\fR +then propagation is enabled for \fImaster\fR, which must be a window +name (see ``GEOMETRY PROPAGATION'' below). +If \fIboolean\fR has a false boolean value then propagation is +disabled for \fImaster\fR. +In either of these cases an empty string is returned. +If \fIboolean\fR is omitted then the command returns \f50\fR or +\f51\fR to indicate whether propagation is currently enabled +for \fImaster\fR. +Propagation is enabled by default. +.TP +\f5grid rowconfigure \fImaster index \fR?\fI-option value...\fR? +Set the row properties of the \fIindex\fP row of the +geometry master, \fImaster\fP. +The valid options are \f5-minsize\fP, \f5-weight\fP, \f5-pad\fP and \f5-name\fP. +If one or more options are provided, then \fIindex\fP may be given as +a list of row indices to which the configuration options will operate on. +The \f5-minsize\fP option sets the minimum size, in screen units, +that will be permitted for this row. +The \f5-weight\fP option (an integer value) +sets the relative weight for apportioning +any extra spaces among +rows. +A weight of zero (0) indicates the row will not deviate from its requested +size. A row whose weight is two will grow at twice the rate as a row +of weight one when extra space is allocated to the layout. +The \f5-pad\fP option specifies a pad distance that will be +added either side of the row; adjacent rows merge their padding, +creating a pad sized to the larger of the pads on either row. +The \f5-name\fP option associates a name with the row, which can +then be used as an index to refer to that row. +.TP +\f5grid rowdelete \fImaster index0 \fR?\fIindex1\fR? +Deletes rows from \fIindex0\fP up to but not including \fIindex1\fP, +If \fIindex1\fP is not given, it defaults to \fIindex0\fP+1. +The deleted rows may not contain cells spanned by +slaves outside the deleted columns. +.TP +\f5grid rowindex \fImaster index\fP +Returns \fIindex\fP as a numerical index into the row. +.TP +\f5grid rowinsert \fImaster index \fR?\fIcount\fR? +Inserts \fIcount\fP (default 1) new rows just before \fIindex\fP. +The inserted rows may not split a spanning cell. +.TP +\f5grid size \fImaster\fR +Returns the size of the grid (in columns then rows) for \fImaster\fP. +The size is determined either by the largest row or column that has +been occupied by a slave, or the largest column or row that has been explicitly +configured. +.TP +\f5grid slaves \fImaster\fR ?\fI-option value\fR? +If no options are supplied, a list of all of the slaves in \fImaster\fR +are returned, most recently manages first. +\fIOption\fP can be either \f5-row\fP or \f5-column\fP which +causes only the slaves in the row (or column) specified by \fIvalue\fP +to be returned. +.SS INDICES +.PP +An index is either a non-negative integer value, the string +\f5end\fP, (one beyond the last index in the row or column in question), +or a name identifying a row or column previously named with +the \f5-name\fP option to \f5rowconfigure\fP or \f5columnconfigure\fP. +.SS "RELATIVE PLACEMENT" +.PP +The \f5grid\fP command contains a limited set of capabilities that +permit layouts to be created without specifying the row and column +information for each slave. This permits slaves to be rearranged, +added, or removed without the need to explicitly specify row and +column information. +When no column or row information is specified for a \fIslave\fP, +default values are chosen for +\f5column\fP, \f5row\fP, \f5columnspan\fP and \f5rowspan\fP +at the time the \fIslave\fP is managed. The values are chosen +based upon the current layout of the grid, the position of the \fIslave\fP +relative to other \fIslave\fPs in the same grid command, and the presence +of the characters \f5-\fP, \f5^\fP, and \f5^\fP in \f5grid\fP +command where \fIslave\fP names are normally expected. +.RS +.TP +\f5-\fP +This increases the columnspan of the \fIslave\fP to the left. Several +\f5-\fP's in a row will successively increase the columnspan. A \f5-\fP +may not follow a \f5^\fP or a \f5x\fP. +.TP +\f5x\fP +This leaves an empty column between the \fIslave\fP on the left and +the \fIslave\fP on the right. +.TP +\f5^\fP +This extends the \f5rowspan\fP of the \fIslave\fP above the \f5^\fP's +in the grid. The number of \f5^\fP's in a row must match the number of +columns spanned by the \fIslave\fP above it. +.RE +.SS "THE GRID ALGORITHM" +.PP +The grid geometry manager lays out its slaves in three steps. +In the first step, the minimum size needed to fit all of the slaves +is computed, then (if propagation is turned on), a request is made +of the master window to become that size. +In the second step, the requested size is compared against the actual size +of the master. If the sizes are different, then spaces is added to or taken +away from the layout as needed. +For the final step, each slave is positioned in its row(s) and column(s) +based on the setting of its \fIsticky\fP flag. +.PP +To compute the minimum size of a layout, the grid geometry manager +first looks at all slaves whose columnspan and rowspan values are one, +and computes the nominal size of each row or column to be either the +\fIminsize\fP for that row or column, or the sum of the \fIpad\fPding +plus the size of the largest slave, whichever is greater. Then the +slaves whose rowspans or columnspans are greater than one are +examined. If a group of rows or columns need to be increased in size +in order to accommodate these slaves, then extra space is added to each +row or column in the group according to its \fIweight\fP. For each +group whose weights are all zero, the additional space is apportioned +equally. +.PP +For masters whose size is larger than the requested layout, the additional +space is apportioned according to the row and column weights. If all of +the weights are zero, the layout is centered within its master. +For masters whose size is smaller than the requested layout, space is taken +away from columns and rows according to their weights. However, once a +column or row shrinks to its minsize, its weight is taken to be zero. +If more space needs to be removed from a layout than would be permitted, as +when all the rows or columns are at their minimum sizes, the layout is +clipped on the bottom and right. +.SS "GEOMETRY PROPAGATION" +.PP +The grid geometry manager normally computes how large a master must be to +just exactly meet the needs of its slaves, and it sets the +requested width and height of the master to these dimensions. +This causes geometry information to propagate up through a +window hierarchy to a top-level window so that the entire +sub-tree sizes itself to fit the needs of the leaf windows. +However, the \f5grid propagate\fR command may be used to +turn off propagation for one or more masters. +If propagation is disabled then grid will not set +the requested width and height of the master window. +This may be useful if, for example, you wish for a master +window to have a fixed size that you specify. +.SS CREDITS +.PP +The \f5grid\fP command is based on ideas taken from the \fIGridBag\fP +geometry manager written by Doug. Stein, and the \f5blt_table\fR geometry +manager, written by George Howlett. +.SH "SEE ALSO" +.IR pack (9), +.IR types (9), +.IR options (9) |