Ruby/TK - Checkbutton Widget



A Checkbutton is like a regular button, except that not only can the user press it, which will invoke a command callback, but it also holds a binary value of some kind (i.e., a toggle). Checkbuttons are used all the time when a user is asked to choose between, e.g., two different values for an option.

A checkbutton can display a textual string, bitmap or image. 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 Tcl command whenever mouse button 1 is clicked over the checkbutton.


Here is a simple syntax to create this widget − {
   .....Standard Options....
   .....Widget-specific Options....

Standard Options

  • activebackground
  • activeforeground
  • anchor
  • background
  • bitmap
  • borderwidth
  • compound
  • cursor
  • disabledforeground
  • font
  • foreground
  • highlightbackground
  • highlightcolor
  • highlightthickness
  • image
  • justify
  • padx
  • pady
  • relief
  • takefocus
  • text
  • textvariable
  • underline
  • wraplength

These options have been described in the previous chapter.

Widget Specific Options

Sr.No. Options & Description

command => String

Specifies a Ruby command to associate with the button. This command is typically invoked when mouse button 1 is released over the button window. Here you can associate a Ruby method to be executed against mouse click. Built in function which can be called using command option −

  • deselect − Deselects the checkbutton and sets the associated variable to its "off" value.

  • flash − Flashes the checkbutton. This is accomplished by redisplaying the checkbutton several times, alternating between active and normal colors.

  • select − Selects the checkbutton and sets the associated variable to its "on" value.

  • toggle − Toggles the selection state of the button, redisplaying it and modifying its associated variable to reflect the new state.


height => Integer

Specifies a desired height for the button.


indicatoron => Boolean

Specifies whether or not the indicator should be drawn. Must be a proper boolean value. If false, the relief option is ignored and the widget's relief is always sunken if the widget is selected and raised otherwise.


offvalue => Integer

Specifies value to store in the button's associated variable whenever this button is deselected. Defaults to 0.

5 onvalue => Integer

Specifies value to store in the button's associated variable whenever this button is selected. Defaults to 1.


selectcolor => String

Specifies a background color to use when the button is selected. If indicatoron is true, then the color applies to the indicator. If indicatoron is false, this color is used as the background for the entire widget, in place of background or activebackground, whenever the widget is selected.


selectimage => Image

Specifies an image to display (in place of the image option) when the checkbutton is selected. This option is ignored unless the image option has been specified.


state => String

Specifies one of three states for the button: normal, active, or disabled. In normal state the button is displayed using the foreground and background options. The active state is typically used when the pointer is over the button. In active state the button is displayed using the activeforeground and activebackground options. Disabled state means that the button should be insensitive.


variable => Variable

Specifies name of global variable to set to indicate whether or not this button is selected. Defaults to the name of the button within its parent.


width => Integer

Specifies a desired width for the button.

Event Bindings

Ruby/Tk automatically creates class bindings for checkbuttons that give them the following default behavior −

  • A checkbutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the checkbutton.

  • When mouse button 1 is pressed over a checkbutton it is invoked (its selection state toggles and the command associated with the button is invoked, if there is one).

  • When a checkbutton has the input focus, the space key causes the checkbutton to be invoked.

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


require 'tk'

root =
root.title = "Window"

CkhButton1 = do
   text "Orange"
   indicatoron "true"
   background  "red"
   relief "groove"
   height 2
   width 2
   onvalue 'Orange'
   place('height' => 25,'width'  => 100, 'x' => 10, 'y'=> 10)
   command (select)

CkhButton2 = do
   text "Banana"
   background  "red"
   relief "groove"
   height 2
   width 2
   onvalue 'Banana'
   place('height' => 25,'width' => 100, 'x' => 10, 'y'=> 40)

This will produce the following result −

Ruby/Tk Checkbox