iwidgets::Labeledgrid - Create a grid of labeled widgets

SYNOPSIS

iwidgets::Labeledgrid pathName ?options?

INHERITANCE

itk::Widget <- iwidgets::Labeledgrid

STANDARD OPTIONS

background
foreground
cursor
highlightColor
font
highlightThickness
disabledForeground

See the "options" manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS

Name:                   childColumnSpan
Class:                  ChildColumnSpan
Command-Line Switch:	-childcolumnspan

Name:                   childStyle
Class:                  ChildStyle
Command-Line Switch:	-childstyle

Name:                   columnSpan
Class:                  ColumnSpan
Command-Line Switch:	-columnspan

Name:                   labelAnchor
Class:                  Anchor
Command-Line Switch:	-labelanchor

Name:                   entryBackground
Class:                  Background
Command-Line Switch:	-entrybackground

Name:                   labelForeground
Class:                  Foreground
Command-Line Switch:	-labelforeground

Name:                   labelFont
Class:                  Font
Command-Line Switch:	-labelfont

Name:                   padX
Class:                  PadX
Command-Line Switch:	-padx

Name:                   padY
Class:                  PadY
Command-Line Switch:	-pady


DESCRIPTION

The labeledgrid command creates a grid of labeled widgets for user input, such as entry fields, radiobuttons and checkbuttons, option menus, and so on. It uses the Tk grid geometry manager to implement the principles of alignment and grid-based design described in the book "Designing Visual Interfaces: Communication Oriented Techniques", by Kevin Mullet and Darrell Sano, SunSoft Press, 1995.

Mullet and Sano propose that widget layouts use a canonical grid, which is a 12-column grid that can be used to divide a window into one, two, three, four, or six columns. The layout within each window uses different combinations of these columns to produce a pleasing and readable layout. Mullet and Sano's examples generally use the left column for labels -- Labeledgrid supports this as its default mode, but also adds other display styles, such as labeled bounding boxes.

Labeledgrid views a grid as being divided into groups, where each group contains labeled widgets, or other groups. All widgets are placed into the same layout grid, however, ensuring that alignment is achieved even between logical groups. Groups can be contained within other groups, to arbitrary depth, and the widget as a whole is best thought of as the top-level group. Each group and widget has its own label and border, as selected by the display style of that group or widget (see DISPLAY STYLES below).

A group has a number of options that control layout (at the top level, they are specified by options to the widget, at lower levels, by options to the group method). The -columnspan option, for example, is the width occupied by items within the group, not including rows or columns needed for labels and borders. Adding items to a group places the new item at the position determined by the current row and column counters of that group. When the -columnspan of the group is reached, the counters move to the next row. The default values of these layout options are chosen to make is easy to produce a simple layout, and possible to produce a complex one.\ Each group also has a -childcolumnspan option, which specifies the defaullt column span of children; the option can be overridden when a particular child is created.

One of the unique features of Labeledgrid is its ability to perform standard operations on widgets regardless of what type they are. The operations are: setting the current value, reading the current value, enabling and disabling user input, and creating and deleting the widget. This makes access to user input very simple for client programs, and relieves them of any need to understand particular widgets.

Labeledgrid provides a useful set of widgets for placing into a layout, including entry and text fields, radio buttons and check buttons, and option menus. However, since the number of different kinds of widget that could be placed into a Labeledgrid window is potentially unlimited, the newtype procedure is provided so that new widget types can be added to Labeledgrid's collection of known widget types.

ITEM TYPES

By default, Labeledgrid recognises the following widget types:
checkbutton
A Tk checkbutton. Checkbuttons can usefully be placed into groups, as well as being labeled individually.
entry
A Tk entry widget.
labeledgrid
A nested labeled grid widget. This is used if alignment must not be preserved between the new grid's contents and its containing grid. Usually, this occurs only when there are alignment problems caused by the fact that borders use up whole columns or rows of the grid.
optionmenu
An Iwidgets optionmenu.
radiobutton
A Tk radiobutton. Radiobuttons are usually used within a shared item group.
text
A Tk text widget.
type
A widget of some other type. New types can be added to the Labeledgrid class with the newtype procedure, and can then be created in the same way as the built-in item types.

Widgets are added to Labeledgrid with the add method. This method accepts any options that are valid for the particular widget type, and the following:

-label string
The text to place in the item label. The default is null. This option is ignored by the plain display style.
-columnspan int
The number of columns to be spanned by the created widget, not including any borders. The default is the -childcolumnspan of the parent group.
-initial value
The initial value assigned to this widget. If the widget is within a shared group, this option will be ignored.
-sticky string
The "stickiness" of the widget within the grid. This option will be passed to the grid configure command. The default is the -sticky option specified for its type.
-style string
The display style of the item. See DISPLAY STYLES below. The default value is the -childstyle option of the item's parent.

ITEM GROUPS

A new group of items is added to Labeledgrid with the group method. Groups accept many of the same options as regular items, and can have labels and bounding boxes. Items within a group have hierarchical tags; for example, the item foo.bar is within the group foo. Groups accept the following options:
-childcolumnspan int
The default value of the -columnspan option of the group's children. The default is one.
-childstyle string
The default value of -style option of the group's children. The default is plain
-column int
The start column of the group, as an absolute value (in other words, the column is not relative to the start of the parent group). This is the first column that will be used for any component of the group, including its label or border. This option should be used sparingly, if at all. The default is the current column counter of its parent group.
-columnspan int
The number of columns spanned by the group. This includes the label and borders of child items but does not include the labels and borders of the group itself. The default is the -childcolumnspan of its parent group, or the number of columns remaining with the parent group, whichever is smallest.
-initial value
If not null, the initial value of a variable created for the whole group. In this case, all items in the group are given a shared variable rather than individual ones, and the value of the group will be the value of this variable. This is most useful for radiobutton groups. If this option is null, each item will get its own variable and the value of the group will be a compsite of the values of each child item.
-label string
The text to place in the group's label. This option is ignored by the plain display mode.
-row int
The start row of the group, as an absolute value (in other words, the row is not relative to the start of the parent group). This is the first row that will be used for any component of the group, including its label or border. This option should be used sparingly, if at all. The default is the current row counter of its parent group.
-rowspan int
The number of rows spanned by the group. This includes the label and borders of child items but does not include the labels and borders of the group itself. If zero, the group expands until the next sibling item is added. The default is one.
-style string
The display style of the group. See DISPLAY STYLES below. The default value is the -childstyle option of the group's parent.

ADDING NEW TYPES

Labeledgrid provides a mechanism for defining new item types. For each of the operations it supports on its items, it has a small script that it evaluates to perform this action. These scripts are added to the Labeledgrid class with the newtype procedure, which accepts a number of options that specify the scripts that Labeledgrid evaluates to perform operations on items of the new type. These options are:
-assign
The script to assign a value to an item. If null, an attempt to assign a value will raise an error. The default is {set %v %a}.
-create
The script to create an item. An error will be raised if this option is not specified.
-delete
The script to delete an item. The default is {destroy %w}. If null, an error will be raised on an attempt to delete that type.
-disable
Disable user input to the item. If null, the type cannot be disabled. The default is {%w configure -state disabled}.
-enable
Enable user input to the item. If null, the widget cannot be enabled. The default is {%w configure -state normal}.
-get
Get the item's value. If null, the item will not appear in the results of any value-getting methods. The default is {set %v}.
-options
A string passed as the second argument to itk_component add when the widget is created. The default is {usual}, which will cause the following option-handling command to be used:
keep -font -background -cursor \
    -disabledforeground -foreground \
    -highlightthickness -highlightcolor
-sticky
The default "stickiness" of widget of thos type.

Before evaluating a script, Labeledgrid performs the following substitutions:

DISPLAY STYLES

Labeledgrid supports several display styles. A display style is simply a combination of label position and item border. Different display styles can be mixed, although this should of course be done with care and there are some caveats (note that the default behaviour of Labeledgrid is to use the same display style for every item within a group.) Depending on the style, zero or more rows or columns of the grid may be used, in addition to the rows and columns required to display the item itself. The display styles are:
plain
There is no label or border, and no additional rows or columns are used. This style is generally used for groups of radiobuttons or checkbuttons. It can also be used for items that need to occupy the same row as another item, but without its own label, and as a way of grouping related widgets without any explicit visual structure.
simple
The label is drawn in the column to the left of the item. The label anchor is given by the -labelanchor widget option. There is no border drawn around the item. This style uses one additional row. This is the style used in the examples in Mullet and Sano's book.
boxed
The label is drawn in the row above the item, and a border is drawn around the whole item. An additional row or column on all four sides is required for the border and label. This style is very popular but shouldn't be used to the point of cluttering the layout. Mullet and Sano comment: "While the practice is encouraged by many environments, it should be used with restraint, since explicit structure is a very poor substitute for effective spatial segregation." (p110).
separated
The label is drawn in the row above the item, and a horizontal line line spanning its width drawn under the label. This is useful for separating large dialog boxes into two or three distinct vertical regions. It uses a row for the separator line and a column to the left of the item for spacing.

The default behavior of Labeledgrid is to give top-level items the simple style, and items within those the plain style -- plain and simple...

CAVEATS

Labeledgrid is designed to make it easy to construct designed layouts. It provides no support for changing an existing layout. Although layouts can be moved around by directly calling the Tk grid command, this is unlikely to be very reliable.

There are also some caveats associated with mixing different display styles within the same grid. Firstly, the -columnspan and -rowspan options of groups need to take into account the display styles of children. If display styles in an existing layout are changed, the options may need tweaking to get the layout right again. Secondly, since labels and borders use up whole rows or columns of the grid, some care needs to be taken to avoid placing items within the same column (for example) as a border in another part of the layout. A workaround is simply to recursively create Labeledgrid widgets: alignment isn't preserved between a nested labeled grid and the containing labeledgrid.

METHODS

The iwidgets::labeledgrid command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args determine the exact behavior of the command. The following commands are possible for iwidgets::Labeledgrid widgets:

ASSOCIATED PROCEDURE

iwidgets::Labeledgrid::newtype type ?option value ...?
Add a new item type to the Labeledgrid class. The first argument is the item type that will be passed to the add method. It is usually the same as the widget command, but there is no need for it to be. Following arguments are an option-value list, where legal options are as described in the section ADDING NEW TYPES above. This procedures raises an error if the _type_ already exists, or if an invalid option is specified.

WIDGET-SPECIFIC METHODS

pathName add type tag ?option value ...?
Add a new item to the grid. The first argument is type of widget to create. This is followed by the tag that will be used to reference the widget, then an option-value list. The options can be any that are valid for the widget type type, plus options that specify labeling and positioning information, as described in the section Item Types above. For each item, a variable is created that can be used to hold its value, which can be accessed within control scripts as %v.
pathName assign tag value
Assign a value to an item. If the item is a group with a shared variable, the value is be assigned to the shared variable. If the group is not shared, the value must be a list of name-value pairs, where each name is relative to tag. Each group member that appears in the list is assigned the corresponding value. If assignment is supported for the item's type, assign value to the item; if assignment is not supported, raise an error. Raise an error if tag does not exist.
pathName delete tag
Delete an item. If the item is a group, all members of the group will also be deleted. Raise an error if tag does not exist, or if deletion is not supported for its type.
pathName disable tag
Disable an item. If the item is a group, all members of the group will also be disabled. Raise an error if tag does not exist.
pathName enable tag
Enable an item. If the item is a group, all members of the group will also be enabled. Raise an error if tag does not exist.
pathName exists tag
Return one if tag is an item in this Query widget, otherwise zero.
pathName get ?tag?
Get the value of one or more items. If tag is a widget, return that item's value, or null if getting the value is not supported for the item's type. If tag is a group with a shared variable, return the value of the shared variable. If tag is any other group, return a name-value list of its members, where each name is relative to tag. If tag is not supplied, return a name-value list of all top-level items. Raise an error if tag is supplied but is not an item.
pathName group tag ?option value?
Add a group. Options are as described in Item Groups above. Raise an error if an item with that tag already exists.
pathName hskip ?group? ?option value?
Skip a column. If group is supplied, it is the name of the group within which to skip; if it is not supplied, the skip takes place at the top level. The current row counter is incremented by one; if this takes the counter past the end of the group, vskip is called to move to the next row. Following arguments are an option-value list: these can be any options supported by the Tk grid columnconfigure command are supported -- that is, -minsize, pad, and -weight. The options will be applied to the current column before the skip. Note that these options will affect the grid used by all items, not just the grid with the given group.
pathName vskip ?group? ?option value...?
Skip a row. If group is supplied, it is the name of the group within which to skip; if not supplied, the skip is at the top level. The current row counter is incremented by the row span of the item in the current row with the largest row span, and the current column counter is reset to the start column of the group. Following arguments are an option-value list. Legal options options are those supported by the Tk grid rowconfigure command are supported -- that is, -minsize, pad, and -weight. These will applied to the current row before skipping. Note that these options will affect the grid used by all items, not just the grid with the given group.

COMPONENTS

Labeledgrid dynamically creates components as widgets and groups are added to the grid.

Name:                   tag
Class:                  widgetclass

Name:                   tagframe
Class:                  Frame

Name:                   taglabel
Class:                  Label

Name:                   tagborder
Class:                  Frame

EXAMPLE

_EXAMPLE_CODE_

AUTHOR

John Reekie, johnr@eecs.berkeley.edu

ACKNOWLEDGMENTS

Based on the tycho::Query widget by Prof. Edward A. Lee of UC Berkeley. iwidgets::Labeledgrid adds more structured grid placement, different display styles, and the facility to support arbitrary widget types. Original author is Prof. Edward A. Lee; additional contributions by Joel R. King, Bilung Lee, Christopher Hylands, Seehyun Kim, and Mark L. Ulferts. Labeledgrid is contributed to [incr Widgets] by the Tycho project at UC Berkeley: http://ptolemy.eecs.berkeley.edu/tycho.

KEYWORDS

labeledgrid, grid, widget