checkbutton

Create and manipulate checkbutton widgets


SYNOPSIS

(checkbutton widget-name . options)

Standard options


activeBackground  cursor               highlightThickness  takeFocus 
activeForeground  disabledForeground   image               text 
anchor            font                 justify             textVariable 
background        foreground           padX                underline 
bitmap            highlightBackground  padY                wrapLength 
borderWidth       highlightColor       relief


Widget-specific options

Name: procedure
Class: Command
Command-Line Switch: :procedure

Name: height
Class: Height
Command-Line Switch: :height Name: indicatorOn
Class: IndicatorOn
Command-Line Switch: :indicatoron Name: offValue
Class: Value
Command-Line Switch: :offvalue Name: onValue
Class: Value
Command-Line Switch: :onvalue Name: selectColor
Class: Background
Command-Line Switch: :selectcolor Name: selectImage
Class: SelectImage
Command-Line Switch: :selectimage Name: state
Class: State
Command-Line Switch: :state Name: string-value
Class: StringValue
Command-Line Switch: :string-value

Name: variable
Class: Variable
Command-Line Switch: :variable Name: width
Class: Width
Command-Line Switch: :width

DESCRIPTION

The checkbutton procedure creates a new window (given by the widget-name argument) and makes it into a checkbutton widget. Additional options, described above, may be specified on the procedure line or in the option database to configure aspects of the checkbutton such as its colors, font, text, and initial relief. The checkbutton procedure returns its widget-name argument. At the time this procedure is invoked, there must not exist a window named widget-name, but widget-name's parent must exist.

A checkbutton is a widget that displays a textual string, bitmap or image and a square called an indicator. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the wrapLength option) and one of the characters may optionally be underlined using the underline option. A checkbutton has all of the behavior of a simple button, including the following: it can display itself in either of three different ways, according to the state option; it can be made to appear raised, sunken, or flat; it can be made to flash; and it invokes a STk procedure whenever mouse button 1 is clicked over the checkbutton.

In addition, checkbuttons can be selected. If a checkbutton is selected then the indicator is normally drawn with a sunken relief and a special color, and a STk variable associated with the checkbutton is set to a particular value (normally #t). If the checkbutton is not selected, then the indicator is drawn with a raised relief and no special color, and the associated variable is set to a different value (typically #f). By default, the name of the variable associated with a checkbutton is the same as the name used to create the checkbutton. The variable name, and the ``on'' and ``off'' values stored in it, may be modified with options on the procedure line or in the option database. Configuration options may also be used to modify the way the indicator is displayed (or whether it is displayed at all). By default a checkbutton is configured to select and deselect itself on alternate button clicks. In addition, each checkbutton monitors its associated variable and automatically selects and deselects itself when the variables value changes to and from the button's ``on'' value.


WIDGET COMMAND

The checkbutton procedure creates a new STk procedure whose name is widget-name. This procedure may be used to invoke various operations on the widget. It has the following general form:

Option and the args determine the exact behavior of the procedure. The following procedures are possible for checkbutton widgets:

(widget-name 'cget option)

(widget-name 'configure)
(widget-name 'configure option value...) (widget-name 'deselect)
(widget-name 'flash)
(widget-name :invoke)
(widget-name 'select)
(widget-name 'toggle)

BINDINGS

Tk automatically creates class bindings for checkbuttons that give them the following default behavior:

If the checkbutton's state is disabled then none of the above actions occur: the checkbutton is completely nonresponsive.

The behavior of checkbuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings.


Go to top