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
The default column span of top-level items. If zero, the item will
span all remaining columns of the grid. The default is zero.
Changing this option only affects the default column span of
items subsequently added to the grid, not of items already added.
Name: childStyle
Class: ChildStyle
Command-Line Switch: -childstyle
The default style of top-level items. The default is "simple".
Name: columnSpan
Class: ColumnSpan
Command-Line Switch: -columnspan
The column span in the grid. The default is four. Changing
this option only affects the layout of items subsequently added
to the grid, not of items already added.
Name: labelAnchor
Class: Anchor
Command-Line Switch: -labelanchor
The default anchoring of the text labels in the simple
style. The value of this option is passed directly to the
-sticky option of the Tk grid command. It can be
overridden for individual widgets and labels by calling the grid
configure command with the Tk widget path as argument.
Name: entryBackground
Class: Background
Command-Line Switch: -entrybackground
The background color used in entry and text widgets.
Name: labelForeground
Class: Foreground
Command-Line Switch: -labelforeground
The foreground color of the text labels.
Name: labelFont
Class: Font
Command-Line Switch: -labelfont
The font of the text labels.
Name: padX
Class: PadX
Command-Line Switch: -padx
The horizontal padding to use when gridding widgets. Widgets
are gridded with the -padx option to the Tk grid command
set to this value. This option is read only when items are
first added to the grid, and will thus not affect items
already added.
Name: padY
Class: PadY
Command-Line Switch: -pady
The horizontal padding to use when gridding widgets. Widgets
are gridded with the -pady option to the Tk grid command
set to this value.
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:
%a is substituted with additional arguments.
%x is substituted with the assigned value (assign only).
%t is substituted with the item tag.
%v is substituted with the control variable.
%w is substituted with the widget path.
%Q is substituted with the Labeledgrid widget.
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
A widget. The tag item is the tag passed to the add method
when the widget was created. Note that if tag is a group, there
will be component named tag.
Name: tagframe
Class: Frame
A frame that is used in the separated and boxed display
styles to contain the border and label.
Name: taglabel
Class: Label
The label of a widget or group, created in the simple,
separated and boxed display styles. See the "label" widget
manual entry for details.
Name: tagborder
Class: Frame
A border in the separated and boxed display styles. This
is a Tk frame -- see the "label" widget manual entry for details.
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