Author:         Csaba Nemethi <csaba.nemethi@t-online.de>
 State:          Final
 Type:           Project
 Tcl-Version:    9.1
 Vote:           Done
 Created:        28-Aug-2025
 Keywords:       toggleswitch, widget, Tk
 Tk-Branch:      toggleswitch
 Vote-Summary:   Accepted 9/0/0
 Votes-For:      HO, KW, SL, APN, DKF, RA, AK, MC, JN
 Votes-Against:  none
 Votes-Present:  none

Abstract

This TIP proposes to add a ttk::toggleswitch widget to the core, reusing parts of the tsw::toggleswitch implementation of the Tsw package by the author.

Rationale

Toggleswitch widgets, as replacements for checkbuttons in many situations, have become quite common and wide-spread on all platforms and desktops, including the tablets and smartphones. This was the main motivation for the author to develop the Tsw package, which implements a toggleswitch mega-widget. At the conference in Bologna we talked about the proposal made by Harald to add this widget to the Tk core after replacing the mega-widget specific parts with C code. This work is now completed, and this TIP proposes to integrate the result into Tk 9.1.

Specification

Description

A ttk::toggleswitch widget is used to show or change a binary setting. It consists of a horizontal trough (a fully rounded filled rectangle) and a slider (a filled circle contained in the trough). Their dimensions depend on the display's scaling level, the current theme, and the value of the -size configuration option.

Just like a light switch, a toggleswitch widget can have one of two possible switch states: on or off. In the on state the slider is placed at the end of the trough, and in the off state at its beginning. The user can toggle between these two states with the mouse or the space key.

The colors used when drawing the trough and the slider in the various widget states depend on the current theme. If the theme is aqua then they also depend on the system appearance (light mode or dark mode) and the accent color, and are automatically adapted whenever one of these global system settings changes.

The implementation creates these elements when needed with the aid of generic procedures for arbitrary themes and theme-specific ones for a few built-in themes. Applications can add explicit support for any theme theme by providing an appropriate command of the name ttk::toggleswitch::CreateElemements_theme.

Standard Options

-class, -cursor, -style, -takefocus.

The default value of the -class option is Toggleswitch. The value of the -style option defaults to Toggleswitch2, corresponding to the -size option's default value 2 (see below).

Widget-Specific Options

-command command

-offvalue value

-onvalue value

-size 1|2|3

-variable variable

The default value of the -size option is 2. In the case of the aqua theme, the size IDs 1, 2, and 3 correspond to the control sizes "mini", "small", and "large" of the native toggle switches on macOS.

By setting the -size option to a value size, the -style option's value will automatically change to (prefix.)Toggleswitchsize. Conversely, by setting the -style option to (prefix.)Toggleswitchsize, the -size option will automatically be set to size. The -size option takes precedence over -style. See the manual for a more detailed description.

Widget Command

Standard subcommands: cget, configure, identify element, instate, state, style.

Additional subcommands:

pathName switchstate ?boolean?

pathName toggle

Internal Commands

The following subcommands are used internally by the Toggleswitch widget class bindings:

pathName get ?min|max|x?

pathName set value

pathName xcoord ?value?

Default Bindings

The default bindings of the Toggleswitch widget class take into account that the behavior of the native toggleswitch widgets on macOS Aqua is slightly different from that of the native toggleswitches on Linux and Windows. For example, the smooth slider movements are specific to the aqua theme. See the manual for details.

Reference Implementation

A ready-to-use reference implementation can be found in the Tk branch toggleswitch. Besides the complete implementation of the ttk::toggleswitch widget, it contains the manual page toggleswitch.n, a file tests/ttk/toggleswitch.test, and a new version of the Widget Demo script ttkbut.tcl, in which the ttk::checkbutton displaying the text "Enabled" is replaced with a ttk::toggleswitch widget.

Copyright

This document has been placed in the public domain.