Manual Pages for UNIX Darwin command on man grid

grid(n) Tk Built-In Commands grid(n)

NAME

grid - Geometry manager that arranges widgets in a grid

SYNOPSIS

ggrriidd option arg ?arg ...?

DESCRIPTION

The ggrriidd 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 ggrriidd command can have any of several forms, depending on the option argument: ggrriidd slave ?slave ...? ?options? If the first argument to ggrriidd is suitable as the first slave argument to ggrriidd ccoonnffiigguurree, either a window name (any value

starting with ..) or one of the characters xx or ^^ (see the ``REL-

ATIVE PLACEMENT'' section below), then the command is processed in the same way as ggrriidd ccoonnffiigguurree. ggrriidd bbbbooxx master ?column row? ?column2 row2?

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 width and height of the grid, also in pixels. If a single

column and row is specified on the command line, then the bound-

ing box for that cell is returned, where the top left cell is

numbered from zero. If both column and row arguments are speci-

fied, then the bounding box spanning the rows and columns indi-

cated is returned.

ggrriidd ccoolluummnnccoonnffiigguurree master index ?-option value...?

Query or set the column properties of the index column of the

geometry master, master. The valid options are -mmiinnssiizzee, |

-wweeiigghhtt, -uunniiffoorrmm and -ppaadd. If one or more options are pro-

vided, then index may be given as a list of column indeces to

which the configuration options will operate on. The -mmiinnssiizzee

option sets the minimum size, in screen units, that will be per-

mitted for this column. The -wweeiigghhtt 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 -uunniiffoorrmm option, when a |

non-empty value is supplied, places the column in a uniform |

group with other columns that have the same value for -uunniiffoorrmm. |

The space for columns belonging to a uniform group is allocated | so that their sizes are always in strict proportion to their |

-wweeiigghhtt values. See ``THE GRID ALGORITHM'' below for further |

details. The -ppaadd option specifies the number of screen units

that will be added to the largest window contained completely in

that column when the grid geometry manager requests a size from

the containing window. If only an option is specified, with no value, the current value of that option is returned. If only

the master window and index is specified, all the current set-

tings are returned in an list of "-option value" pairs.

ggrriidd ccoonnffiigguurree slave ?slave ...? ?options? 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 -, xx and ^^, can be specified instead of

a window name to alter the default location of a slave, as described in the ``RELATIVE PLACEMENT'' section, below. The following options are supported:

-ccoolluummnn n

Insert the slave so that it occupies the nth 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 grid,

or column "0" if it is the first slave. For each xx that immediately precedes the slave, the column position is incremented by one. Thus the xx represents a blank column

for this row in the grid.

-ccoolluummnnssppaann n

Insert the slave so that it occupies n columns in the

grid. The default is one column, unless the window name

is followed by a -, in which case the columnspan is

incremented once for each immediately following -.

-iinn other

Insert the slave(s) in the master window given by other. The default is the first slave's parent window.

-iippaaddxx amount

The amount 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 amount must be a valid screen distance, such as 22 or ..55cc. It defaults to 0.

-iippaaddyy amount

The amount 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 amount defaults to 0.

-ppaaddxx amount

The amount specifies how much horizontal external padding to leave on each side of the slave(s), in screen units. Amount may be a list of two values to specify padding for left and right separately. The amount defaults to 0. This space is added outside the slave(s) border.

-ppaaddyy amount

The amount specifies how much vertical external padding to leave on the top and bottom of the slave(s), in screen units. Amount may be a list of two values to specify padding for top and bottom separately. The amount defaults to 0. This space is added outside the slave(s) border.

-rrooww n Insert the slave so that it occupies the nth 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 ggrriidd, or the first unoccupied row if this is the first slave.

-rroowwssppaann n

Insert the slave so that it occupies n rows in the grid.

The default is one row. If the next ggrriidd command con-

tains ^^ characters instead of slaves that line up with the columns of this slave, then the rroowwssppaann of this slave is extended by one.

-ssttiicckkyy style

If a slave's cell is larger than its requested dimen-

sions, this option may be used to position (or stretch)

the slave within its cell. Style is a string that con-

tains zero or more of the characters nn, ss, ee or ww. 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 nn and ss (or ee and ww) are specified, the slave will be stretched to fill the entire height (or width) of its cavity. The ssttiicckkyy option subsumes the combination of

-aanncchhoorr and -ffiillll that is used by ppaacckk. The default is

{{}}, which causes the slave to be centered in its cavity, at its requested size. If any of the slaves are already managed by the geometry manager

then any unspecified options for them retain their previous val-

ues rather than receiving default values. ggrriidd ffoorrggeett slave ?slave ...?

Removes each of the slaves 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. ggrriidd iinnffoo slave Returns a list whose elements are the current configuration

state of the slave given by slave in the same option-value form

that might be specified to ggrriidd ccoonnffiigguurree. The first two ele-

ments of the list are ``-iinn master'' where master is the slave's

master. ggrriidd llooccaattiioonn master x y Given x and y values in screen units relative to the master window, the column and row number at that x and y location is returned. For locations that are above or to the left of the

grid, -11 is returned.

ggrriidd pprrooppaaggaattee master ?boolean?

If boolean has a true boolean value such as 11 or oonn then propa-

gation is enabled for master, which must be a window name (see ``GEOMETRY PROPAGATION'' below). If boolean has a false boolean value then propagation is disabled for master. In either of these cases an empty string is returned. If boolean is omitted then the command returns 00 or 11 to indicate whether propagation is currently enabled for master. Propagation is enabled by default.

ggrriidd rroowwccoonnffiigguurree master index ?-option value...?

Query or set the row properties of the index row of the geometry

master, master. The valid options are -mmiinnssiizzee, -wweeiigghhtt, -uunnii- |

ffoorrmm and -ppaadd. If one or more options are provided, then index

may be given as a list of row indeces to which the configuration

options will operate on. The -mmiinnssiizzee option sets the minimum

size, in screen units, that will be permitted for this row. The

-wweeiigghhtt 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 |

-uunniiffoorrmm option, when a non-empty value is supplied, places the |

row in a uniform group with other rows that have the same value |

for -uunniiffoorrmm. The space for rows belonging to a uniform group |

is allocated so that their sizes are always in strict proportion |

to their -wweeiigghhtt values. See ``THE GRID ALGORITHM'' below for |

further details. The -ppaadd option specifies the number of screen

units that will be added to the largest window contained com-

pletely in that row when the grid geometry manager requests a

size from the containing window. If only an option is speci-

fied, with no value, the current value of that option is returned. If only the master window and index is specified, all

the current settings are returned in an list of "-option value"

pairs. ggrriidd rreemmoovvee slave ?slave ...?

Removes each of the slaves from grid for its master and unmaps

their windows. The slaves will no longer be managed by the grid

geometry manager. However, the configuration options for that window are remembered, so that if the slave is managed once more

by the grid geometry manager, the previous values are retained.

ggrriidd ssiizzee master

Returns the size of the grid (in columns then rows) for master.

The size is determined either by the slave occupying the largest row or column, or the largest column or row with a mmiinnssiizzee,

wweeiigghhtt, or ppaadd that is non-zero.

ggrriidd ssllaavveess master ?-option value?

If no options are supplied, a list of all of the slaves in mas-

ter are returned, most recently manages first. Option can be

either -rrooww or -ccoolluummnn which causes only the slaves in the row

(or column) specified by value to be returned. RREELLAATTIIVVEE PPLLAACCEEMMEENNTT The ggrriidd 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 informa-

tion. When no column or row information is specified for a slave, default values are chosen for ccoolluummnn, rrooww, ccoolluummnnssppaann and rroowwssppaann at the time the slave is managed. The values are chosen based upon the

current layout of the grid, the position of the slave relative to other

slaves in the same grid command, and the presence of the characters -,

xx, and ^^ in ggrriidd command where slave names are normally expected.

- This increases the columnspan of the slave to the left.

Several -'s in a row will successively increase the

columnspan. A - may not follow a ^^ or a xx, nor may it be

the first slave argument to ggrriidd ccoonnffiigguurree. xx This leaves an empty column between the slave on the left and the slave on the right. ^^ This extends the rroowwssppaann of the slave above the ^^'s in

the grid. The number of ^^'s in a row must match the num-

ber of columns spanned by the slave above it. TTHHEE GGRRIIDD AALLGGOORRIITTHHMM

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 com-

puted, 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 sticky flag.

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 minsize for that row or column, or the sum of the padding plus the size of the largest slave, whichever is greater. After that the rows or columns in each uniform group adapt to each other. 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 col-

umn in the group according to its weight. For each group whose weights are all zero, the additional space is apportioned equally. When multiple rows or columns belong to a uniform group, the space allocated to them is always in proportion to their weights. (A weight

of zero is considered to be 1.) In other words, a row or column con-

figured with -wweeiigghhtt 11 -uunniiffoorrmm aa will have exactly the same size as

any other row or column configured with -wweeiigghhtt 11 -uunniiffoorrmm aa. A row or

column configured with -wweeiigghhtt 22 -uunniiffoorrmm bb will be exactly twice as

large as one that is configured with -wweeiigghhtt 11 -uunniiffoorrmm bb.

More technically, each row or column in the group will have a size equal to k*weight for some constant k. The constant k is chosen so

that no row or column becomes smaller than its minimum size. For exam-

ple, if all rows or columns in a group have the same weight, then each row or column will have the same size as the largest row or column in the group.

For masters whose size is larger than the requested layout, the addi-

tional space is apportioned according to the row and column weights.

If all of the weights are zero, the layout is centered within its mas-

ter. 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 there mini-

mum sizes, the layout is clipped on the bottom and right. GGEEOOMMEETTRRYY PPRROOPPAAGGAATTIIOONN

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 geome-

try 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 ggrriidd pprrooppaaggaattee 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 mas-

ter window to have a fixed size that you specify. RREESSTTRRIICCTTIIOONNSS OONN MMAASSTTEERR WWIINNDDOOWWSS The master for each slave must either be the slave's parent (the default) or a descendant of the slave's parent. This restriction is necessary to guarantee that the slave can be placed over any part of its master that is visible without danger of the slave being clipped by its parent. In addition, all slaves in one call to ggrriidd must have the same master. SSTTAACCKKIINNGG OORRDDEERR If the master for a slave is not its parent then you must make sure

that the slave is higher in the stacking order than the master. Other-

wise the master will obscure the slave and it will appear as if the slave hasn't been managed correctly. The easiest way to make sure the slave is higher than the master is to create the master window first: the most recently created window will be highest in the stacking order. CCRREEDDIITTSS

The ggrriidd command is based on ideas taken from the GridBag geometry man-

ager written by Doug. Stein, and the bbllttttaabbllee geometry manager, writ-

ten by George Howlett. KKEEYYWWOORRDDSS