joptionbutton.tcl

Introduction

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 one­of­many choice. It's equivalent in functionality to a group of radio buttons, but a little easier to use and more sparing of screen real­estate.

This document describes joptionbutton.tcl version 4.1/4.4.

Usage

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.

Credits and Copyright

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.

Overview

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

j:option

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 non­null), 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 non­null, 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.

j:option:configure

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.

j:option:popup

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

Future Directions