ttk::toggleswitch(n)

📦 version 9.1.0, in nixpkgs unstable

🌈 ttk::toggleswitch(n) — Tk Themed Widget 🌈

okay bestie, we are officially in toggleswitch territory, and it's giving main-character widget energy. 💅

🌸 NAME 🌸

ttk::toggleswitch — create and manipulate a toggleswitch widget. That's the name, that's the job, and it ate. ✨

✨ SYNOPSIS ✨

ttk::toggleswitch pathName ?options...?

🦋 DESCRIPTION 🦋

okay so a ttk::toggleswitch widget is used to show or change a binary setting. In its simplest form it consists of a horizontal trough — a fully rounded filled rectangle — and a slider, which is a filled circle or a fully rounded filled rectangle contained in the trough. Their dimensions depend on the value of the -size configuration option, the current theme, the display's scaling level, and Tk's scaling factor given by [tk scaling] at the time the first toggleswitch widget is created. The widget may also contain an optional text element, displayed to the trough's left. text element on the left? cute, noted. 🎀

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. literally light-switch behavior, no cap. 🔥

The colors used when drawing the trough and 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. adaptive color slay. 🌈

The implementation creates these elements when needed with the aid of generic code for arbitrary themes and theme-specific one 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::CreateElements_theme. iykyk, that's the customization hook. 🪄

👑 STANDARD OPTIONS 👑

These are the standard option besties:

  • -class
  • -cursor
  • -style
  • -takefocus
  • -text
  • -textvariable
  • -underline
  • -width

See the ttk_widget manual entry for details on the standard options. go check that one for the full standard-option lore. 📚

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. Depending on the value of the -size option, in case of a toggleswitch without a text element the standard -style value is one of Toggleswitch1, Toggleswitch2, or Toggleswitch3, while in case of a toggleswitch containing a text element it is one of ToggleswitchEx1, ToggleswitchEx2, or ToggleswitchEx3 (see below). style mapping? she's organized. 💖

🎀 WIDGET-SPECIFIC OPTIONS 🎀

  • -command — Command-Line Name: -command; Database Name: command; Database Class: Command.

Specifies a Tcl script to be evaluated at global scope whenever the switch state of the widget is toggled (programmatically, by invoking the switchstate or toggle subcommand, or interactively). The default is an empty string. so if you want a lil side quest on every toggle, this is your girl. 🫶

  • -offvalue — Command-Line Name: -offvalue; Database Name: offValue; Database Class: OffValue.

The value to store in the associated -variable when the widget's switch state is set to off. Defaults to 0. yes bestie, off means zero by default. 💀

  • -onvalue — Command-Line Name: -onvalue; Database Name: onValue; Database Class: OnValue.

The value to store in the associated -variable when the widget's switch state is set to on. Defaults to 1. on equals one, iconic. ⭐

  • -size — Command-Line Name: -size; Database Name: size; Database Class: Size.

Specifies the size identifier of the toggleswitch widget. The supported values are the strings 1, 2 (the default), and 3. In the case of the aqua theme, these size IDs correspond to the control sizes "mini", "small", and "large" of the native toggle switches on macOS. macOS representation is shaking, but okay. 🍓

Note that by setting this option to a value size, the -style option's value will automatically change to Toggleswitchsize or ToggleswitchExsize if its previous or requested value was one of Toggleswitch1, Toggleswitch2, Toggleswitch3, ToggleswitchEx1, ToggleswitchEx2, or ToggleswitchEx3. Similarly, the value of the -style option will automatically change to prefix.Toggleswitchsize or prefix.ToggleswitchExsize if its previous or requested value was one of prefix.Toggleswitch1, prefix.Toggleswitch2, prefix.Toggleswitch3, prefix.ToggleswitchEx1, prefix.ToggleswitchEx2, or prefix.ToggleswitchEx3. (size here is the size value, bestie — it's the Toggleswitch name with the size stuck on the end.)

Conversely, by setting the -style option to a value of one of the forms Toggleswitchsize, ToggleswitchExsize, prefix.Toggleswitchsize, or prefix.ToggleswitchExsize (where size is one of 1, 2, or 3), the -size option will automatically be set to size. automatic back-and-forth, love that for them. 🔁

When configuring both options -size and -style, the former will take precedence over the latter, regardless of the order in which they were specified. For example, if you create the widget with

ttk::toggleswitch pathName -size 3 -style My.Toggleswitch3

or invoke

pathName configure -style My.Toggleswitch3

then the -style option will be set to My.Toggleswitch3 (and the -size option will have the value 3). On the other hand, if you create the widget with

ttk::toggleswitch pathName -style My.Toggleswitch3

then the -style option will have the value My.Toggleswitch2 rather than My.Toggleswitch3, because the widget creation triggers the default -size 2 setting, which takes precedence over -style My.Toggleswitch3. yeah, the -size precedence ate, periodt. 👑

  • -variable — Command-Line Name: -variable; Database Name: variable; Database Class: Variable.

The name of a global variable whose value is linked to the toggleswitch. The widget's switch state changes to on when this variable is set to the value specified by the -onvalue option and to off otherwise. Defaults to the widget's pathname if not specified.

Note: just like in the case of the (ttk::)checkbutton, toggling the widget's switch state by changing the value of this variable will not cause the script specified by the -command option to get executed. no cap, it's a whole thing. 📌

💅 WIDGET COMMAND 💅

In addition to the standard cget, configure, identify element, instate, state, and style commands (see ttk::widget), toggleswitch widgets support the following additional commands:

🎚️ pathName switchstate ?boolean?

Modifies or inquires the widget's switch state. If the optional argument is present then it must be a boolean (a numeric value, where 0 is false and anything else is true, or a string such as true/yes/on or false/no/off). If the widget's disabled state flag is set then the command returns an empty string immediately after checking the argument. otherwise? we continue. 👀

Otherwise, if the argument is true then the command sets the widget's switch state to on by setting its selected flag, moving the slider to the end of the trough, and setting the associated -variable to the value specified by the -onvalue option; if the argument is false then the command sets the widget's switch state to off by clearing the selected flag, moving the slider to the beginning of the trough, and setting the associated variable to the value specified by the -offvalue option. whole little routine, very cutesy. ✨

If the argument's value causes the widget's switch state to get toggled and the script specified as the value of the -command option is a nonempty string then the command evaluates that script at global scope and returns its result; otherwise the return value is an empty string. 🫧

If the optional argument is not present then the command returns the widget's current switch state as 0 (off) or 1 (on). When a toggleswitch widget is created, its switch state is initialized with 0. starting off, literally. 💤

🔁 pathName toggle

This convenience subcommand toggles the widget's switch state. It is logically equivalent to invoking the switchstate command with the argument 0 if the current switch state is on and with the argument 1 otherwise. flip it and reverse it, that's the whole subcommand. 🦋

🧚 INTERNAL COMMANDS 🧚

The following widget commands are used internally by the Toggleswitch widget class bindings. They provide a means to access the widget's internal value, which is a real number within a certain invariant interval. internal-value lore, stay with me. 🔍

🌸 pathName get ?min|max|x?

Returns the current/minimum/maximum internal value, or the one corresponding to the coordinate x relative to the widget origin if it is specified. yes, min, max, and x are all in the group chat. 💬

🎀 pathName set value

Sets the widget's internal value to value. The value will be clipped to the range given by the minimum and maximum values, as returned by get min and get max. clipped, bestie — not on her watch. ✂️

🦋 pathName xcoord ?value?

Returns the x coordinate corresponding to value, or to the current internal value if value is omitted. x marks the spot. 📍

🔥 DEFAULT BINDINGS 🔥

The toggleswitch widget's default bindings enable the following behavior.

💖 If the current theme is aqua

  • By pressing mouse button 1 over the slider and then dragging the mouse with button 1 down until the pointer enters the trough, the slider moves smoothly to the opposite edge of the trough and the widget's switch state gets toggled. The same happens if mouse button 1 is pressed outside the slider and then the pointer leaves the widget horizontally with button 1 down. smooth little slide, very demure. 💅
  • By pressing mouse button 1 anywhere within the widget and then releasing it over the widget without previously moving the slider, the latter moves smoothly to the opposite edge of the trough and the widget's switch state gets toggled. click-and-release ate. 🫶
  • When the widget has the input focus, the space key causes its switch state to get toggled. keyboard girlies, this one's for you. ⌨️

🌈 If the current theme is different from aqua

  • By pressing mouse button 1 anywhere within the widget and then dragging the mouse with button 1 down, the slider moves in the same (horizontal) direction as the pointer. By releasing the button, the switch state is set to off or on, depending on the slider's position relative to the middle of the widget. drag direction matching, slay. ➡️
  • By pressing mouse button 1 anywhere within the widget and then releasing it over the widget without previously dragging the mouse horizontally, the widget's switch state gets toggled. tiny click, big toggle energy. ✨
  • When the widget has the input focus, the space key causes its switch state to get toggled. space key stays iconic. ⭐
If the widget's disabled state flag is set then none of the above actions occur. literally none, bestie. 💀

💅 WIDGET STATES

Okay so the state situation is lowkey important, listen up:

  • The widget sets the selected state whenever the switch state changes to on, and clears it otherwise. So like, on = selected, off = not selected. Simple. Iconic. ✨
  • The widget sets the invalid state whenever the linked -variable is unset. (Yes, unset — not "set to something weird". Unset. Got it? 🫶)
  • The default bindings set and clear the active and pressed state flags. That's the hover-and-click drama you see visually. 💅

🎀 STYLING OPTIONS

The default class name for a ttk::toggleswitch is Toggleswitch. Remember that, you'll need it for your style calls, iykyk.

Dynamic states: active, background, disabled, invalid, pressed, selected.

These are the styling options you can configure with ttk::style for Toggleswitch1, Toggleswitch2, Toggleswitch3, ToggleswitchEx1, ToggleswitchEx2, and ToggleswitchEx3:

  • -background color, -focuscolor color — for both of these options, the default is theme-specific. So don't come for me, ask your theme. 😌
  • -focussolid boolean — defaults to true for the classic theme and false for all the others. fr fr, classic is the odd one out here.
  • -focusthickness amount — the default is 1. The value may have any of the forms acceptable to Tk_GetPixels. 🎯
  • -font font — for ToggleswitchEx? only. The default is TkDefaultFont.
  • -foreground color — for ToggleswitchEx? only. The default is theme-specific.
  • -padding padding — defaults to 1.5p for the aqua theme (and for aqua, the three above-mentioned styles have no focus element, jsyk) and 0.75p for all the other themes.
For the aqua theme the focus-related options are simply ignored. Like, not an error, not a warning — just ignored. Don't fight it bestie, aqua does its own thing. 💀

See the ttk_style manual page for information on how to configure ttk styles. That's your homework, go read it. 📚

🦋 SEE ALSO

All the cousins of this widget basically. Go say hi. 👋

⭐ KEYWORDS

toggleswitch, trough, slider, widget

And that's the whole vibe check on ttk::toggleswitch(n), bestie — written for Tk 9.1, slayed and delivered with love. 💖 Go make something toggle, you absolute main character. ✨🎀🦋

📦 where this page comes from