# 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 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 2001.02.10.

## 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-2001by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.

## Overview

### Procedure

`::jstools::option_button` - create option button with associated menu

## ::jstools::option_button

### Usage

`::jstools::option_button` 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
::jstools::option_button .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`
`
::jstools::option_button .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}
}
::jstools::option_button .family \
-list {* times helvetica courier symbol} \
-variable FAMILY -command {set_font .t}
::jstools::option_button .weight \
-list {medium bold demibold light *} \
-variable WEIGHT -command {set_font .t}
::jstools::option_button .slant -list {r i o *} \
-variable SLANT -command {set_font .t}
::jstools::option_button .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`).

## 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 given 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.

`
`