scustomtkinter 0.2.1__py3-none-any.whl

scustomtkinter/sctk_button_tertiary.py

@@ -0,0 +1,375 @@
+#!/usr/bin/python3
+"""
+sCTkButtonTertiary
+
+A theme-compliant tertiary (outline-style) action button widget -- the
+lowest-emphasis of the library's three button tiers (see also
+sCTkButtonPrimary, sCTkButtonSecondary). Inherits directly from ctk.CTkButton
+so CustomTkinter handles native rendering; this class layers automatic
+light/dark theme resolution and a four-state visual model
+(normal/disabled/pressed) on top. Unlike sCTkButtonPrimary, there is no
+"alarm" state here.
+
+Base class order matters here: `class sCTkButtonTertiary(ctk.CTkButton,
+ThemeableWidget)` puts the native CTk class first, so every `super()` call in
+this file's own methods resolves to ctk.CTkButton -- and, beneath it,
+tkinter.Misc -- never to ThemeableWidget. ThemeableWidget's own
+configure()/cget()/_set_appearance_mode() overrides have been removed entirely
+for this reason (see themeable_widget.py's docstring); this widget owns all of
+its own runtime color-swapping logic.
+"""
+from typing import Any, Optional
+import customtkinter as ctk
+from .themeable_widget import ThemeableWidget, defer
+
+
+class sCTkButtonTertiary(ctk.CTkButton, ThemeableWidget):
+    """Themeable tertiary (outline-style) action button.
+
+    Adds to native ctk.CTkButton:
+      - Automatic light/dark theme resolution from sCTkThemes.json (via
+        ThemeableWidget.__init__ -- see that class's docstring for what it does,
+        and just as importantly, what it no longer does).
+      - A three-state visual model: normal, disabled, and pressed. Precedence
+        when both could apply is disabled > pressed (see
+        _update_current_visual_state() and the guard clause in set_pressed()).
+      - Pygubu Designer property introspection for a handful of properties via
+        a single-argument configure() call.
+
+    This button style has a transparent fg_color by design (it's an outline
+    button: border + text, no filled background). The theme's disabled_map has
+    no fg_color or hover_color entries at all, which is deliberate -- omitting
+    them means those properties simply keep their current ("transparent")
+    value when disabled, rather than gaining a solid disabled-fill background
+    that a filled button would want but an outline button shouldn't.
+    Similarly, pressed_map has no hover_color entry; _update_current_visual_state()
+    explicitly falls back to the normal-state hover_color in that case (see
+    that method) rather than leaving it unset.
+
+    Colors are passed through to configure() as raw (light, dark) tuples rather
+    than pre-resolved to a single value, so CustomTkinter's own appearance-mode
+    tracking repaints them automatically on a light/dark switch -- the same
+    approach validated on sCTkComboBox, sCTkSegmentedButton, and sCTkButtonPrimary.
+
+    Disabling uses CTk's native state="disabled" rather than manually unbinding
+    mouse events -- an earlier version of this widget used the manual-unbind
+    approach (identical code to what sCTkButtonPrimary originally had), which
+    was directly tested and confirmed NOT to block clicks on that widget. The
+    fix is carried over here on the strength of both widgets sharing the same
+    underlying ctk.CTkButton click-handling; a confirmatory test on this
+    specific widget is still worthwhile.
+    """
+
+    def __init__(self, master: Optional[Any] = None, **kw: Any) -> None:
+        """
+        Args:
+            master: Parent container.
+            **kw: Any native CTkButton argument, or a theme-key override (see
+                the "sCTkButtonTertiary" block in sCTkThemes.json, including
+                its disabled_map, pressed_map and alarm_map sub-blocks).
+        """
+        # 1. Fire our shared theme logic first. This resolves final_kw
+        # (construction-time properties) and the disabled/pressed color maps.
+        # See ThemeableWidget.__init__ for what actually happens here.
+        # NO PLACEHOLDER TEXT. CustomTkinter defaults `text` to the class
+        # name, so a CTkButton built without text reads "CTkButton". Nothing wants
+        # that in a real interface, and the Designer made it worse: clearing
+        # the text field removes the property, the canvas rebuilds the widget
+        # from what is left, and the placeholder appeared in place of the
+        # blank that was asked for.
+        kw.setdefault("text", "")
+        ThemeableWidget.__init__(self, kw)
+
+        # 2. Deep-copy each resolved map onto this instance, so later changes
+        # here never leak back into the shared theme registry.
+        self._local_defaults = dict(self.final_kw)
+        self._custom_disabled_map = dict(self._widget_disabled_map)
+        self._custom_pressed_map = dict(self._widget_pressed_map)
+        self._custom_alarm_map = dict(self._widget_alarm_map)
+
+        # 3. Initialize CustomTkinter natively with the clean final kwargs array.
+        super().__init__(master, **self.final_kw)
+
+        self.is_pressed = False
+        self.is_alarm = False
+        self._custom_current_state = "normal"
+        self._update_current_visual_state()
+
+        # 4. Register lifecycle handshake hook, notifying Pygubu-style consumers
+        # that construction is complete.
+        self._finalize_themeable_lifecycle()
+
+    def configure(self, *args: Any, **kwargs: Any) -> Any:
+        """
+        Standard widget configuration, with Pygubu/positional-argument handling.
+
+        Args:
+            *args: At most one positional argument is meaningful:
+                - a dict: merged into kwargs and processed normally below.
+                - the literal string "state": returns a Tkinter-style
+                  (name, name, name, default, current) tuple.
+                - one of "fg_color"/"border_color"/"text_color"/"hover_color":
+                  returns the same style of tuple, with `current` reflecting
+                  whichever of disabled/alarm/pressed/normal is currently active.
+                  Note the returned value is str(value), where value may
+                  itself be a (light, dark) tuple rather than a single
+                  resolved color -- a known limitation shared with the wider
+                  Pygubu-query investigation set aside elsewhere in this
+                  project, not fixed here.
+                - anything else: forwarded directly to the native widget's
+                  configure(), which does not support single-argument property
+                  queries for arbitrary properties (same limitation).
+            **kwargs: Standard CTkButton configuration options, plus: passing
+                `state=...` routes through self.state() rather than being
+                forwarded as-is.
+
+        Returns:
+            The query tuple described above for the single-argument case, or
+            whatever super().configure() returns for the keyword-argument case
+            (typically None).
+        """
+        # args is always a tuple -- args[0] is the actual value passed, whether
+        # that's a string or a dict. An earlier version of this method compared
+        # the wrapped tuple directly (`pname = args`) and forwarded it unwrapped
+        # to super().configure(), which is not a valid call shape for the
+        # native widget. Don't reintroduce that.
+        if len(args) == 1:
+            if isinstance(args[0], dict):
+                kwargs = {**args[0], **kwargs}
+            else:
+                pname = args[0]
+                if pname == "state":
+                    return ("state", "state", "state", "normal", str(self.state()))
+
+                if pname in ["fg_color", "border_color", "text_color", "hover_color"]:
+                    current_state = str(self.state()).lower()
+                    if current_state == "disabled" and self._custom_disabled_map:
+                        val = self._custom_disabled_map.get(pname)
+                    elif getattr(self, "is_alarm", False) and self._custom_alarm_map:
+                        val = self._custom_alarm_map.get(pname)
+                    elif getattr(self, "is_pressed", False) and self._custom_pressed_map:
+                        val = self._custom_pressed_map.get(pname)
+                    else:
+                        val = self._local_defaults.get(pname)
+                    return (pname, pname, pname, self._query_value(self._theme_default(pname)), self._query_value(val))
+
+                return self._configure_query(pname)
+
+        # Runtime overrides have to reach the map a repaint reads, or
+        # _update_current_visual_state() puts the theme value straight back --
+        # see ThemeableWidget._record_theme_overrides().
+        self._record_theme_overrides(kwargs)
+
+        if "state" in kwargs:
+            target_state = kwargs.pop("state")
+            self.state(target_state)
+
+        # Theme values cleared to "" are dropped; `text=""` is kept, so a
+        # button's caption can actually be blanked. See
+        # ThemeableWidget._CONTENT_KEYS.
+        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 automatically track whichever configure() a
+    # subclass defines. Without this line, calling .config(...) on an instance
+    # would silently skip this entire override and land on the native widget's
+    # configure() directly, bypassing theming and state handling entirely.
+    config = configure
+
+    def _set_appearance_mode(self, mode_string: str) -> None:
+        """
+        Forwards CustomTkinter's internal light/dark mode change notification to
+        the native widget.
+
+        No longer manually re-triggers _update_current_visual_state(). That
+        method now passes raw (light, dark) tuples straight through to
+        configure() instead of pre-resolving to a single color, so CTk's own
+        appearance-mode tracking should repaint correctly on its own -- the same
+        approach validated on sCTkComboBox, sCTkSegmentedButton, and
+        sCTkButtonPrimary.
+
+        Args:
+            mode_string: The new appearance mode ("Light" or "Dark"), as passed
+                by CustomTkinter's internal appearance-mode change machinery.
+        """
+        if hasattr(super(), "_set_appearance_mode"):
+            try:
+                super()._set_appearance_mode(mode_string)
+            except Exception:
+                pass
+
+    def get_state(self) -> str:
+        """Equivalent to calling state() with no argument."""
+        return self.state()
+
+    def state(self, mode: Optional[str] = None) -> str:
+        """
+        Gets or sets the widget's enabled/disabled state.
+
+        Args:
+            mode: If None, returns the current state without changing anything.
+                Otherwise, only the literal string "disabled" (case-insensitive)
+                is treated as disabled; anything in ("normal", "enabled",
+                "active") is treated as enabled. Any other value falls through
+                without matching either branch, leaving the state unchanged.
+
+        Returns:
+            The resulting state ("normal" or "disabled", lowercase).
+        """
+        if mode is None:
+            return str(getattr(self, "_custom_current_state", "normal")).lower()
+
+        mode = mode.lower()
+        if mode in ("normal", "enabled", "active"):
+            self._custom_current_state = "normal"
+            super().configure(state="normal", hover=True)
+            # Re-establish the mouse bindings that disabling below may have
+            # torn down.
+            if hasattr(self, "_create_bindings"):
+                try: self._create_bindings()
+                except Exception: pass
+            # Deferred via after_idle rather than called immediately: on
+            # sCTkButtonPrimary, CTk's own state="normal" transition was found
+            # to schedule its own internal repaint that can run AFTER an
+            # immediate call here and silently overwrite fresh colors back to
+            # something stale. Queuing our reapply via after_idle lets CTk's
+            # own pending repaint settle first, so ours wins the final paint.
+            defer(self, "idle", self._update_current_visual_state)
+
+        elif mode == "disabled":
+            self._custom_current_state = "disabled"
+            # Uses CTk's native state="disabled" -- confirmed necessary (not
+            # optional) on sCTkButtonPrimary, which originally used the same
+            # manual-unbind code this method used to have. That approach was
+            # confirmed broken: clicks still fired the button's command while
+            # "disabled", almost certainly because CTkButton binds its click
+            # handler at the canvas-ITEM level (tag_bind on the drawn
+            # rectangle/text), not the canvas-WIDGET level -- so
+            # canvas.unbind() never reached it. Don't reintroduce manual event
+            # unbinding here.
+            super().configure(state="disabled", hover=False)
+            defer(self, "idle", self._update_current_visual_state)
+
+        return self._custom_current_state
+
+    def set_pressed(self, pressed: bool) -> None:
+        """
+        Toggles the visual "pressed" state.
+
+        No-op while disabled or in the alarm state -- see the precedence
+        order on _update_current_visual_state().
+
+        Args:
+            pressed: True to show the pressed-state colors, False to return to
+                normal (assuming not disabled or in alarm).
+        """
+        if getattr(self, "_custom_current_state", "normal") == "disabled" or self.is_alarm:
+            return
+        self.is_pressed = pressed
+        self._update_current_visual_state()
+
+    def set_alarm_state(self, active: bool) -> None:
+        """
+        Forces the button into (or out of) a high-visibility alarm state.
+
+        No-op while disabled. Turning alarm on clears any current "pressed"
+        state, since alarm takes visual precedence -- see
+        _update_current_visual_state().
+
+        Args:
+            active: True to enter the alarm state, False to leave it.
+        """
+        if getattr(self, "_custom_current_state", "normal") == "disabled":
+            return
+        self.is_alarm = active
+        if self.is_alarm:
+            self.is_pressed = False
+        self._update_current_visual_state()
+
+    def _update_current_visual_state(self) -> None:
+        """
+        Recomputes and applies this widget's colors from the theme file, based
+        on the current state. Precedence: disabled > alarm > pressed > normal -- only
+        the first matching branch applies.
+
+        Called after construction, on every state()/set_pressed() change, and
+        (indirectly, via after_idle) after every state() transition.
+
+        Passes raw (light, dark) tuples straight through to configure() instead
+        of resolving to a single color first, so CTk's native tracking can
+        handle appearance-mode repaints without help from _set_appearance_mode.
+        Every value here traces back to sCTkThemes.json; there are no
+        hardcoded colors in this method.
+
+        The pressed branch explicitly falls back to the normal-state
+        hover_color if pressed_map doesn't define one -- it doesn't, by
+        design, for this widget's theme block. See this class's docstring.
+
+        Only the normal (final else) branch also reapplies border_width,
+        corner_radius, and font -- these don't vary between
+        disabled/alarm/pressed/normal, so there's no need to repeat them in every
+        branch; they're set once here and otherwise left alone.
+        """
+        if getattr(self, "_custom_current_state", "normal") == "disabled":
+            config_payload = {}
+            for key in ("fg_color", "hover_color", "border_color"):
+                val = self._custom_disabled_map.get(key)
+                if val is not None:
+                    config_payload[key] = val
+
+            # disabled_map's text_color goes to the NATIVE text_color_disabled.
+            #
+            # CTkButton has its own text_color_disabled option and its draw
+            # code uses that whenever state is "disabled", overriding whatever
+            # text_color was set to. Assigning the disabled value to text_color
+            # here was therefore discarded at draw time and the theme key had
+            # no visible effect at all.
+            #
+            # text_color keeps the NORMAL value, so the two options do not
+            # fight and CTk chooses between them as it is designed to.
+            disabled_text = self._custom_disabled_map.get("text_color")
+            if disabled_text is not None:
+                config_payload["text_color_disabled"] = disabled_text
+                normal_text = self._local_defaults.get("text_color")
+                if normal_text is not None:
+                    config_payload["text_color"] = normal_text
+
+            if config_payload:
+                super().configure(**config_payload)
+            return
+
+        if getattr(self, "is_alarm", False):
+            config_payload = {}
+            for key in ("fg_color", "hover_color", "border_color", "text_color"):
+                val = self._custom_alarm_map.get(key)
+                if val is not None:
+                    config_payload[key] = val
+            config_payload["hover"] = False
+            super().configure(**config_payload)
+
+        elif getattr(self, "is_pressed", False):
+            config_payload = {}
+            for key in ("fg_color", "border_color", "hover_color", "text_color"):
+                val = self._custom_pressed_map.get(key)
+                if val is not None:
+                    config_payload[key] = val
+
+            # pressed_map has no hover_color entry for this widget by design
+            # (see class docstring) -- fall back to the normal-state value
+            # rather than leaving hover_color unset while pressed.
+            config_payload.setdefault("hover_color", self._local_defaults.get("hover_color"))
+            config_payload["hover"] = False
+            super().configure(**config_payload)
+        else:
+            config_payload = {}
+            for key in ("fg_color", "hover_color", "border_color", "text_color", "border_width", "corner_radius", "font"):
+                val = self._local_defaults.get(key)
+                if val is not None:
+                    config_payload[key] = val
+
+            config_payload["hover"] = True
+            if config_payload:
+                super().configure(**config_payload)

scustomtkinter/sctk_checkbox.py

@@ -0,0 +1,270 @@
+#!/usr/bin/python3
+"""
+sCTkCheckBox
+
+A theme-compliant binary selection checkbox widget. Inherits directly from
+ctk.CTkCheckBox so CustomTkinter handles native rendering, click toggling, and
+input locking; this class layers automatic light/dark theme resolution and a
+distinct enabled/disabled visual state on top.
+
+Base class order matters here: `class sCTkCheckBox(ctk.CTkCheckBox,
+ThemeableWidget)` puts the native CTk class first, so every `super()` call in
+this file's own methods resolves to ctk.CTkCheckBox -- and, beneath it,
+tkinter.Misc -- never to ThemeableWidget. ThemeableWidget's own
+configure()/cget()/_set_appearance_mode() overrides have been removed entirely
+for this reason (see themeable_widget.py's docstring); this widget owns all of
+its own runtime color-swapping logic.
+"""
+from typing import Any, Optional
+import customtkinter as ctk
+from .themeable_widget import ThemeableWidget, defer
+
+
+class sCTkCheckBox(ctk.CTkCheckBox, ThemeableWidget):
+    """Themeable checkbox.
+
+    Adds to native ctk.CTkCheckBox:
+      - Automatic light/dark theme resolution from sCTkThemes.json (via
+        ThemeableWidget.__init__ -- see that class's docstring for what it does,
+        and just as importantly, what it no longer does).
+      - A distinct enabled/disabled visual state, tracked in
+        self._custom_current_state and swapped via _update_current_visual_state().
+      - Pygubu Designer property introspection for a handful of properties via
+        a single-argument configure() call.
+
+    Every color this widget applies, including the checkmark itself, comes
+    from sCTkThemes.json -- checkmark_color was added as a real theme key
+    during this project's audit; previously the theme block didn't define it
+    at all, so the checkmark silently always used CTkCheckBox's native default
+    regardless of theme.
+
+    Colors are passed through to configure() as raw (light, dark) tuples rather
+    than pre-resolved to a single value, so CustomTkinter's own appearance-mode
+    tracking should repaint them automatically on a light/dark switch -- the
+    same approach validated on sCTkComboBox, sCTkSegmentedButton, and
+    sCTkButtonPrimary. Not separately re-confirmed for this specific widget.
+
+    Unlike the button family, this widget already used CTk's native
+    state="disabled"/state="normal" rather than manual event unbinding, so its
+    click-blocking was never suspected to be broken the way the buttons' was.
+    The color-then-state call order was reversed during this audit (state is
+    now set first, colors reapplied second via after_idle) as a precaution
+    based on a race condition confirmed on sCTkButtonPrimary between CTk's own
+    state-change repaint and an immediately-following manual color update --
+    this specific reordering has not been independently confirmed necessary
+    for this widget, only carried over as a defensive measure.
+    """
+
+    def __init__(self, master: Optional[Any] = None, **kw: Any) -> None:
+        """
+        Args:
+            master: Parent container.
+            **kw: Any native CTkCheckBox argument, or a theme-key override
+                (see the "sCTkCheckBox" block in sCTkThemes.json, including its
+                disabled_map sub-block).
+        """
+        # 1. Fire our shared theme logic first. This resolves final_kw
+        # (construction-time properties) and the disabled color map. See
+        # ThemeableWidget.__init__ for what actually happens here.
+        # NO PLACEHOLDER TEXT. CustomTkinter defaults `text` to the class
+        # name, so a CTkCheckBox built without text reads "CTkCheckBox". Nothing wants
+        # that in a real interface, and the Designer made it worse: clearing
+        # the text field removes the property, the canvas rebuilds the widget
+        # from what is left, and the placeholder appeared in place of the
+        # blank that was asked for.
+        kw.setdefault("text", "")
+        ThemeableWidget.__init__(self, kw)
+
+        # 2. Deep-copy the resolved map onto this instance, so later changes
+        # here never leak back into the shared theme registry.
+        self._local_defaults = dict(self.final_kw)
+        self._custom_disabled_map = dict(self._widget_disabled_map)
+
+        # 3. Initialize CustomTkinter natively with the clean final kwargs array.
+        super().__init__(master, **self.final_kw)
+        self._custom_current_state = "normal"
+
+        # 4. Register lifecycle handshake hook, notifying Pygubu-style consumers
+        # that construction is complete.
+        self._finalize_themeable_lifecycle()
+
+    def _set_appearance_mode(self, mode_string: str) -> None:
+        """
+        Forwards CustomTkinter's internal light/dark mode change notification to
+        the native widget.
+
+        No longer manually re-triggers _update_current_visual_state(). That
+        method now passes raw (light, dark) tuples straight through to
+        configure() instead of pre-resolving to a single color, so CTk's own
+        appearance-mode tracking should repaint correctly on its own -- the
+        same approach validated on sCTkComboBox, sCTkSegmentedButton, and
+        sCTkButtonPrimary.
+
+        Args:
+            mode_string: The new appearance mode ("Light" or "Dark"), as passed
+                by CustomTkinter's internal appearance-mode change machinery.
+        """
+        if hasattr(super(), "_set_appearance_mode"):
+            try:
+                super()._set_appearance_mode(mode_string)
+            except Exception:
+                pass
+
+    def configure(self, *args: Any, **kwargs: Any) -> Any:
+        """
+        Standard widget configuration, with Pygubu/positional-argument handling.
+
+        Args:
+            *args: At most one positional argument is meaningful:
+                - a dict: merged into kwargs and processed normally below.
+                - the literal string "state": returns a Tkinter-style
+                  (name, name, name, default, current) tuple.
+                - one of "fg_color"/"border_color"/"text_color"/"hover_color"/
+                  "checkmark_color": returns the same style of tuple, with
+                  `current` reflecting the disabled or normal value as
+                  appropriate. Note the returned value is str(value), where
+                  value may itself be a (light, dark) tuple rather than a
+                  single resolved color -- a known limitation shared with the
+                  wider Pygubu-query investigation set aside elsewhere in this
+                  project, not fixed here.
+                - anything else: forwarded directly to the native widget's
+                  configure(), which does not support single-argument property
+                  queries for arbitrary properties (same limitation).
+            **kwargs: Standard CTkCheckBox configuration options, plus: passing
+                `state=...` routes through self.state() rather than being
+                forwarded as-is.
+
+        Returns:
+            The query tuple described above for the single-argument case, or
+            whatever super().configure() returns for the keyword-argument case
+            (typically None).
+        """
+        if len(args) == 1:
+            if isinstance(args[0], dict):
+                kwargs = {**args[0], **kwargs}
+            else:
+                pname = args[0]
+                if pname == "state":
+                    return ("state", "state", "state", "normal", str(self.state()))
+
+                if pname in ["fg_color", "border_color", "text_color", "hover_color", "checkmark_color"]:
+                    current_state = str(self.state()).lower()
+                    val = self._custom_disabled_map.get(pname) if current_state == "disabled" else self._local_defaults.get(pname)
+                    return (pname, pname, pname, self._query_value(self._theme_default(pname)), self._query_value(val))
+
+                return self._configure_query(pname)
+
+        # Runtime overrides have to reach the map a repaint reads, or
+        # _apply_theme_colors() puts the theme value straight back -- see
+        # ThemeableWidget._record_theme_overrides().
+        self._record_theme_overrides(kwargs)
+
+        if "state" in kwargs:
+            self.state(kwargs.pop("state"))
+
+        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 automatically track whichever configure() a
+    # subclass defines. Without this line, calling .config(...) on an instance
+    # would silently skip this entire override and land on the native widget's
+    # configure() directly, bypassing theming and state handling entirely.
+    config = configure
+
+    def get_state(self) -> str:
+        """Equivalent to calling state() with no argument."""
+        return self.state()
+
+    def state(self, mode: Optional[str] = None) -> str:
+        """
+        Gets or sets the widget's enabled/disabled state.
+
+        Args:
+            mode: If None, returns the current state without changing anything.
+                Otherwise, only the literal string "disabled" (case-insensitive)
+                is treated as disabled; anything in ("normal", "enabled",
+                "active") is treated as enabled. Any other value falls through
+                without matching either branch, leaving the state unchanged.
+
+        Returns:
+            The resulting state ("normal" or "disabled", lowercase). An
+            earlier version of this method didn't return anything when setting
+            a mode (only the query branch returned a value) -- fixed here for
+            consistency with every other themed widget's state().
+        """
+        if mode is None:
+            return str(getattr(self, "_custom_current_state", "normal")).lower()
+
+        mode = mode.lower()
+        if mode in ("normal", "enabled", "active"):
+            self._custom_current_state = "normal"
+        elif mode == "disabled":
+            self._custom_current_state = "disabled"
+
+        self._update_current_visual_state()
+        return self._custom_current_state
+
+    def _update_current_visual_state(self) -> None:
+        """
+        Sets the native enabled/disabled flag, then recomputes and applies
+        this widget's colors from the theme file, deferred via after_idle.
+
+        Called after every state() change.
+
+        Native state is set FIRST, colors reapplied SECOND via after_idle --
+        this order is a precaution, not a confirmed fix for this widget
+        specifically. On sCTkButtonPrimary, an immediate color reapply
+        following a state change was found to lose a race against CTk's own
+        internal state-change repaint, leaving stale colors after repeated
+        disable/enable cycles. That fix is carried over here defensively;
+        see this class's docstring.
+
+        Passes raw (light, dark) tuples straight through to configure() instead
+        of resolving to a single color first, so CTk's native tracking can
+        handle appearance-mode repaints without help from _set_appearance_mode.
+        Every value here traces back to sCTkThemes.json; there are no
+        hardcoded colors in this method.
+        """
+        is_disabled = getattr(self, "_custom_current_state", "normal") == "disabled"
+
+        super().configure(state="disabled" if is_disabled else "normal")
+        defer(self, "idle", self._apply_theme_colors)
+
+    def _apply_theme_colors(self) -> None:
+        """
+        Applies fg_color, border_color, hover_color, text_color,
+        checkmark_color, border_width, and font from whichever theme map
+        matches the current state. Called only via after_idle from
+        _update_current_visual_state() -- see that method for why the
+        deferral exists.
+        """
+        is_disabled = getattr(self, "_custom_current_state", "normal") == "disabled"
+        target_map = self._custom_disabled_map if is_disabled else self._local_defaults
+
+        config_payload = {}
+        for key in ("fg_color", "border_color", "hover_color", "checkmark_color", "border_width", "font"):
+            val = target_map.get(key)
+            if val is not None:
+                config_payload[key] = val
+
+        # text_color is handled separately, because CTkCheckBox has its own
+        # text_color_disabled option and its draw code uses that whenever state
+        # is "disabled" -- overriding whatever text_color was set to. Swapping
+        # text_color out of disabled_map was therefore discarded at draw time
+        # and the theme key had no visible effect: setting it to yellow changed
+        # nothing.
+        #
+        # Both options are set, so CTk chooses between them as designed.
+        normal_text = self._local_defaults.get("text_color")
+        if normal_text is not None:
+            config_payload["text_color"] = normal_text
+        disabled_text = self._custom_disabled_map.get("text_color")
+        if disabled_text is not None:
+            config_payload["text_color_disabled"] = disabled_text
+
+        if config_payload:
+            super().configure(**config_payload)