scustomtkinter 0.2.1__py3-none-any.whl

scustomtkinter/sctk_dial.py

@@ -0,0 +1,1472 @@
+#!/usr/bin/python3
+"""
+sCTkDial
+
+Centralized Foundable Base Class for Theme-Adaptive Rotary Encoders.
+Coordinates 3D knob geometry structures, vector math layers, and hardware delta masks.
+"""
+import sys
+import math
+import time
+import customtkinter as ctk
+from . import themeable_widget as _tw
+from .themeable_widget import ThemeableWidget, parse_list_property, defer
+class sCTKDialBase(ctk.CTkFrame, ThemeableWidget):
+    """Abstract Base Class for theme-adaptive mechanical rotary encoder widgets."""
+
+    # Stops ScrollBindingMixin's descendant walk here, so an enclosing
+    # scrollable frame does not bind this widget's canvas to its own handler.
+    #
+    # FIX: without it, a dial placed inside an sCTkScrollableFrame scrolled the
+    # LIST when the pointer was over the knob -- the enclosing frame binds every
+    # descendant it finds with add="+", and its handler fires first. Pointing at
+    # a VFO knob and turning the wheel should turn the knob.
+    _CONSUMES_SCROLL = True
+
+    def __init__(self, master=None, divisions=24, state="normal", width=120, height=120, **kw):
+        # Pulled out BEFORE the theme pass, so it is not merged into final_kw
+        # and forwarded to the native constructor, which would reject it.
+        # None means "use the theme's label_font".
+        self._label_font_override = kw.pop("label_font", None)
+
+        # Same reason: these are this widget's own, not CTkFrame options.
+        # Parsed rather than bool()'d: the Designer passes strings, and
+        # bool("False") is True -- which would have made every dial placed in
+        # the Designer latch whatever the dropdown said.
+        def _as_bool(v, default=False):
+            if v is None:
+                return default
+            if isinstance(v, str):
+                return v.strip().lower() in ("true", "1", "yes", "on")
+            return bool(v)
+
+        _pressed_init = _as_bool(kw.pop("pressed", False))
+        _latching_init = _as_bool(kw.pop("latching", False))
+        _dbl_init = kw.pop("double_click_command", None)
+        _sdbl_init = kw.pop("shift_double_click_command", None)
+
+        ThemeableWidget.__init__(self, kw)
+        # THEME SOURCE -- read the RAW block, not final_kw.
+        #
+        # ThemeableWidget maintains a CUSTOM_VECTOR_KEYS set (dial_color,
+        # shadow_color, text_color, pointer_color, pointer_glow_color,
+        # diameter, ...) which it deliberately strips out of final_kw for
+        # vector widgets like this one, so they never reach the native
+        # CTkFrame constructor and raise ValueError. That stripping is
+        # correct. What was wrong was reading colours back out of final_kw
+        # afterwards: those keys were never in there.
+        #
+        # FIX: every `.get(key) or ("#hex", "#hex")` in the old draw code was
+        # therefore ALWAYS taking the hardcoded fallback -- this widget family
+        # has never rendered its configured theme colours at all. The values
+        # in sCTkThemes.json for dial_color, shadow_color, text_color and
+        # pointer_glow_color were decorative. Surfaced by _validate_theme_keys()
+        # the first time fail-loud checking was applied here.
+        #
+        # Module-attribute access rather than a direct name import, because
+        # load_initial_framework_themes() REBINDS GLOBAL_THEME_REGISTRY on
+        # load; a `from ... import GLOBAL_THEME_REGISTRY` would capture the
+        # empty dict that existed at import time.
+        # _THEME_BLOCK_NAME, not the class name.
+        #
+        # This resolved the block from self.__class__.__name__ directly,
+        # bypassing the override ThemeableWidget uses everywhere else -- so a
+        # subclass got an empty block and fail-loud validation raised:
+        #
+        #   KeyError: "'sCTkDialContinuousForPreview' theme block is missing
+        #   'text_color' at the top level of sCTkThemes.json."
+        #
+        # naming a block that neither exists nor should. Hit by the Designer's
+        # preview subclasses, and by any user subclass of a dial.
+        raw_block = _tw.GLOBAL_THEME_REGISTRY.get(self._theme_block()) or {}
+        raw_colors = {k: v for k, v in raw_block.items() if not isinstance(v, dict)}
+        self._local_defaults = ThemeableWidget._convert_lists_to_tuples(raw_colors)
+        # final_kw still wins where it has a value, so constructor overrides
+        # and non-vector theme keys keep their existing precedence.
+        self._local_defaults.update(self.final_kw)
+
+        self._custom_disabled_map = dict(self._widget_disabled_map)
+        # pressed_map is already resolved by ThemeableWidget for every widget,
+        # so this needs nothing added there.
+        self._custom_pressed_map = dict(self._widget_pressed_map)
+        self._validate_theme_keys()
+
+        # knob_diameter names the KNOB. width and height name the CANVAS.
+        #
+        # It previously set both canvas dimensions to its own value, so a
+        # "diameter" of 300 produced a 300px WIDGET with a 244px knob inside
+        # it -- the name described neither. Renamed and separated: the knob is
+        # drawn at exactly this size, and the canvas defaults to leaving room
+        # for labels around it.
+        target_knob = self._local_defaults.get("knob_diameter")
+        self._knob_diameter = int(target_knob) if target_knob is not None else 120
+        width, height = self._default_canvas_size(width, height)
+
+        FRAME_VALID_KEYS = {"width", "height", "fg_color", "border_color", "border_width", "corner_radius", "bg_color"}
+        frame_kwargs = {k: self._local_defaults[k] for k in FRAME_VALID_KEYS if k in self._local_defaults and self._local_defaults[k] is not None}
+        frame_kwargs.setdefault("width", width)
+        frame_kwargs.setdefault("height", height)
+        frame_kwargs.setdefault("fg_color", "transparent")
+
+        super().__init__(master, **frame_kwargs)
+
+        self._divisions = int(divisions) if int(divisions) > 0 else 24
+        self._state = "normal" if state.lower() == "normal" else "disabled"
+
+        # LATCHING IS OPT-IN, and off by default.
+        #
+        # With latching=False -- the default -- a dial behaves exactly as it
+        # always has: always live, top-level colours, pressed_map ignored and
+        # not required. That matters because an armed/inert rotary control is
+        # an unusual pattern: someone reaching for sCTkDialRange as a volume
+        # knob would find it inert with nothing on screen to say why.
+        #
+        # With latching=True the dial starts switched off and ignores clicks,
+        # drags and the wheel until set_pressed(True). pressed_map then
+        # supplies the operational colours and the top-level block is the
+        # resting, dimmed look.
+        #
+        # Named for the mute or lock button it behaves like: pressed and it
+        # stays pressed. The button family's own pressed_map is momentary --
+        # a different meaning in a different block.
+        self._latching = _latching_init
+        self._pressed = _pressed_init if _latching_init else False
+
+        # Double-click is a PLAIN CALLBACK, not wired to the latch.
+        #
+        # Toggling on double-click is one use and a natural one, but it is the
+        # application's decision rather than the widget's -- see the example in
+        # sCTkDial.md, which wires exactly that. Called with the dial itself,
+        # so a handler can act on it without a closure over the name.
+        self._double_click_command = _dbl_init
+
+        # A SECOND double-click callback, on Shift.
+        #
+        # Every mouse button steps the dial, so a plain double-click competes
+        # with ordinary use: clicking left repeatedly to turn the knob trips it
+        # sooner or later. That only matters in one direction -- while the dial
+        # is switched off nothing is bound, so arming by double-click is always
+        # safe. It is DISARMING that collides.
+        #
+        # Shift is already the drag modifier, but a shift-double-click only
+        # fires <Shift-ButtonPress-1> twice, which records a drag origin and
+        # nothing else. So the gesture is free.
+        #
+        # The widget still decides nothing about meaning. The convention the
+        # examples follow is arm on double-click, disarm on shift-double-click.
+        self._shift_double_click_command = _sdbl_init
+        self._current_value = 0
+        self._scroll_cooldown_seconds = 0.060
+        self._last_scroll_time = 0.0
+        self._last_y = 0
+
+        self.canvas = ctk.CTkCanvas(self, highlightthickness=0, bd=0)
+        self.canvas.pack(fill="both", expand=True)
+        self.pack_propagate(False)
+        self.grid_propagate(False)
+
+        self.canvas.bind("<Enter>", lambda e: self._on_mouse_enter())
+        # Interactive bindings are NOT installed unconditionally any more --
+        # a dial starts switched off and must be inert until double-clicked.
+        # _apply_input_bindings() installs whatever the current state calls
+        # for, including the double-click that switches it on.
+        self.canvas.bind("<Shift-ButtonPress-1>", self._on_button_press)
+        self.canvas.bind("<Shift-B1-Motion>", self._on_button_motion)
+        self._apply_input_bindings()
+        self.canvas.bind("<Configure>", lambda e: self._draw_dial_base())
+        defer(self, 50, self._inject_private_layer_bindings)
+
+    # Keys every dial reads, required at the TOP LEVEL of its theme block.
+    _REQUIRED_THEME_KEYS = (
+        "fg_color", "text_color", "shadow_color", "dial_color",
+        "dial_highlight_color", "dial_shadow_color",
+        "dial_rim_light_color", "dial_rim_shadow_color",
+    )
+
+    # Keys required inside disabled_map. Deliberately excludes fg_color: the
+    # background does NOT dim when disabled, the knob face and text carry the
+    # signal. Matches the choice made for sCTkScrollableFrame.
+    _REQUIRED_DISABLED_KEYS = ("text_color", "dial_color")
+
+    # Required inside pressed_map -- the latched switched-on state. Same two
+    # keys as disabled_map: enough to tell the states apart at a glance,
+    # without forcing every shading key to be restated.
+    _REQUIRED_PRESSED_KEYS = ("text_color", "dial_color")
+
+    def _label_font(self):
+        """
+        The font for text drawn on the canvas.
+
+        A per-instance override set through the constructor or configure()
+        wins over the theme, so one dial can carry a different label size
+        without moving every dial in the application.
+
+        FIX: the two label-drawing variants hardcoded ("Arial", 9, "bold") in
+        their create_text() calls, while the colour on the same line was read
+        from the theme -- a partial job, and one the theme file had no way to
+        reach. Same pattern as the eight hardcoded fonts found in the S-meters.
+
+        Read from _local_defaults, which this widget builds from the RAW theme
+        registry block rather than from final_kw -- see __init__. That matters
+        for the same reason the dial colours do: keys this library adds are
+        stripped out of final_kw before the native constructor sees them, so a
+        widget reading them from there gets nothing.
+
+        Returns:
+            The tuple from the theme block.
+        """
+        font = (getattr(self, "_label_font_override", None)
+                or self._local_defaults.get("label_font"))
+
+        # Drop an empty style before it reaches the canvas. Tk rejects one --
+        # unknown font style "" -- and the Designer's font editor produces
+        # exactly that for a family with no style selected, as the literal
+        # "{}". Guarded here as well as in the builder object because a font
+        # can arrive from application code too.
+        if isinstance(font, (tuple, list)) and len(font) >= 3:
+            styles = [s for s in font[2:]
+                      if s and str(s).strip() not in ("", "{}")]
+            font = (font[0], font[1], *styles) if styles else (font[0], font[1])
+        return font
+
+    # Room left around the knob for labels when only knob_diameter is given.
+    #
+    # 40, not the 28 the old fixed layout used. At 9pt a default Selector label
+    # like "POS 1" is around 40px wide, and anchoring puts half of that beyond
+    # the arc point -- about 20px -- on top of the gap _label_placement()
+    # leaves. 28 clipped the default labels of both Range and Selector at the
+    # canvas edge.
+    #
+    # Only applies when width and height are not given. An explicit canvas
+    # size always wins, so nothing laid out deliberately is affected.
+    DEFAULT_LABEL_MARGIN = 40
+
+    def _theme_block(self):
+        """
+        The theme block this widget reads, honouring _THEME_BLOCK_NAME.
+
+        Used for three things that all keyed off the raw class name before:
+        resolving the block, naming it in a validation error, and deciding
+        which variant's drawing code runs. A subclass -- the Designer's
+        preview classes, or a user's own -- broke all three.
+        """
+        return getattr(self, "_THEME_BLOCK_NAME", None) or self.__class__.__name__
+
+    def _default_canvas_size(self, width, height):
+        """
+        Fills in a canvas size the caller did not specify.
+
+        knob_diameter says how big the KNOB is; the canvas has to be at least
+        that plus somewhere for the labels. An explicit width or height always
+        wins -- this only supplies one where none was given, so a bare
+        knob_diameter still produces a usable dial without the caller having to
+        pass three numbers.
+
+        Labels longer or larger than the default margin allows are CLIPPED,
+        deliberately: widening the canvas is the caller's decision, and
+        shrinking the knob instead would make dials sharing a knob_diameter
+        look different from one another.
+
+        Args:
+            width: The width asked for, or the class default.
+            height: The height asked for.
+
+        Returns:
+            (width, height) to build the canvas with.
+        """
+        needed = self._knob_diameter + (2 * self.DEFAULT_LABEL_MARGIN)
+        explicit = self._local_defaults
+        if explicit.get("width") is None:
+            width = max(int(width or 0), needed)
+        if explicit.get("height") is None:
+            height = max(int(height or 0), needed)
+        return width, height
+
+    def _label_placement(self, angle_rad, knob_radius):
+        """
+        Where a label sits, and which way it grows from there.
+
+        TWO FIXES, both visible with a long label on an sCTkDialSelector:
+
+        ANCHORING. The labels were drawn CENTRED on their point, so half of
+        each one extended back toward the dial. A label on the left of the arc
+        therefore overhung the dial face, and a long one ran across it -- "Very
+        Long" intruded at any font size, and a bigger diameter did not help
+        because the offset is a fixed distance from the knob edge. Anchoring by
+        position makes a label grow AWAY from the dial: one on the left anchors
+        east, one on the right anchors west, one at the top or bottom anchors
+        to its near edge.
+
+        sCTkDialRange never showed this because its labels are numbers, one to
+        three characters, which barely overhang when centred. Same defect,
+        different content.
+
+        OFFSET SCALING. The gap was a hardcoded 18px, tuned for 9pt. Larger
+        text sat closer to the knob in proportion, and eventually touched it.
+        It now grows with the font size.
+
+        Args:
+            angle_rad: Where on the arc this label belongs.
+            knob_radius: Radius of the drawn knob.
+
+        Returns:
+            (offset, anchor) -- the distance from centre at which to place the
+            label, and the Tk anchor to place it with.
+        """
+        font = self._label_font()
+        try:
+            size = int(font[1])
+        except (TypeError, ValueError, IndexError):
+            size = 9
+
+        # 9pt keeps the original 18px gap, so existing dials are unchanged.
+        offset = knob_radius + 9 + size
+
+        cos_a, sin_a = math.cos(angle_rad), math.sin(angle_rad)
+
+        # 0.3 rather than 0: near the top and bottom of the arc a label is
+        # better anchored vertically, or a nearly-horizontal one flips side
+        # over a fraction of a degree and appears to jump.
+        if cos_a < -0.3:
+            anchor = "e"
+        elif cos_a > 0.3:
+            anchor = "w"
+        else:
+            anchor = "s" if sin_a > 0 else "n"
+
+        return offset, anchor
+
+    def _validate_theme_keys(self) -> None:
+        """
+        Hard-fails at construction on an incomplete theme block, naming the
+        missing key and where it belongs.
+
+        Replaces the previous pattern of `.get(key) or ("#hex", "#hex")`
+        throughout the draw routine, which silently substituted a plausible
+        guess whenever the theme was incomplete -- so a broken block looked
+        merely slightly-off rather than broken. Same fail-loud principle used
+        for sCTkTabview and sCTkScrollableFrame.
+
+        Subclasses extend the requirements via _EXTRA_THEME_KEYS and
+        _EXTRA_DISABLED_KEYS rather than overriding this, since each dial
+        variant reads a slightly different set: only Continuous draws a
+        dimple, and only Selector/Range draw a pointer line.
+
+        Raises:
+            KeyError: naming the first missing key found.
+        """
+        name = self._theme_block()
+        required = self._REQUIRED_THEME_KEYS + getattr(self, "_EXTRA_THEME_KEYS", ())
+        required_disabled = self._REQUIRED_DISABLED_KEYS + getattr(self, "_EXTRA_DISABLED_KEYS", ())
+
+        for key in required:
+            if self._local_defaults.get(key) is None:
+                raise KeyError(
+                    f"'{name}' theme block is missing '{key}' at the top level "
+                    f"of sCTkThemes.json."
+                )
+        for key in required_disabled:
+            if self._custom_disabled_map.get(key) is None:
+                raise KeyError(
+                    f"'{name}' theme block is missing '{key}' in disabled_map."
+                )
+        # pressed_map is only required when latching is in use. A dial that
+        # is always live never reads it, so demanding it would force the key
+        # into every theme block for a feature most dials do not use.
+        if not getattr(self, "_latching", False):
+            return
+        for key in self._REQUIRED_PRESSED_KEYS + getattr(self, "_EXTRA_PRESSED_KEYS", ()):
+            if self._custom_pressed_map.get(key) is None:
+                raise KeyError(
+                    f"'{name}' theme block is missing '{key}' in pressed_map."
+                )
+
+    # ------------------------------------------------------------------
+    # Latched "pressed" state
+    # ------------------------------------------------------------------
+    _SCROLL_EVENTS = ("<MouseWheel>", "<TouchpadScroll>", "<Button-4>",
+                      "<Button-5>", "<Shift-ButtonPress-1>", "<Shift-B1-Motion>")
+
+    def _draws_active(self) -> bool:
+        """
+        Whether to draw the operational colours.
+
+        A NON-LATCHING dial is permanently on, so it draws from pressed_map
+        like an armed one. Without this, opting out of latching changed how a
+        dial looked: the bright values live in pressed_map now, and the
+        top-level block holds the resting, dimmed set -- so a plain dial
+        rendered dim, which is not what opting out should mean.
+
+        Disabled always wins over both.
+        """
+        if str(getattr(self, "_state", "normal")).lower() == "disabled":
+            return False
+        return True if not getattr(self, "_latching", False) else self.is_pressed()
+
+    def is_pressed(self) -> bool:
+        """True when the dial is switched on and will respond to input."""
+        return bool(getattr(self, "_pressed", False))
+
+    def set_pressed(self, pressed: bool) -> bool:
+        """
+        Switches the dial on or off, repainting and re-gating input.
+
+        Off is the resting state: the dial shows its top-level theme colours
+        and ignores clicks, drags and the wheel. On shows pressed_map and
+        responds normally.
+
+        Returns:
+            The resulting value, so a caller can act on what actually happened.
+        """
+        if not self._latching:
+            # Nothing to switch: the dial is always live. Silently ignored
+            # rather than raising, so generic code that arms every dial on a
+            # panel does not have to know which ones latch.
+            return False
+        pressed = bool(pressed)
+        if pressed == self.is_pressed():
+            return pressed
+        self._pressed = pressed
+        self._apply_input_bindings()
+        self._process_theme_repaint()
+        return pressed
+
+    def toggle_pressed(self) -> bool:
+        """Flips the switched-on state. What a double-click does."""
+        return self.set_pressed(not self.is_pressed())
+
+    def _on_shift_double_click(self, event=None):
+        """
+        Fires shift_double_click_command, if one was given.
+
+        See __init__ for why disarming wants its own gesture.
+        """
+        if str(self._state).lower() == "disabled":
+            return "break"
+        if callable(self._shift_double_click_command):
+            try:
+                self._shift_double_click_command(self)
+            except Exception:
+                pass
+        return "break"
+
+    def _on_double_click(self, event=None):
+        """
+        Fires double_click_command, if one was given.
+
+        Deliberately does NOT touch the latch. Wiring a double-click to
+        toggle_pressed() is the application's choice:
+
+            dial = sCTkDialRange(parent, latching=True,
+                                 double_click_command=lambda d: d.toggle_pressed())
+
+        Returns "break" so the click does not also reach anything bound
+        further up.
+        """
+        if str(self._state).lower() == "disabled":
+            return "break"
+        if callable(self._double_click_command):
+            try:
+                self._double_click_command(self)
+            except Exception:
+                # A raising callback must not leave the binding broken for
+                # the next click.
+                pass
+        return "break"
+
+    def _apply_input_bindings(self):
+        """
+        Installs or removes the interactive bindings for the current state.
+
+        Gating here rather than guarding inside each handler: there are six
+        handlers on each of the three variants, and a missed guard would be a
+        dial that still turns while switched off. Not binding at all cannot be
+        got wrong.
+
+        The double-click binding survives while the widget is enabled -- it is
+        how the dial gets switched on in the first place.
+        """
+        if not hasattr(self, "canvas"):
+            return
+        try:
+            if not self.canvas.winfo_exists():
+                return
+        except Exception:
+            return
+
+        enabled = str(self._state).lower() != "disabled"
+        # Without latching the dial is live whenever it is enabled, which is
+        # how it has always behaved.
+        live = enabled and (self.is_pressed() if self._latching else True)
+
+        try:
+            if live:
+                self.canvas.bind("<Button-1>", self._on_left_click_step)
+                self.canvas.bind("<Button-2>", self._on_right_click_step)
+                self.canvas.bind("<Button-3>", self._on_right_click_step)
+                # The shift-drag handlers are part of the interactive set and
+                # have to come back with it. _inject_private_layer_bindings()
+                # covers only the scroll events.
+                self.canvas.bind("<Shift-ButtonPress-1>", self._on_button_press)
+                self.canvas.bind("<Shift-B1-Motion>", self._on_button_motion)
+                self._inject_private_layer_bindings()
+            else:
+                self.canvas.unbind("<Button-1>")
+                self.canvas.unbind("<Button-2>")
+                self.canvas.unbind("<Button-3>")
+                # Unbound on EVERY layer the injection binds, not just the
+                # canvas. _inject_private_layer_bindings() installs the scroll
+                # handlers on the canvas, the widget and CTkFrame's own canvas;
+                # clearing one of the three left a dial that still scrolled
+                # while switched off. The old disabled path had the same gap.
+                for _layer in (self.canvas, self, getattr(self, "_canvas", None)):
+                    if _layer is None:
+                        continue
+                    for ev in self._SCROLL_EVENTS:
+                        try:
+                            _layer.unbind(ev)
+                        except Exception:
+                            pass
+
+            # The plain double-click is NOT bound on an armed latching dial.
+            #
+            # Tk gives <Double-Button-1> precedence over the second
+            # <Button-1>, so while both are bound an accidental double-click
+            # while clicking to step the dial costs a step -- two clicks, one
+            # step. Harmless but irritating on a control you click repeatedly.
+            #
+            # On a latching dial the plain double-click means "arm", which is
+            # only ever needed while it is off. Not binding it once armed
+            # removes the collision outright rather than compensating for it.
+            # Disarming has its own gesture and stays bound throughout.
+            #
+            # A non-latching dial keeps it bound always: there
+            # double_click_command is a general-purpose callback with no
+            # arming role, and silently dropping it would be wrong.
+            if enabled and not (self._latching and self.is_pressed()):
+                self.canvas.bind("<Double-Button-1>", self._on_double_click)
+            else:
+                self.canvas.unbind("<Double-Button-1>")
+
+            if enabled:
+                self.canvas.bind("<Shift-Double-Button-1>",
+                                 self._on_shift_double_click)
+            else:
+                self.canvas.unbind("<Shift-Double-Button-1>")
+        except Exception:
+            pass
+
+    def _inject_private_layer_bindings(self):
+        """
+        Installs the scroll handlers on every layer that can receive them.
+
+        Guarded on the dial actually being live. __init__ schedules this with
+        after(50, ...), so it fires AFTER _apply_input_bindings() has decided
+        what should be bound -- and without this check it put the scroll
+        handlers back on a dial that was meant to be inert. The symptom was a
+        freshly built latching dial that still responded to the wheel, while
+        one cycled on and off behaved correctly, because by then the gating
+        had run again with nothing scheduled behind it.
+        """
+        if getattr(self, "_latching", False) and not self.is_pressed():
+            return
+        if str(getattr(self, "_state", "normal")).lower() == "disabled":
+            return
+
+        layers_to_bind = [self.canvas, self]
+        if hasattr(self, "_canvas") and self._canvas is not None:
+            layers_to_bind.append(self._canvas)
+        for target_layer in layers_to_bind:
+            if sys.platform == "darwin":
+                # GUARDED: <TouchpadScroll> arrived in Tk 8.7, so a macOS on an
+                # older Tk raises here and the dial cannot be built at all:
+                #
+                #     TclError: bad event type or keysym "TouchpadScroll"
+                #
+                # The wheel bindings below still work; only the finer trackpad
+                # events are lost. ScrollBindingMixin guards the same bind.
+                # Exception, not tk.TclError: this module does not import
+                # tkinter, so naming the specific class raised NameError from
+                # inside the handler -- which aborted the whole injection and
+                # took the <MouseWheel> bindings below with it. The dial then
+                # responded to clicks and not to the wheel.
+                try:
+                    target_layer.bind("<TouchpadScroll>",
+                                      self._process_mac_touchpad_scroll, add="+")
+                except Exception:
+                    pass
+            target_layer.bind("<MouseWheel>", self._process_scroll_wheel, add="+")
+            target_layer.bind("<Button-4>", self._process_scroll_wheel, add="+")
+            target_layer.bind("<Button-5>", self._process_scroll_wheel, add="+")
+
+    def _on_mouse_enter(self):
+        if self._state == "normal": self.canvas.focus_set()
+
+    def _set_appearance_mode(self, mode_string):
+        if hasattr(super(), "_set_appearance_mode"):
+            try: super()._set_appearance_mode(mode_string)
+            except Exception: pass
+        if hasattr(self, "canvas") and self.canvas.winfo_exists():
+            defer(self, 20, self._process_theme_repaint)
+
+    def _process_theme_repaint(self):
+        """🔑 TRANSPARENCY SHIELD FIXED: Resolves transparent settings to parent hex values."""
+        theme_bg_raw = self._local_defaults.get("fg_color", "transparent")
+        if self._state == "disabled":
+            theme_bg_raw = self._custom_disabled_map.get("fg_color", "transparent")
+
+        resolved_bg = self._resolve_color(theme_bg_raw)
+
+        if resolved_bg == "transparent":
+            current_parent = self.master
+            while current_parent is not None:
+                if hasattr(current_parent, "cget"):
+                    try:
+                        p_color = current_parent.cget("fg_color")
+                        if p_color and p_color not in ("transparent", ""):
+                            resolved_bg = self._resolve_color(p_color)
+                            break
+                    except Exception:
+                        pass
+                current_parent = getattr(current_parent, "master", None)
+
+            if resolved_bg == "transparent":
+                resolved_bg = self._opaque_fallback()
+
+        self.canvas.configure(bg=resolved_bg)
+        if hasattr(self, "_draw_dial_base"): self._draw_dial_base()
+
+    def _opaque_fallback(self):
+        """A drawable colour for when everything above resolves transparent."""
+        return ("#1C1C1C" if str(ctk.get_appearance_mode()).lower() == "dark"
+                else "#F1F5F9")
+
+    def _canvas_background(self):
+        """
+        A colour the CANVAS can actually be set to.
+
+        fg_color may legitimately be "transparent" -- it is how a widget says
+        it should take its parent's colour, and a dial dropped into a themed
+        panel wants exactly that. A raw canvas cannot render the word, so it
+        has to be turned into whatever is really behind the widget:
+
+            TclError: unknown color name "transparent"
+
+        The same accommodation sCTkNotebook and sCTkFileExplorer make for
+        their canvases.
+        """
+        colour = self._resolve_color(self._local_defaults.get("fg_color"))
+        if colour != "transparent":
+            return colour
+
+        parent = getattr(self, "master", None)
+        for _ in range(6):
+            if parent is None:
+                break
+            try:
+                candidate = self._resolve_color(parent.cget("fg_color"))
+                if candidate and candidate != "transparent":
+                    return candidate
+            except Exception:
+                pass
+            parent = getattr(parent, "master", None)
+        return self._opaque_fallback()
+
+    # ------------------------------------------------------------------
+    # Clicks, drags, the wheel and the trackpad -- shared by all three dials
+    # ------------------------------------------------------------------
+    # FIX (2026-11-11): these were copied into each of sCTkDialContinuous,
+    # sCTkDialSelector and sCTkDialRange, and had already drifted apart
+    # once. Each dial now says only how it takes one step (_step) and how far
+    # a drag must travel for one (_DRAG_THRESHOLD_PX); the handling is here.
+
+    # Pixels of vertical drag per step. The selector's is larger: its
+    # positions are few and far apart, so a small drag should not skip one.
+    _DRAG_THRESHOLD_PX = 2
+
+    def _step(self, delta: int):
+        """Moves the dial by `delta` positions (+1 or -1). Each dial defines it."""
+        raise NotImplementedError
+
+    def _on_left_click_step(self, event):
+        if self._state == "disabled": return
+        if self._left_click_callback is not None: self._left_click_callback()
+        else: self._step(-1)
+
+    def _on_right_click_step(self, event):
+        if self._state == "disabled": return
+        if self._right_click_callback is not None: self._right_click_callback()
+        else: self._step(1)
+
+    def _on_button_press(self, event): self._last_y = event.y
+
+    def _on_button_motion(self, event):
+        if self._state == "disabled": return
+        delta_y = self._last_y - event.y
+        if abs(delta_y) > self._DRAG_THRESHOLD_PX:
+            self._step(1 if delta_y > 0 else -1)
+            self._last_y = event.y
+
+    def _process_mac_touchpad_scroll(self, event):
+        if self._state == "disabled": return "break"
+        current_time = time.time()
+        if current_time - self._last_scroll_time < self._scroll_cooldown_seconds: return "break"
+        delta_y = self._decode_mac_touchpad_delta(event.delta)
+        if delta_y != 0:
+            self._last_scroll_time = current_time
+            self._step(1 if delta_y > 0 else -1)
+        return "break"
+
+    def _process_scroll_wheel(self, event):
+        """
+        One wheel detent, once.
+
+        RETURNS "break", and must. The scroll handlers are installed on THREE
+        layers -- the drawing canvas, the widget, and CTkFrame's own
+        background canvas -- so an event that is not consumed propagates to
+        each in turn and the dial steps two or three times for one notch.
+
+        The symptom is subtle where a caller coalesces its commands and
+        obvious where it does not: a receive frequency ran away at roughly
+        2.5 steps per detent while a transmit one, whose writes were being
+        merged, looked correct.
+        """
+        if self._state == "disabled":
+            return "break"
+        if getattr(event, "num", 0) == 4 or (hasattr(event, "delta") and event.delta > 0):
+            d = 1
+        elif getattr(event, "num", 0) == 5 or (hasattr(event, "delta") and event.delta < 0):
+            d = -1
+        else:
+            return "break"
+        self._step(d)
+        return "break"
+
+    def _decode_mac_touchpad_delta(self, raw_delta):
+        raw = raw_delta & 0xFFFFFFFF
+        delta_y = raw & 0xFFFF
+        if delta_y >= 0x8000: delta_y -= 0x10000
+        return delta_y
+
+    def configure(self, *args, **kwargs):
+        """Handles Pygubu designer queries and manages composite state updates safely."""
+        if args and len(args) == 1:
+            # FIX: was
+            #     pname = args if isinstance(args, (list, tuple)) else args
+            # -- BOTH branches assigned `args`, which is always a tuple. Every
+            # comparison below therefore tested a tuple against a string and
+            # failed, so the entire query block was dead and Pygubu could read
+            # none of these properties. The ternary made it look deliberate.
+            #
+            # Same one-character bug found in sCTkFileExplorer, sCTkSMeterBar
+            # and sCTkPathChooser.
+            pname = args[0]
+            if pname == "latching":
+                return ("latching", "latching", "Latching", "False",
+                        str(bool(getattr(self, "_latching", False))))
+
+            if pname == "pressed":
+                return ("pressed", "pressed", "Pressed", "False",
+                        str(self.is_pressed()))
+
+            if pname == "width":
+                return ('width', 'width', 'Width', 120, super().cget("width") if hasattr(self, "cget") else 120)
+            if pname == "height":
+                return ('height', 'height', 'Height', 120, super().cget("height") if hasattr(self, "cget") else 120)
+            if pname == "state":
+                return ('state', 'state', 'State', 'normal', getattr(self, "_state", "normal"))
+            if pname == "labels":
+                # JSON, not a comma-joined string: pygubu parses list
+                # properties with a strict json.loads(). _query_value() renders
+                # it, given the property name -- see themeable_widget.py.
+                default_labels = ["POS 1", "POS 2", "POS 3"]
+                return ('labels', 'labels', 'Labels',
+                        self._query_value(default_labels, "labels"),
+                        self._query_value(
+                            list(getattr(self, "_labels", default_labels)),
+                            "labels"))
+
+            if pname == "label_font":
+                # The theme's label_font is the default, so clearing the field
+                # in the Designer returns to it rather than to nothing.
+                return ('label_font', 'label_font', 'Label font',
+                        self._query_value(
+                            self._local_defaults.get("label_font"), "label_font"),
+                        self._query_value(self._label_font(), "label_font"))
+            if pname in ["knob_diameter", "divisions", "arc_angle", "from_", "to", "command", "left_click_callback",
+                         "right_click_callback"]:
+                return (pname, pname, pname, "", "")
+            try:
+                return self._configure_query(pname)
+            except Exception:
+                return (pname, pname, pname, "", "")
+
+        # FIX: was `if args and isinstance(args, dict)`. args is ALWAYS a
+        # tuple, so this never fired and the dict form of configure() was
+        # dead code. Same tautology fixed across the batch-one widgets.
+        if len(args) == 1 and isinstance(args[0], dict):
+            kwargs = {**args[0], **kwargs}
+
+        if "width" in kwargs:
+            w = kwargs["width"]
+            kwargs["width"] = int(w) if (w and str(w).strip()) else 120
+        if "height" in kwargs:
+            h = kwargs["height"]
+            kwargs["height"] = int(h) if (h and str(h).strip()) else 120
+
+        if "label_font" in kwargs:
+            # Empty restores the theme's label_font, matching the query above
+            # and what generated code does when the property is omitted.
+            new_font = kwargs.pop("label_font")
+            self._label_font_override = new_font if new_font else None
+            # Full redraw, not _redraw_indicator(): the labels are part of the
+            # dial body, and the cheap indicator-only path does not touch them.
+            self._draw_dial_base()
+
+        # Runtime overrides have to reach the map a repaint reads, or the
+        # repaint puts the theme value straight back -- see
+        # ThemeableWidget._record_theme_overrides().
+        self._record_theme_overrides(kwargs)
+
+        if "double_click_command" in kwargs:
+            self._double_click_command = kwargs.pop("double_click_command")
+
+        if "shift_double_click_command" in kwargs:
+            self._shift_double_click_command = kwargs.pop("shift_double_click_command")
+
+        if "latching" in kwargs:
+            _l = kwargs.pop("latching")
+            if isinstance(_l, str):
+                _l = _l.strip().lower() in ("true", "1", "yes")
+            self._latching = bool(_l)
+            if not self._latching:
+                self._pressed = False
+            self._apply_input_bindings()
+            self._process_theme_repaint()
+
+        if "pressed" in kwargs:
+            _p = kwargs.pop("pressed")
+            # The Designer sends strings.
+            if isinstance(_p, str):
+                _p = _p.strip().lower() in ("true", "1", "yes")
+            self.set_pressed(bool(_p))
+
+        if "state" in kwargs:
+            self.state(kwargs.pop("state"))
+
+        # This library's own theme keys are consumed here.
+        #
+        # They are not native CTkFrame options -- text_color, dial_color,
+        # pointer_color and the rest describe things this widget draws on its
+        # own canvas -- so forwarding them raises:
+        #
+        #     ['text_color'] are not supported arguments.
+        #
+        # _record_theme_overrides() above has already stored the value and
+        # triggered a redraw, so there is nothing left to do with them.
+        for _own_key in list(kwargs):
+            if _own_key in self._local_defaults:
+                kwargs.pop(_own_key)
+
+        if kwargs:
+            self._drop_cleared(kwargs)
+            if kwargs: return super().configure(**kwargs)
+        return None
+
+
+    # Tkinter/CTk convention binds .config to .configure as a SEPARATE class
+    # attribute -- it does NOT track whichever configure() a subclass defines.
+    # Without this, .config(...) skips every override in this class and lands
+    # on the native widget, bypassing divisions/command/diameter handling and
+    # the theme repaint entirely. Confirmed as a critical bug on
+    # sCTkSegmentedButton earlier in this project's audit. Each subclass needs
+    # its own line -- inheriting the alias would point at the PARENT's
+    # configure(), not the subclass's.
+    config = configure
+    def get_state(self) -> str:
+        return str(self._state).lower()
+
+    def state(self, mode: str = None) -> str:
+        """Dedicated rotary dial operational interaction lock and visibility state controller."""
+        if mode is None:
+            return str(self._state).lower()
+
+        mode = mode.lower()
+        if mode in ("normal", "enabled", "active"):
+            self._state = "normal"
+            self._custom_current_state = "normal"
+
+            # 🔑 1. REPAINT CANVAS LAYERS FIRST: Let Tkinter settle its color configurations
+            self._process_theme_repaint()
+
+            # Bindings follow BOTH conditions: enabling a dial that is
+            # switched off must not make it responsive. Disabling cleared the
+            # latch, so a dial always comes back from a lock switched off.
+            self._apply_input_bindings()
+
+        elif mode == "disabled":
+            self._state = "disabled"
+            self._custom_current_state = "disabled"
+            # Disabling switches the dial OFF as well as locking it, so
+            # re-enabling leaves it inert until deliberately double-clicked.
+            #
+            # This is what makes a panel lock useful: unlocking gives you a
+            # screen of dials that cannot be nudged by accident, rather than
+            # one that comes back live because it was live before the lock.
+            self._pressed = False
+            self._apply_input_bindings()
+            self._process_theme_repaint()
+
+        return str(self._state).lower()
+
+    def cget(self, attribute_name: str) -> any:
+        if attribute_name == "pressed": return self.is_pressed()
+        if attribute_name == "latching": return bool(getattr(self, "_latching", False))
+        if attribute_name == "double_click_command": return self._double_click_command
+        if attribute_name == "shift_double_click_command": return self._shift_double_click_command
+        if attribute_name == "state": return getattr(self, "_state", "normal")
+        if attribute_name == "knob_diameter": return self._knob_diameter
+        if attribute_name == "divisions": return getattr(self, "_divisions", 24)
+        return super().cget(attribute_name)
+
+    # ------------------------------------------------------------------
+    # Knob shading
+    # ------------------------------------------------------------------
+    # Number of concentric ovals used to fake a radial gradient. Tk's canvas
+    # has no gradient primitive and no alpha channel, so the only way to get a
+    # domed surface is to stack solid-filled ovals, each slightly smaller and
+    # shifted toward the light source. Below ~12 the steps read as visible
+    # contour bands; above ~24 the extra items cost more than they show.
+    KNOB_SHADE_STEPS = 18
+
+    # How far the ring stack shrinks from edge to centre, and how far each
+    # step drifts toward the light. Both as fractions of the knob radius.
+    KNOB_SHADE_SHRINK = 0.55
+    KNOB_LIGHT_OFFSET = 0.55
+
+    # Finger dimple, as fractions of knob radius -- NOT absolute pixels. The
+    # previous code used a fixed 14px inset with a fixed 14.5px radius, so the
+    # dimple was lost on a large dial and swallowed a small one.
+    DIMPLE_RADIUS_FRAC = 0.36
+    DIMPLE_RIM_CLEARANCE_FRAC = 0.06
+
+    # Pointer line for Selector/Range: width in px, and how far short of the
+    # rim it stops.
+    POINTER_WIDTH = 3.0
+    POINTER_RIM_INSET = 3
+
+    @staticmethod
+    def _lerp_color(color_a: str, color_b: str, t: float) -> str:
+        """
+        Blends two resolved "#RRGGBB" strings.
+
+        Both inputs must already be resolved to a single colour by
+        _resolve_color() -- this cannot accept (light, dark) tuples.
+
+        Args:
+            color_a: Start colour at t=0.
+            color_b: End colour at t=1.
+            t: Position between them, 0.0 to 1.0.
+
+        Returns:
+            The blended colour as "#RRGGBB".
+        """
+        a = tuple(int(color_a[i:i + 2], 16) for i in (1, 3, 5))
+        b = tuple(int(color_b[i:i + 2], 16) for i in (1, 3, 5))
+        return "#%02X%02X%02X" % tuple(int(a[i] + (b[i] - a[i]) * t) for i in range(3))
+
+    def _draw_shaded_disc(self, cx, cy, radius, edge_color, centre_color, tag,
+                          rim_light=None, rim_shadow=None, recessed=False):
+        """
+        Draws a domed (or recessed) disc as a stack of concentric ovals.
+
+        The light source is the upper left. For a DOME each successive ring
+        shrinks and drifts toward that light, so the bright end of the ramp
+        lands off-centre where a highlight would fall. For a RECESS the drift
+        is inverted -- a hole lit from the upper left is shadowed on its
+        upper-left interior wall and lit on the lower right. Getting that
+        backwards is what makes a dimple pop outward as a bump instead of
+        sinking in.
+
+        Args:
+            cx, cy: Centre of the disc.
+            radius: Outer radius.
+            edge_color: Resolved colour at the outer edge.
+            centre_color: Resolved colour at the lit end of the ramp.
+            tag: Canvas tag applied to every item, so the whole disc can be
+                deleted as a unit.
+            rim_light: Optional resolved colour for the lit rim arc.
+            rim_shadow: Optional resolved colour for the shaded rim arc.
+            recessed: True to invert the light direction (see above).
+        """
+        direction = -1.0 if recessed else 1.0
+        for i in range(self.KNOB_SHADE_STEPS):
+            t = i / (self.KNOB_SHADE_STEPS - 1)
+            r = radius * (1.0 - self.KNOB_SHADE_SHRINK * t)
+            drift = (radius - r) * self.KNOB_LIGHT_OFFSET * direction
+            x, y = cx - drift, cy - drift
+            self.canvas.create_oval(x - r, y - r, x + r, y + r,
+                                    fill=self._lerp_color(edge_color, centre_color, t),
+                                    outline="", tags=tag)
+
+        # Rim lighting. On a dark knob this does most of the work: the body
+        # ramp is clamped at the bottom (you can't go darker than black), so
+        # the bright upper-left arc is what reads as a curved edge rather than
+        # a flat cut-out.
+        if rim_light:
+            lit_start, shade_start = (225, 45) if not recessed else (45, 225)
+            self.canvas.create_arc(cx - radius, cy - radius, cx + radius, cy + radius,
+                                   start=lit_start, extent=180, style="arc",
+                                   outline=rim_light, width=2.5, tags=tag)
+            if rim_shadow:
+                self.canvas.create_arc(cx - radius, cy - radius, cx + radius, cy + radius,
+                                       start=shade_start, extent=180, style="arc",
+                                       outline=rim_shadow, width=2.5, tags=tag)
+
+    def _redraw_indicator(self):
+        """
+        Redraws only the moving indicator -- the dimple or the pointer line --
+        leaving the knob body, ticks and labels alone.
+
+        Call this on a VALUE change. Call _draw_dial_base() only when the
+        geometry, theme or state changes.
+
+        The body is now a stack of ~20 shaded ovals plus ticks and labels, and
+        none of it changes as the dial turns. Rebuilding all of it per detent
+        made the shading cost real; this makes it free while tuning. Same
+        pattern as sCTkSMeter._execute_needle_draw(), which redraws its needle
+        against a static face.
+        """
+        if not hasattr(self, "canvas") or not self.canvas.winfo_exists(): return
+        if not self.canvas.find_withtag("knob_body"):
+            # Body was never drawn (first paint, or a resize wiped it), so a
+            # partial update would leave the dial blank. Do the full pass.
+            self._draw_dial_base()
+            return
+        self._draw_dial_base(indicator_only=True)
+
+    def _draw_dial_base(self, indicator_only: bool = False):
+        if not hasattr(self, "canvas") or not self.canvas.winfo_exists(): return
+        if not indicator_only:
+            self.canvas.delete("all")
+        width, height = self.canvas.winfo_width(), self.canvas.winfo_height()
+        if width < 10 or height < 10: width = height = int(self.cget("width") if hasattr(self, "cget") else 120)
+
+        # Resolved, not the class name: a preview or user subclass must draw
+        # as the variant it derives from, or it renders as the generic base.
+        child_classname = self._theme_block()
+        # No `or ("#hex", "#hex")` fallbacks: _validate_theme_keys() hard-failed
+        # at construction if any of these were missing, so every lookup here is
+        # guaranteed to resolve. A fallback would only reintroduce the silent
+        # substitution that made an incomplete theme block invisible.
+        bg_color = self._canvas_background()
+        shadow_paint = self._resolve_color(self._local_defaults.get("shadow_color"))
+        text_color = self._resolve_color(self._local_defaults.get("text_color"))
+        dial_color = self._resolve_color(self._local_defaults.get("dial_color"))
+        is_dark_mode = (ctk.get_appearance_mode() == "Dark")
+
+        # Knob shading colours. Explicit rather than derived from dial_color:
+        # a fixed lighten/darken percentage produces a nearly invisible rim on
+        # a black knob and a blown-out one on aluminium, because the available
+        # range differs enormously between them.
+        knob_highlight = self._resolve_color(self._local_defaults.get("dial_highlight_color"))
+        knob_shadow = self._resolve_color(self._local_defaults.get("dial_shadow_color"))
+        rim_light = self._resolve_color(self._local_defaults.get("dial_rim_light_color"))
+        rim_shadow = self._resolve_color(self._local_defaults.get("dial_rim_shadow_color"))
+
+        if self._draws_active():
+            # SWITCHED ON. pressed_map holds the operational look; the top
+            # level above is the resting, dimmed one. Each key falls back to
+            # the top-level value, so a pressed_map that names only the few
+            # colours that should brighten is a valid block.
+            _pm = self._custom_pressed_map
+
+            def _pressed_or(key, current):
+                val = _pm.get(key)
+                return self._resolve_color(val) if val is not None else current
+
+            text_color = _pressed_or("text_color", text_color)
+            dial_color = _pressed_or("dial_color", dial_color)
+            shadow_paint = _pressed_or("shadow_color", shadow_paint)
+            knob_highlight = _pressed_or("dial_highlight_color", knob_highlight)
+            knob_shadow = _pressed_or("dial_shadow_color", knob_shadow)
+            rim_light = _pressed_or("dial_rim_light_color", rim_light)
+            rim_shadow = _pressed_or("dial_rim_shadow_color", rim_shadow)
+            # fg_color deliberately not switched: the background stays put and
+            # the knob face carries the signal, as it does when disabled.
+
+        if self._state == "disabled":
+            text_color = self._resolve_color(self._custom_disabled_map.get("text_color"))
+            # FIX: this previously read "fg_color" for BOTH the dial face and
+            # the background, so once disabled_map actually contained fg_color
+            # the knob would render the same colour as the surface behind it
+            # and vanish. The two only looked different before because the map
+            # was empty and their hardcoded fallbacks happened to differ.
+            dial_color = self._resolve_color(self._custom_disabled_map.get("dial_color"))
+            knob_highlight = self._resolve_color(
+                self._custom_disabled_map.get("dial_highlight_color") or self._custom_disabled_map.get("dial_color"))
+            knob_shadow = self._resolve_color(
+                self._custom_disabled_map.get("dial_shadow_color") or self._custom_disabled_map.get("dial_color"))
+            rim_light = self._resolve_color(
+                self._custom_disabled_map.get("dial_rim_light_color") or self._custom_disabled_map.get("dial_color"))
+            rim_shadow = self._resolve_color(
+                self._custom_disabled_map.get("dial_rim_shadow_color") or self._custom_disabled_map.get("dial_color"))
+            # Background deliberately NOT dimmed -- the knob face and border
+            # carry the disabled signal, matching sCTkScrollableFrame.
+
+        self.canvas.configure(bg=bg_color)
+        center_x, center_y = width / 2, height / 2
+        # knob_diameter is the KNOB, not the widget. The canvas is width x
+        # height, and the knob is drawn at the size asked for regardless -- so
+        # three dials sharing a knob_diameter have identical faces however long
+        # their labels are.
+        #
+        # An earlier version measured the labels and shrank the knob to fit
+        # them inside the widget. That kept the layout predictable but made the
+        # knobs differ between dials whose labels differed, which is wrong in
+        # the case that matters most: a row of controls on a panel.
+        #
+        # Labels that do not fit are clipped. Widen the canvas -- see
+        # _default_canvas_size() for what a bare knob_diameter reserves.
+        knob_radius = self._knob_diameter / 2.0
+
+        # Never larger than the canvas: a knob bigger than its widget would
+        # draw outside the visible area with no indication why.
+        knob_radius = min(knob_radius, min(center_x, center_y))
+
+        has_arc_constraints = hasattr(self, "_arc_angle")
+        arc_sweep = float(self._arc_angle) if has_arc_constraints else 360.0
+        start_deg = -90.0 - (arc_sweep / 2.0) if has_arc_constraints else 0.0
+
+        if child_classname == "sCTkDialSelector" and hasattr(self, "_labels"):
+            if not self._labels or len(self._labels) == 0: self._labels = list(getattr(self, "_default_labels", ["POS 1", "POS 2", "POS 3"]))
+            total_ticks = len(self._labels)
+            self._divisions = total_ticks
+        elif child_classname == "sCTkDialRange" and hasattr(self, "_divisions"):
+            total_ticks = int(self._divisions) if (self._divisions and int(self._divisions) > 0) else 5
+        else:
+            total_ticks = int(self._divisions) if (hasattr(self, "_divisions") and self._divisions) else 24
+
+        if not indicator_only:
+            for i in range(total_ticks):
+                fraction = (i / (total_ticks - 1)) if (total_ticks > 1 and has_arc_constraints) else (i / total_ticks)
+                angle_deg = start_deg + (fraction * arc_sweep)
+                angle_rad = math.radians(-angle_deg)
+                x1, y1 = center_x + knob_radius * math.cos(angle_rad), center_y - knob_radius * math.sin(angle_rad)
+                x2, y2 = center_x + (knob_radius + 6) * math.cos(angle_rad), center_y - (knob_radius + 6) * math.sin(angle_rad)
+                self.canvas.create_line(x1, y1, x2, y2, fill=text_color, width=2.0)
+
+                if child_classname == "sCTkDialSelector" and i < len(self._labels):
+                    label_offset, label_anchor = self._label_placement(angle_rad, knob_radius)
+                    self.canvas.create_text(
+                        center_x + label_offset * math.cos(angle_rad),
+                        center_y - label_offset * math.sin(angle_rad),
+                        text=str(self._labels[i]), fill=text_color,
+                        font=self._label_font(), anchor=label_anchor)
+                elif child_classname == "sCTkDialRange":
+                    from_val, to_val = getattr(self, "_from", 0), getattr(self, "_to", 100)
+                    range_val = int(from_val + (to_val - from_val) * fraction)
+                    label_offset, label_anchor = self._label_placement(angle_rad, knob_radius)
+                    self.canvas.create_text(
+                        center_x + label_offset * math.cos(angle_rad),
+                        center_y - label_offset * math.sin(angle_rad),
+                        text=str(range_val), fill=text_color,
+                        font=self._label_font(), anchor=label_anchor)
+
+            self.canvas.create_oval(center_x - knob_radius + 1, center_y - knob_radius + 4, center_x + knob_radius + 4, center_y + knob_radius + 4, fill=shadow_paint, outline="")
+
+            if child_classname == "sCTkDialContinuous":
+                num_side_teeth = 72
+                teeth_shadow = "#000000" if is_dark_mode else "#334155"
+                for k in range(num_side_teeth):
+                    k_angle = math.radians(-(k * (360.0 / num_side_teeth)))
+                    self.canvas.create_line(center_x + knob_radius * math.cos(k_angle), center_y - knob_radius * math.sin(k_angle), center_x + (knob_radius - 3) * math.cos(k_angle), center_y - (knob_radius - 3) * math.sin(k_angle), fill=teeth_shadow, width=1.5)
+
+            # The knob body: a stack of concentric ovals stepping from
+            # dial_shadow_color at the rim to dial_highlight_color off-centre,
+            # replacing what used to be a single flat fill with two hardcoded
+            # outline rings. See _draw_shaded_disc().
+            self._draw_shaded_disc(center_x, center_y, knob_radius - 2,
+                                   knob_shadow, knob_highlight, "knob_body",
+                                   rim_light=rim_light, rim_shadow=rim_shadow)
+
+        val_pct = self._get_value_fraction() if hasattr(self, "_get_value_fraction") else 0.0
+        pointer_rad = math.radians(-(start_deg + (val_pct * arc_sweep)))
+
+        # Indicator. Tagged separately from the body so a value change can
+        # redraw ONLY this -- see _redraw_indicator(). The body is expensive
+        # now and doesn't change while the dial is turned.
+        self.canvas.delete("indicator")
+
+        if child_classname in ["sCTkDialSelector", "sCTkDialRange"]:
+            # A plain straight line from dead centre out to just short of the
+            # rim, which is how these knobs are actually marked. The previous
+            # version drew an arrowhead and a centre cap; both are gone, along
+            # with the cap's two hardcoded outline colours.
+            px = center_x + (knob_radius - self.POINTER_RIM_INSET) * math.cos(pointer_rad)
+            py = center_y - (knob_radius - self.POINTER_RIM_INSET) * math.sin(pointer_rad)
+            pointer_key = "pointer_color"
+            if self._state == "disabled":
+                raw_pointer = (self._custom_disabled_map.get(pointer_key)
+                               or self._custom_disabled_map.get("text_color"))
+            elif self._draws_active():
+                # Switched on, or never latching: pressed_map first, then the
+                # resting value.
+                raw_pointer = (self._custom_pressed_map.get(pointer_key)
+                               or self._custom_pressed_map.get("text_color")
+                               or self._local_defaults.get(pointer_key)
+                               or self._local_defaults.get("text_color"))
+            else:
+                raw_pointer = (self._local_defaults.get(pointer_key)
+                               or self._local_defaults.get("text_color"))
+            self.canvas.create_line(center_x, center_y, px, py,
+                                    fill=self._resolve_color(raw_pointer),
+                                    width=self.POINTER_WIDTH, capstyle="round",
+                                    tags="indicator")
+        else:
+            # Continuous only: the finger dimple a VFO operator spins the dial
+            # by. Sized as a FRACTION of knob_radius so it holds its
+            # proportions at any dial size.
+            # Resolved HERE rather than above, because only this branch draws
+            # a dimple. The previous code resolved it for every dial, so
+            # Selector and Range looked up a key they never used -- which is
+            # why pointer_glow_color appeared "missing" from their theme
+            # blocks. It belongs to Continuous alone.
+            pointer_glow = self._resolve_color(
+                self._custom_disabled_map.get("pointer_glow_color") if self._state == "disabled"
+                else self._local_defaults.get("pointer_glow_color"))
+
+            ind_radius = knob_radius * self.DIMPLE_RADIUS_FRAC
+            clearance = knob_radius * self.DIMPLE_RIM_CLEARANCE_FRAC
+            dimple_center_radius = knob_radius - ind_radius - clearance
+            dx = center_x + dimple_center_radius * math.cos(pointer_rad)
+            dy = center_y - dimple_center_radius * math.sin(pointer_rad)
+
+            # recessed=True inverts the light direction: a hole lit from the
+            # upper left is shadowed on its upper-left interior wall. Drawn
+            # with the body's direction it would read as a raised bump.
+            self._draw_shaded_disc(dx, dy, ind_radius, knob_highlight, knob_shadow,
+                                   "indicator", rim_light=rim_shadow,
+                                   rim_shadow=rim_light, recessed=True)
+            self.canvas.create_oval(dx - ind_radius, dy - ind_radius, dx + ind_radius, dy + ind_radius,
+                                    fill="", outline=pointer_glow, width=1.5, tags="indicator")
+class sCTkDialContinuous(sCTKDialBase):
+    # Only this variant draws the finger dimple, so only it requires the glow
+    # ring colour -- see _draw_dial_base()'s indicator branch.
+    _EXTRA_THEME_KEYS = ("pointer_glow_color",)
+    _EXTRA_DISABLED_KEYS = ("pointer_glow_color",)
+
+    def __init__(self, master=None, divisions=24, command=None, left_click_callback=None, right_click_callback=None, knob_diameter=120, **kw):
+        super().__init__(master, divisions=divisions, knob_diameter=knob_diameter, **kw)
+        self._command = command
+        self._left_click_callback = left_click_callback if (left_click_callback and str(left_click_callback).strip()) else None
+        self._right_click_callback = right_click_callback if (right_click_callback and str(right_click_callback).strip()) else None
+        self._current_value = 0
+        self._finalize_themeable_lifecycle()
+
+    def _get_value_fraction(self): return self._current_value / self._divisions
+    def configure(self, *args, **kwargs):
+        if args: return super().configure(*args, **kwargs)
+        if "divisions" in kwargs: self._divisions = int(kwargs.pop("divisions"))
+        if "command" in kwargs: self._command = kwargs.pop("command")
+        if "left_click_callback" in kwargs: self._left_click_callback = kwargs.pop("left_click_callback")
+        if "right_click_callback" in kwargs: self._right_click_callback = kwargs.pop("right_click_callback")
+        if "knob_diameter" in kwargs:
+            # Sets the KNOB only. The canvas keeps whatever width and height it
+            # has -- resizing the widget when the knob changes would move
+            # everything else in the layout.
+            self._knob_diameter = int(kwargs.pop("knob_diameter"))
+        result = super().configure(**kwargs)
+        if hasattr(self, "canvas") and self.canvas.winfo_exists(): self._draw_dial_base()
+        return result
+
+
+    # Tkinter/CTk convention binds .config to .configure as a SEPARATE class
+    # attribute -- it does NOT track whichever configure() a subclass defines.
+    # Without this, .config(...) skips every override in this class and lands
+    # on the native widget, bypassing divisions/command/diameter handling and
+    # the theme repaint entirely. Confirmed as a critical bug on
+    # sCTkSegmentedButton earlier in this project's audit. Each subclass needs
+    # its own line -- inheriting the alias would point at the PARENT's
+    # configure(), not the subclass's.
+    config = configure
+    def cget(self, attribute_name: str) -> any:
+        if attribute_name == "command": return self._command
+        if attribute_name == "left_click_callback": return self._left_click_callback
+        if attribute_name == "right_click_callback": return self._right_click_callback
+        return super().cget(attribute_name)
+
+    def set_position_index(self, step_delta):
+        self._current_value = (self._current_value + int(step_delta)) % self._divisions
+        if self.canvas.winfo_exists(): self._redraw_indicator()
+        if self._command is not None and self._state == "normal": self._command(int(step_delta))
+
+    def _step(self, delta: int):
+        self.set_position_index(delta)
+
+
+class sCTkDialSelector(sCTKDialBase):
+    # This variant draws a plain line pointer rather than a dimple, so it
+    # requires pointer_color instead of pointer_glow_color. pointer_color was
+    # present in the theme file but never read by any code path until now.
+    # label_font is required on the two variants that DRAW text. Continuous
+    # draws none, so it does not carry the key.
+    _EXTRA_THEME_KEYS = ("pointer_color", "label_font")
+
+    """
+    Rotary switch selector module. Constrained to custom arc angles (default 270).
+    Loops infinitely past outer limits and reports the active integer item index position.
+    """
+    def __init__(self, master=None, labels=None, arc_angle=270, command=None, left_click_callback=None, right_click_callback=None, knob_diameter=120, **kw):
+        if isinstance(labels, str) and labels.strip():
+            # Shared parser -- see parse_list_property(). This site used
+            # literal_eval with a manual fallback; the configure() site
+            # below used a bare split that did NOT strip quotes, so the
+            # same value parsed differently depending on when it was set.
+            labels = parse_list_property(labels)
+        self._default_labels = ["POS 1", "POS 2", "POS 3"]
+        self._labels = labels if labels is not None else list(self._default_labels)
+        self._arc_angle = float(arc_angle)
+        super().__init__(master, divisions=len(self._labels), knob_diameter=knob_diameter, **kw)
+        self._scroll_cooldown_seconds = 0.150
+        self._command = command
+        self._left_click_callback = left_click_callback if (left_click_callback and str(left_click_callback).strip()) else None
+        self._right_click_callback = right_click_callback if (right_click_callback and str(right_click_callback).strip()) else None
+        self._current_value = 0
+        self._custom_current_state = "normal" if self._state == "normal" else "disabled"
+        self._finalize_themeable_lifecycle()
+
+    def _get_value_fraction(self):
+        t = len(self._labels) - 1
+        return self._current_value / t if t > 0 else 0.0
+
+    def configure(self, *args, **kwargs):
+        if args: return super().configure(*args, **kwargs)
+        if "labels" in kwargs:
+            lbls = kwargs.pop("labels")
+            if isinstance(lbls, str):
+                s = lbls.strip().strip("[]\"'")
+                lbls = parse_list_property(s, default=list(self._default_labels))
+            self._labels = list(self._default_labels) if not lbls else lbls
+            self._divisions = len(self._labels)
+        if "arc_angle" in kwargs: self._arc_angle = float(kwargs.pop("arc_angle"))
+        if "command" in kwargs: self._command = kwargs.pop("command")
+        if "left_click_callback" in kwargs: self._left_click_callback = kwargs.pop("left_click_callback")
+        if "right_click_callback" in kwargs: self._right_click_callback = kwargs.pop("right_click_callback")
+        if "knob_diameter" in kwargs:
+            # Sets the KNOB only. The canvas keeps whatever width and height it
+            # has -- resizing the widget when the knob changes would move
+            # everything else in the layout.
+            self._knob_diameter = int(kwargs.pop("knob_diameter"))
+        result = super().configure(**kwargs)
+        if hasattr(self, "canvas") and self.canvas.winfo_exists(): self._draw_dial_base()
+        return result
+
+
+    # Tkinter/CTk convention binds .config to .configure as a SEPARATE class
+    # attribute -- it does NOT track whichever configure() a subclass defines.
+    # Without this, .config(...) skips every override in this class and lands
+    # on the native widget, bypassing divisions/command/diameter handling and
+    # the theme repaint entirely. Confirmed as a critical bug on
+    # sCTkSegmentedButton earlier in this project's audit. Each subclass needs
+    # its own line -- inheriting the alias would point at the PARENT's
+    # configure(), not the subclass's.
+    config = configure
+    def cget(self, attribute_name: str) -> any:
+        if attribute_name == "labels": return self._labels
+        if attribute_name == "arc_angle": return self._arc_angle
+        if attribute_name == "command": return self._command
+        return super().cget(attribute_name)
+
+    def set(self, value):
+        t = len(self._labels)
+        if t == 0: return
+        target = int(value)
+        if target >= t: target = 0
+        elif target < 0: target = t - 1
+        self._current_value = target
+        if self.canvas.winfo_exists(): self._redraw_indicator()
+        if self._command is not None and self._state == "normal": self._command(self._current_value)
+
+    def get(self): return self._current_value
+    # Few positions, far apart: a small drag should not skip one.
+    _DRAG_THRESHOLD_PX = 25
+
+    def _step(self, delta: int):
+        self.set(self._current_value + delta)
+
+
+class sCTkDialRange(sCTKDialBase):
+    # This variant draws a plain line pointer rather than a dimple, so it
+    # requires pointer_color instead of pointer_glow_color. pointer_color was
+    # present in the theme file but never read by any code path until now.
+    # label_font is required on the two variants that DRAW text. Continuous
+    # draws none, so it does not carry the key.
+    _EXTRA_THEME_KEYS = ("pointer_color", "label_font")
+
+    """
+    Ranged potentiometer module tracking discrete integer boundaries.
+    Enforces absolute dead stops (does not loop at thresholds) and reports absolute integer states.
+    """
+    def __init__(self, master=None, from_=0, to=100, arc_angle=270, command=None, left_click_callback=None, right_click_callback=None, knob_diameter=120, divisions=5, **kw):
+        self._from = int(from_)
+        self._to = int(to)
+        self._arc_angle = float(arc_angle)
+        super().__init__(master, divisions=divisions, knob_diameter=knob_diameter, **kw)
+        self._command = command
+        self._left_click_callback = left_click_callback if (left_click_callback and str(left_click_callback).strip()) else None
+        self._right_click_callback = right_click_callback if (right_click_callback and str(right_click_callback).strip()) else None
+        self._current_value = self._from
+        self._custom_current_state = "normal" if self._state == "normal" else "disabled"
+        self._finalize_themeable_lifecycle()
+
+    def _get_value_fraction(self):
+        r = self._to - self._from
+        return (self._current_value - self._from) / r if r > 0 else 0.0
+
+    def configure(self, *args, **kwargs):
+        if args: return super().configure(*args, **kwargs)
+        if "from_" in kwargs or "min_value" in kwargs: self._from = int(kwargs.pop("from_", kwargs.pop("min_value", 0)))
+        if "to" in kwargs or "max_value" in kwargs: self._to = int(kwargs.pop("to", kwargs.pop("max_value", 100)))
+        if "arc_angle" in kwargs: self._arc_angle = float(kwargs.pop("arc_angle"))
+        if "divisions" in kwargs: self._divisions = int(kwargs.pop("divisions"))
+        if "command" in kwargs: self._command = kwargs.pop("command")
+        if "left_click_callback" in kwargs: self._left_click_callback = kwargs.pop("left_click_callback")
+        if "right_click_callback" in kwargs: self._right_click_callback = kwargs.pop("right_click_callback")
+        if "knob_diameter" in kwargs:
+            # Sets the KNOB only. The canvas keeps whatever width and height it
+            # has -- resizing the widget when the knob changes would move
+            # everything else in the layout.
+            self._knob_diameter = int(kwargs.pop("knob_diameter"))
+        result = super().configure(**kwargs)
+        if hasattr(self, "canvas") and self.canvas.winfo_exists(): self._draw_dial_base()
+        return result
+
+
+    # Tkinter/CTk convention binds .config to .configure as a SEPARATE class
+    # attribute -- it does NOT track whichever configure() a subclass defines.
+    # Without this, .config(...) skips every override in this class and lands
+    # on the native widget, bypassing divisions/command/diameter handling and
+    # the theme repaint entirely. Confirmed as a critical bug on
+    # sCTkSegmentedButton earlier in this project's audit. Each subclass needs
+    # its own line -- inheriting the alias would point at the PARENT's
+    # configure(), not the subclass's.
+    config = configure
+    def cget(self, attribute_name: str) -> any:
+        if attribute_name in ["from_", "min_value"]: return self._from
+        if attribute_name in ["to", "max_value"]: return self._to
+        if attribute_name == "arc_angle": return self._arc_angle
+        if attribute_name == "command": return self._command
+        if attribute_name == "divisions": return self._divisions
+        return super().cget(attribute_name)
+
+    def set(self, value):
+        target = max(self._from, min(self._to, int(value)))
+        if target != self._current_value:
+            self._current_value = target
+            if self.canvas.winfo_exists(): self._redraw_indicator()
+            if self._command is not None and self._state == "normal": self._command(self._current_value)
+
+    def get(self): return self._current_value
+    def _step(self, delta: int):
+        self.set(self._current_value + delta)