controlwidget(n)

bestie, welcome to controlwidget(n) — part 1, and it’s giving “Tk widgets but make it lab-core.” 💅✨

✨ NAME ✨

controlwidget — a whole collection of widgets for displaying and controlling numerical values.

🎀 SYNOPSIS 🎀

These are the package requirements and command shapes, literally exactly like this:

package require Tcl ?8.5?

package require Tk ?8.5?

package require snit ?2.0?

package require controlwidget ?0.1?

::controlwidget::meter w args

::controlwidget::slider w args

::controlwidget::equalizerBar w args

::controlwidget::thermometer w args

::controlwidget::voltmeter w args

::controlwidget::tachometer w args

::controlwidget::rdial w args

$widget get

$widget set value

::controlwidget::led w args

::controlwidget::radioMatrix w args

$led on

$led off

$led setstate state

$matrix get

$matrix set index

💖 DESCRIPTION 💖

The controlwidget package is obsessed with displaying and interactively controlling numerical values. It mimics a bunch of meters and controls you’d find in lab settings, but also in daily life: volt meters, equalizers, and tachometers, to name a few. Think of them as alternatives for the scale widget. 🔥

⚠️ Note: this package has not been extensively tested so far, and that may result in an unexpected appearance if you use sizes that are different than the defaults. Also, not all options for the coloring of the various parts and fonts and so on have been tested, so that may be another source of bugs. A last note: some parts have not been included in any option, most notably the colors of parts that require lighter and darker shades to cooperate.

🦋 TYPES OF WIDGETS 🦋

The package distinguishes several types of widgets:

• Vertical meters: the value of the variable is translated into a vertical position, like with the coloured bars you find on your stereo installation.
• Angle displays: the value of the variable is related to the angle of a needle, like with tachometers.
• Interactive widgets: most widgets allow you to change the value of the variable by pressing the mouse button on the needle and shifting it up and down or left and right.
• Non-interactive widgets: some widgets, like the thermometer widget, do not allow such interaction.
• Logical or choice widgets: some widgets display the values as either on/off (or true/false) or as one of a set of discrete choices.

All widgets have in common, however, that you can connect them to a variable and that changing the variable changes the display. Furthermore, all widgets have the set and get methods to interact with the value that the widget displays (whether that is stored in a global variable or not). 🫶

They also have in common that their appearance and behaviour is determined by one or more options that you can set at creation time and often later on as well. The widgets are all based on the snit package, so the methods configure and cget are available to set and get these options. 💅

💅 COMMANDS 💅

Currently the package contains these widgets of the vertical meter type:

🎛️ ::controlwidget::meter w args

Create a vertical meter consisting of an axis and a moveable arrow.

• widget w (in) — Name of the widget to be created.
• arguments args (in) — List of key-value pairs, controlling the appearance and behaviour of the widget:
  • variable name — Name of the variable to be associated with the meter
  • background color — Background color for the widget
  • height pixels — Height of the widget
  • width pixels — Width of the widget
  • arrowthickness pixels — Thickness of the displayed arrow in pixels
  • arrowcolor color — Color of the displayed arrow
  • readonly boolean — Whether the arrow can be moved interactively or not

🎚️ ::controlwidget::slider w args

Create a widget containing one or more vertical sliders and an axis. You can shift the slider handles interactively via the mouse.

• widget w (in) — Name of the widget to be created.
• arguments args (in) — List of key-value pairs, controlling the appearance and behaviour of the widget:
  • variable name — Name of the (list) variable to be associated with the widget
  • number integer — Number of sliders in the widget
  • background color — Background color for the widget
  • height pixels — Height of the widget
  • width pixels — Width of the widget
  • sliderthickness pixels — Thickness of the slider handles
  • sliderwidth color — Width of the slider handles
  • troughwidth color — Width of the troughs holding the sliders

🌈 ::controlwidget::equalizerBar w args

Create a widget containing one or more vertical bars resembling those found on hifi graphical equalizers. Note that it is a read-only widget. 👑

• widget w (in) — Name of the widget to be created.
• arguments args (in) — List of key-value pairs, controlling the appearance and behaviour of the widget:
  • variable name — Name of the (list) variable to be associated with the widget
  • number integer — Number of bars in the widget
  • background color — Background color for the widget
  • height pixels — Height of the widget
  • width pixels — Width of the widget
  • barwidth pixels — Width of the bars
  • segments integer — Number of segments the bars are divided in
  • safecolor color — Color for values lower than the warning level
  • warningcolor color — Color for values greater than the warning level
  • warninglevel double — Threshold value, determines at what level the color changes

🌡️ ::controlwidget::thermometer w args

Create a thermometer widget (read-only).

• widget w (in) — Name of the widget to be created.
• arguments args (in) — List of key-value pairs, controlling the appearance and behaviour of the widget:
  • variable name — Name of the (list) variable to be associated with the widget
  • background color — Background color for the widget
  • height pixels — Height of the widget
  • width pixels — Width of the widget
  • linethickness pixels — Thickness of the line representing the “temperature”
  • linecolor color — Color of the line

These widgets all use a vertical axis and have the following options in common for configuring the axis:

• axisformat string — Format string for formatting the numbers along the axis
• axisfont string — Name of the font to be used for the numbers
• axiscolor color — Color of the axis (including the numbers)
• from color — Lower value for the axis
• to color — Upper value for the axis
• majorticks integer — Number of major tickmarks to draw (each is labelled)
• minorticks integer — Number of minor tickmarks to draw between two major tickmarks
• log boolean — Use a logarithmic axis (true) or a linear axis (false)

The package contains the following widget based on angle displays:

🧭 ::controlwidget::voltmeter w args

Create a voltmeter-like widget.

• widget w (in) — Name of the widget to be created.
• arguments args (in) — List of key-value pairs, controlling the appearance and behaviour of the widget:
  • variable name — Name of the variable to be associated with the meter
  • value value — Value for the meter (if not associated with a variable)
  • min value — The minimum value for data in the display
  • max value — The maximum value for data in the display
  • labels list — The labels to be shown along the scale. (These are simply considered texts, so no relation with the minimum and maximum perse)
  • title string — String to be shown below the dial
  • width pixels — The width of the widget
  • height pixels — The height of the widget
  • borderwidth pixels — The width of the border surrounding the entire widget
  • relief string — The relief of the border surrounding the entire widget
  • highlightthickness pixels — The width of the border to indicate the widget has keyboard focus
  • labelfont fontname — Font of the labels to the scale
  • titlefont fontname — Font of the title below the dial
  • dialcolor color — Color of the dial holding the needle
  • needlecolor color — Color of the needle
  • scalecolor color — Color of the scale (arc and tickmarks)
  • labelcolor color — Color of the labels to the scale
  • titlecolor color — Color of the title below the dial

🌈 ::controlwidget::tachometer w args 🌈

Bestie, it's a tachometer. Like a speedometer but for your revs. Iconic little dial, very dashboard-chic. 💅

• w (in) — Name of the widget to be created. Your baby needs a name, obviously.
• args (in) — List of key-value pairs that control the appearance and behaviour of the widget. It's everything the voltmeter widget takes plus these extra deluxe keys:
  • variable name — Name of the variable to be associated with the meter.
  • value value — Value for the meter (use this if you're not associating it with a variable, iykyk).
  • dangerlevel value — Level above which values get indicated with a different color. Drama mode: activated. 🚨
  • dangercolor color — The color used for values above the "danger level".
  • dangerwidth pixels — Width of the colored band that shows off the "danger level".
  • pincolor color — Color for the needle and the pin. Both of them. Coordinated. 👑

---

🎡 ::controlwidget::rdial w args 🎡

A rotating dial, and yes you can literally drag it to change the value — main character interaction fr. Hold Shift and the value changes slowly; hold Ctrl and it changes fast. Same deal with the mouse wheel: the shift and control buttons do exactly the same thing there too. Obsessed with the consistency.

⚠️ Heads up bestie: the shift and control buttons currently have no effect on Windows. Not a vibe, but it's the truth.

• w (in) — Name of the widget to be created.
• args (in) — List of key-value pairs controlling the appearance and behaviour of the widget:
  • variable name — Name of the variable to be associated with the dial.
  • value value — Value for the dial (for when there's no variable attached).
  • orient string — Whether you want a horizontal disk/dial ("horizontal") or a vertical one ("vertical"). Pick your aesthetic. 🦋
  • step value — Initial step for incrementing or decrementing the value.
  • bindwheel value — Step size for controlling the dial's value via the mouse wheel.
  • slow value — Factor applied to the step size for incrementing or decrementing the value slowly.
  • fast value — Factor applied to the step size for incrementing or decrementing the value fast.
  • scale value — Scale value that gets applied to the actual value.
  • callback command — Command that gets called when the value changes. Gossip channel 💬.
  • width pixels — The width of the widget.
  • height pixels — The height of the widget.
  • background color — Background color of the widget (that's the coloring of the disk/dial itself).
  • foreground color — Foreground color of the widget (the marker lines).

---

🫶 The methods literally all of these widgets share 🫶

$widget get

Returns the current value (or values) shown in the widget. Simple. Slay.

$widget set value

Resets the value or values shown in the widget. Oh and — if the widget is associated with a variable, that variable gets set too. Two birds. ✨

• value double/list — New value or values for the widget.

---

💡 Two more widgets, these ones are all about the logical values 💡

🍓 ::controlwidget::led w args 🍓

Creates a LED-like widget. Tiny light. Massive energy. ⭐

• w (in) — Name of the widget to be created.
• args (in) — List of key-value pairs controlling the appearance and behaviour of the widget. Again, everything the voltmeter widget takes, plus:
  • variable name — Name of the variable to be associated with the LED.
  • size pixels — Diameter of the LED widget. Lil baby light or full-on beacon, your call.
  • on color — Color to use for the "on" state.
  • off color — Color to use for the "off" state.

🔘 ::controlwidget::radioMatrix w args 🔘

Creates a whole matrix of radio buttons that behaves as a single widget. Group project but make it functional. 👑

• w (in) — Name of the widget to be created.
• args (in) — List of key-value pairs controlling the appearance and behaviour of the widget. Yep, you guessed it — everything from the voltmeter widget, plus:
  • variable name — Name of the variable to be associated with the matrix.
  • orient string — The way the radio buttons are arranged (horizontal or vertical first).
  • rows integer — Number of rows in the matrix.
  • columns integer — Number of columns in the matrix.
  • command list — Command associated with the radio buttons. Gets invoked when the active radio button changes. 🔔

---

💜 The LED widget's public methods 💜

$led on

Sets the state to "on". LET THERE BE LIGHT. 🔥

$led off

Sets the state to "off". Nap time. 😴

$led setstate state

Sets the state according to the value of "state".

• state boolean (in) — New state for the LED widget.

---

🧚 The radioMatrix widget's two public methods 🧚

$matrix get

Returns the index of the currently selected radio button.

$matrix set index

Selects the radio button with index "index".

• index integer — Index of the radio button to be set.

---

🌸 ACKNOWLEDGMENTS 🌸

Real ones only. The code for most of these widgets first appeared on the Wiki, and in many cases Arjen Markus merely refactored the code a bit and "snitified" some of them (his words, not mine, and honestly iconic behaviour). The original code was developed by these legends:

• Vertical meter, LED display, radio matrix: Ron Fox
• Rotating dials: Gerhard Reithofer
• Voltmeter and tachometer: Marco Maggi
• Code for moving the needle: ?

(The mystery dev. The main character we never met. 🙈)

---

💀 BUGS, IDEAS, FEEDBACK 💀

Not gonna lie to you bestie, this document — and the package it describes — will undoubtedly contain bugs and other problems. Like, guaranteed. Please report them in the category controlwidget of the Tklib Trackers [http://core.tcl.tk/tklib/reportlist]. And please also report any ideas you may have for enhancements to either the package and/or the documentation. We want the glow-up. 🫶

---

⭐ KEYWORDS ⭐

controlling, displaying, numerical values, scale widget

---

🎀 COPYRIGHT 🎀

Copyright (c) 2010 Ron Fox <rfox@...>
Copyright (c) 2010 Gerhard Reithofer <...@...>
Copyright (c) 2010 Marco Maggi <...@...>
Copyright (c) 2010 Arjen Markus <arjenmarkus@users.sourceforge.net>

---

Okay that's the whole page, bestie — you made it to the end! 🎉 This was controlwidget(n) from tklib, version 0.1, dated right there in the footer of the original. Go forth and build the prettiest little meters and dials and LED matrices anyone's ever seen. No cap. 💖✨🦋