joptionbutton.tcl
The
joptionbutton.tcl library is distributed as part of the
jstools package. It provides a button that pops up an option menu
so your users can make a oneofmany choice. It's equivalent
in functionality to a group of radio buttons, but a little easier
to use and more sparing of screen realestate.
This document describes
joptionbutton.tcl version 4.1/4.4.
Accessing the Library
In order to use the
joptionbutton.tcl library, it (and any other libraries it depends on) must be
in your Tcl
auto_path, described in
tclvars(n). Information about how to arrange that, and other conventions
common to
the
jstools libraries, is in
the
Usage section
of
The jstools Libraries.
Author
Jay Sekora
js@aq.org
http://www.aq.org/~js/
Copyright
The library is copyright © 1992-1995 by Jay Sekora, but may be
freely redistributed under the conditions at the top of the file.
Procedure
j:option - create option button with associated menu
j:option:invoke - execute command associated with option button
j:option:configure - set attributes of option button
j:option:popup - pop up option button's menu
Usage
j:option
w
[options]
Argument
w is the name of the new option button to create
Options
-font
font
(default
{})
-list
list
(default "(none)"; not really optional)
-variable
variable
(default based on name of widget; not really optional)
-command
command
(default
{})
-width
width
(default
20)
-current
current
(default first element of list)
Examples
frame .colour -width 20 -height 40
j:option .option -list {white grey SkyBlue yellow gold} \
-variable BG_COLOUR \
-command {.colour configure -background $BG_COLOUR}
pack .option .colour -fill x
.option invoke ;# make sure colour starts out right
j:option .language -list {en pt fr} \
-variable J_PREFS(language)
proc set_font {widget} {
global FONT FAMILY WEIGHT SLANT SIZE
set FONT "-*-$FAMILY-$WEIGHT-$SLANT-*-*-$SIZE-*"
catch {$widget configure -font $FONT}
}
j:option .family -list {* times helvetica courier symbol}
\
-variable FAMILY -command {set_font .t}
j:option .weight -list {medium bold demibold light *} \
-variable WEIGHT -command {set_font .t}
j:option .slant -list {r i o *} \
-variable SLANT -command {set_font .t}
j:option .size -list {* 80 90 100 120 140 180} \
-variable SIZE -command {set_font .t}
text .t
pack .t -side bottom
pack .family .weight .slant .size -side left
Description
This procedure creates a new option button,
w, with an associated menu, which can be posted by clicking on
the button. An option button is useful for asking the user
to select one option from a constrained set of choices. The
option button displays the string stored in the global variable
variable, and is used to set the value of
variable.
On invocation, if
current is specified, the value of
variable is set to
current, and
current is added to
list if necessary. If
current is not specified, then the option button displays the first
element in
list, and
variable's value is set accordingly. (Note that unlike native Tk widgets,
the option button doesn't take its initial value from
variable if
variable is already defined.)
When the user clicks on the button, a menu appears, containing
all the elements of
list. Choosing an item from the menu will cause the button's text
to change to that item, and cause the item to become the new current
value of the option button, setting the global variable
variable accordingly.
If
command is specified (and nonnull), then it will be evaluated (in
global scope) whenever the value of the option button is set by
choosing an item from the menu or via the widget
set command (described below). This lets you take some sort
of action based on the current value of
variable (or just on the fact that the user has made a choice from the
option button). (The
command is
not automatically executed the first time the option button is
displayed; if you want to guarantee that
command has executed even if the user doesn't change the value of the
option button, you should call `w invoke' yourself when you create the option button.)
If
font is specified and nonnull, both the button and the menu will
be displayed in that font. The menu will be
width characters wide, and the button will also be
width characters wide unless it is packed in such a way as to change
its dimensions.
The current value of the button can be manipulated with the
get and
set widget commands, and the current values of the widget options
can be changed or retrieved with the
configure widget command.
Widget Commands
w get
This widget command returns the current value of the option button's
associated
variable.
w set
value
This widget command sets the current value of the option buttons
variable, displays that value in the button, and invokes
command.
w invoke
This widget command invokes
command.
w configure
option
[argument]
This widget command lets you retrieve (if
argument is omitted) or set (if it is provided) the current value of
any of the widget options (-font,
-list,
-command,
-variable,
-current, or
-width) in the standard format for Tk widget
configure commands (i.e., as a list, the last element of which is the
current value).
w cget
option
This widget command lets you retrieve (only) the current value
of a widget option (-font,
-list,
-command,
-variable,
-current, or
-width).
j:option:invoke
Usage
j:option:invoke
w
Argument
w is the pathname of the option button whose command is to be
invoked
Description
This procedure is used internally by
j:option, and should not need to be called directly. It implements
the
invoke widget command.
Usage
j:option:configure
w
option
[argument]
Arguments
w is the pathname of the option button to be configured
option is
-font,
-list,-command,
-variable,
-current, or
-width
argument, if specified, is the new value of
option
Description
This procedure is used internally by
j:option, and should not need to be called directly. It implements
the
configure widget command.
Usage
j:option:popup
w
button
Arguments
w is the pathname of the frame to hold the popup menu
button is the pathname of the option button
Description
This procedure is used internally by
j:option, and should not need to be called directly. It is invoked
when an option button is clicked on. It creates a new frame
w, packs a listbox in it to simulate a menu, positions it appropriately
over the option button, and sets up mouse bindings letting the
user select an item from the listbox. (The reason for using
a listbox rather than a menu is that the width of a menu can't
be set.)
Bugs and Misfeatures
- Option buttons don't support keyboard traversal.
- If an option button is packed such that it's larger or smaller
than its requested width (as specified by the
-width option), its menu will be the wrong size.
- Only one option at a time can be specified to
j:option:configure, and hence to the
configure widget command. Also, you can't get at the configuration
of the underlying button and menu.
- Because of the way bindings are handled, you can't change
variable (i.e., which global variable holds the result) after creating
an option button.
Future Directions
- Fix the above bugs. :-)
- It would be nice if the value displayed on the button for a
given value didn't have to be the same as the value of
variable; e.g., you might want the values
en or
fr to be displayed as
English or
French, respectively.