scustomtkinter 0.2.1__py3-none-any.whl

scustomtkinter/themeable_widget.py

@@ -0,0 +1,938 @@
+#!/usr/bin/python3
+"""
+ThemeableWidget
+
+Shared __init__-time theme resolution and color-utility mixin for sCustomTkinter widgets.
+
+Scope note: earlier versions of this class also defined configure()/cget()/_set_appearance_mode()
+overrides, intended as shared runtime color-swapping logic used by every widget. Those methods are
+removed here because they were structurally unreachable. Every sCTk* widget declares its native CTk
+base class before ThemeableWidget (e.g. `class sCTkComboBox(ctk.CTkComboBox, ThemeableWidget)`), so
+Python's MRO always resolves super().configure()/cget() calls to the native CTk widget -- and beneath
+it, tkinter.Misc -- first. Both terminate the call chain without ever reaching ThemeableWidget. This
+holds even for a hypothetical widget that defines neither configure() nor cget() itself, since
+tkinter.Misc (an ancestor of every CTk widget) already implements both ahead of ThemeableWidget in
+the MRO. Verified empirically against the real widget files during the docs/coding audit, not just
+inferred from the class layout.
+
+What this class DOES provide, and is genuinely used by every widget:
+  - __init__: resolves this widget's block from sCTkThemes.json, merges it with any keyword
+    overrides passed to the constructor, and builds self.final_kw plus the disabled/pressed/alarm/
+    readonly color maps (self._widget_disabled_map / _widget_pressed_map / _widget_alarm_map /
+    _widget_readonly_map).
+  - _resolve_color / _convert_lists_to_tuples / _sanitize_value: color-normalization helpers,
+    called directly (via self.) by each widget's own visual-state logic.
+  - _finalize_themeable_lifecycle: Pygubu lifecycle hook, called directly by each widget's __init__.
+  - apply_theme: convenience method that re-applies self.final_kw via self.configure(). Because this
+    calls self.configure() (not super().configure()), it correctly dispatches to whichever configure()
+    the actual widget instance defines -- unlike the removed methods, this one isn't dead code.
+
+Each widget's own configure()/cget()/_set_appearance_mode() override is responsible for its own
+runtime color-swapping, because each widget needs a different set of properties (and, for buttons,
+a different state model -- normal/disabled/pressed/alarm) than any single shared method could know
+about without hardcoding every widget's valid property list in one place. See the docs audit notes
+for the reasoning behind not trying to re-centralize this.
+
+RUN-ONCE GUARD: __init__ now sets self._themeable_widget_initialized = True on its first call per
+instance, and returns immediately on any subsequent call. This matters specifically for widgets that
+compose an already-themed sCTk widget as their own base class (e.g. sCTkSelector(sCTkFrame,
+ThemeableWidget), sCTkTableview(sCTkScrollableFrame, ThemeableWidget)) -- without it, the base
+widget's own internal ThemeableWidget.__init__ call (triggered when the composite widget's
+super().__init__() cascades into it) would run a second time on the same instance, silently
+overwriting self.final_kw. See __init__'s own docstring for the full reasoning.
+"""
+import os
+import json
+import tkinter as tk
+import customtkinter as ctk
+
+
+# GLOBAL THEME REGISTRY POOL
+GLOBAL_THEME_REGISTRY = {}
+
+
+# ----------------------------------------------------------------------
+# Deferred calls that survive their widget being destroyed
+# ----------------------------------------------------------------------
+def defer(widget, ms, callback):
+    """
+    widget.after(ms, callback) -- or after_idle when ms is "idle" -- that is
+    safe if the widget is destroyed before it runs.
+
+    FIX (2026-11-11): closing a Designer preview printed
+    `invalid command name "...<lambda>"` for every widget with a call still
+    pending. tkinter registers a deferred callback as a Tcl command OF THE
+    WIDGET, and destroying the widget deletes that command -- so a check
+    inside the callback cannot help: there is no callback left to run. The
+    call is registered with the application's root instead, which outlives
+    the widget, and only reaches `callback` while the widget still exists.
+
+    Returns the id, for cancel_deferred(). Errors in `callback` are NOT
+    swallowed; only the widget's own disappearance is.
+    """
+    root = widget._root()
+
+    def run():
+        try:
+            alive = widget.winfo_exists()
+        except tk.TclError:
+            return
+        if alive:
+            callback()
+
+    if ms == "idle":
+        return root.after_idle(run)
+    return root.after(ms, run)
+
+
+def cancel_deferred(widget, after_id):
+    """Cancels a call made with defer(); harmless if it already ran or is None."""
+    if after_id is None:
+        return
+    try:
+        widget._root().after_cancel(after_id)
+    except (tk.TclError, ValueError):
+        pass
+
+
+def load_initial_framework_themes():
+    """Idempotent startup hook to pull themes.json safely without dropping imports."""
+    global GLOBAL_THEME_REGISTRY
+    if GLOBAL_THEME_REGISTRY:
+        return
+
+    local_user_workspace = os.path.normpath(os.path.join(os.getcwd(), "sCTkThemes.json"))
+
+    # FIXED DIRECTORY COORDINATES: Look inside your actual bundled assets folder
+    current_script_dir = os.path.dirname(os.path.abspath(__file__))
+    bundled_library_default = os.path.normpath(os.path.join(current_script_dir, "assets", "sCTkThemes.json"))
+
+    theme_target = local_user_workspace if os.path.exists(local_user_workspace) else bundled_library_default
+
+    try:
+        if os.path.exists(theme_target):
+            with open(theme_target, "r", encoding="utf-8") as file:
+                GLOBAL_THEME_REGISTRY = json.load(file)
+        else:
+            # Fallback empty profile dictionary so your widget protections don't crash if files vanish
+            GLOBAL_THEME_REGISTRY = {}
+    except Exception as err:
+        print(f"sCustomTkinter System Warning -> Could not parse theme layout tracking: {err}")
+        GLOBAL_THEME_REGISTRY = {}
+
+
+# NATIVE INITIALIZATION PASS: Safe, unblocked startup invocation
+load_initial_framework_themes()
+
+
+def default_i18n_translator(value):
+    return value
+
+def default_fo_callback(widget):
+    pass
+
+def default_image_loader(master, image_name: str, size=None):
+    if not image_name: return None
+    try:
+        if isinstance(image_name, ctk.CTkImage): return image_name
+        img_size = size if size else (24, 24)
+        from PIL import Image
+        pil_img = Image.open(image_name)
+        return ctk.CTkImage(light_image=pil_img, dark_image=pil_img, size=img_size)
+    except Exception:
+        return None
+
+
+def parse_list_property(value, default=None):
+    """
+    Parse a list-valued widget property from any of the formats this library
+    and Pygubu Designer produce, returning a clean list of stripped strings.
+
+    WHY THIS EXISTS. Before this function, seven widgets each parsed their own
+    list property and no two agreed:
+
+        sCTkTableview.columns     comma split, stripped
+        sCTkSelector.items        ast.literal_eval only
+        sCTkDialSelector.labels   literal_eval in __init__, but a plain
+                                  comma split with NO quote stripping in
+                                  configure() -- so the same value parsed
+                                  differently depending on when it was set
+        sCTkFileExplorer.filetypes   three different implementations, in one file
+        sCTkPathChooser.filetypes    literal_eval
+        sCTkSpinbox.values           shlex.split when no comma is present
+
+    The user-visible consequence was that every widget wanted a different
+    format for the same kind of property, and the Designer's inspector gave no
+    hint which. Entering "AM, FM, LSB" into a dial produced labels with leading
+    spaces; the same string in a Tableview worked correctly.
+
+    Accepts, in order of preference:
+      - an actual list or tuple, returned with each element stripped
+      - a Python literal: "['A', 'B']" or "('A', 'B')"
+      - a bare comma-separated string: "A, B, C"
+
+    Empty input returns `default` (or an empty list), never None, so callers
+    can iterate the result unconditionally.
+
+    Deliberately does NOT accept space separation. sCTkSpinbox alone supported
+    it via shlex, which means "Meat Loaf" was two values there and one value
+    everywhere else -- surprising enough to be worth dropping rather than
+    spreading. Quote a value containing a comma if you need one.
+
+    Args:
+        value: The raw property value, in any of the forms above.
+        default: Returned when value is empty or unparseable. Defaults to [].
+
+    Returns:
+        A list of stripped strings.
+    """
+    if default is None:
+        default = []
+
+    if value is None:
+        return list(default)
+
+    if isinstance(value, (list, tuple)):
+        cleaned = [str(item).strip() for item in value]
+        return [item for item in cleaned if item] or list(default)
+
+    text = str(value).strip()
+    if not text:
+        return list(default)
+
+    # Python literal form, as written by older .ui files and by the Selector's
+    # own inspector default of "['Item 1', 'Item 2']".
+    if text[0] in "[(":
+        try:
+            import ast
+            parsed = ast.literal_eval(text)
+            if isinstance(parsed, (list, tuple)):
+                cleaned = [str(item).strip() for item in parsed]
+                return [item for item in cleaned if item] or list(default)
+        except (ValueError, SyntaxError):
+            # Malformed literal -- fall through to the comma split below, which
+            # handles "[A, B]" (unquoted, not valid Python) correctly.
+            pass
+
+    # Bare comma-separated form. Brackets and quotes are stripped so a
+    # half-formed literal still parses the way the user obviously intended.
+    text = text.strip("[]()")
+    return [item.strip().strip("\"'") for item in text.split(",")
+            if item.strip().strip("\"'")] or list(default)
+
+
+def parse_font_property(value, default=None):
+    """
+    Parse a font from any of the forms a designer or a theme file produces,
+    returning the tuple CustomTkinter and Tk canvas items expect.
+
+    WHY THIS EXISTS. Pygubu's `fontentry` editor emits a Tk font
+    specification, not a tuple: a family, brace-wrapped when it contains a
+    space, then a size, then zero or more styles.
+
+        {Comic Sans MS} 14 bold
+        Arial 9 bold
+
+    The trap is what it emits for NO style selected:
+
+        {American Typewriter} 12 {}
+
+    "{}" is Tk's empty-list literal. Passed through as a style, Tk rejects it
+    outright when the tuple reaches a canvas item:
+
+        _tkinter.TclError: unknown font style ""
+
+    Two builder objects had their own copy of this parser and both got it
+    wrong the same way, which is why it lives here now -- the same argument
+    that consolidated seven list parsers into parse_list_property().
+
+    Args:
+        value: The raw font value: a tuple, a Tk font string, or None.
+        default: Returned when value is empty or unparseable. A caller with a
+            theme value to fall back on should pass it here.
+
+    Returns:
+        A (family, size) or (family, size, style) tuple, or `default`.
+    """
+    if not value:
+        return default
+
+    if isinstance(value, (tuple, list)):
+        if len(value) < 2:
+            return default
+        family, size = value[0], value[1]
+        styles = [str(s) for s in value[2:]
+                  if s and str(s).strip() not in ("", "{}", "normal", "roman")]
+    else:
+        text = str(value).strip()
+        if not text:
+            return default
+        if text.startswith("{"):
+            end = text.find("}")
+            if end == -1:
+                return default
+            family, rest = text[1:end], text[end + 1:].split()
+        else:
+            parts = text.split()
+            family, rest = parts[0], parts[1:]
+        if not rest:
+            return default
+        size = rest[0]
+        styles = [s for s in rest[1:]
+                  if s and s not in ("{}", "normal", "roman")]
+
+    try:
+        size = int(size)
+    except (TypeError, ValueError):
+        return default
+
+    joined = " ".join(styles).strip()
+    return (str(family), size, joined) if joined else (str(family), size)
+
+
+class ThemeableWidget:
+    def __init__(self, kwargs: dict):
+        """
+        Shared base mixin that resolves global theme lookups via introspection,
+        extracts styling options, handles nested map sanitization, and filters
+        custom layout properties to prevent native framework validation failures.
+
+        RUN-ONCE GUARD: if a widget composes an already-themed sCTk widget as its
+        own base class (e.g. sCTkSelector(sCTkFrame, ThemeableWidget)), that base
+        widget's own __init__ calls ThemeableWidget.__init__ again internally when
+        super().__init__() cascades into it. Without a guard, this second call
+        would run in full -- looking up the theme block again via
+        self.__class__.__name__ (which is always the OUTERMOST class, e.g.
+        "sCTkSelector", regardless of which base class's code is currently
+        executing) and completely overwriting self.final_kw from scratch. For a
+        widget that forwards its full final_kw to super().__init__() (like
+        sCTkSelector), this second call happens to be a harmless no-op today,
+        since it's re-merging already-merged data onto itself -- but that's
+        incidental, not guaranteed, and fragile against future changes. For a
+        widget that only forwards a few explicit constructor arguments (like
+        sCTkTableview passing just master/width/height), the second call is
+        actively destructive: it replaces the correctly-built final_kw with a far
+        sparser one, silently discarding whatever the first call correctly
+        resolved. This guard makes ThemeableWidget.__init__ idempotent per
+        instance, the same way a C header's #ifndef/#define guard prevents a
+        header's contents from being processed twice -- the first call does the
+        real work and marks itself done; every subsequent call on the same
+        instance returns immediately.
+        """
+        if getattr(self, "_themeable_widget_initialized", False):
+            return
+        self._themeable_widget_initialized = True
+
+        # 1. PYGUBU UTILITY PARAMETER INTERCEPTION & EXTRIPATION:
+        # We pop these completely out of the incoming kwargs pass before running any
+        # dictionary loops. This guarantees CustomTkinter never encounters them!
+        self.translator = kwargs.pop("translator", default_i18n_translator)
+        self.on_first_object_cb = kwargs.pop("on_first_object_cb", default_fo_callback)
+        self.image_loader = kwargs.pop("image_loader", default_image_loader)
+        self.data_pool = kwargs.pop("data_pool", None)
+
+        # _THEME_BLOCK_NAME lets a subclass declare which theme block it reads,
+        # instead of the lookup always using its own class name.
+        #
+        # Needed by the Pygubu Designer preview subclasses: sCTkTableviewForPreview,
+        # sCTkSelectorForPreview and friends exist only to expose internals so the
+        # Designer can select them, but their class names have no theme block --
+        # so the lookup found nothing, final_kw came back empty, and any widget
+        # with fail-loud key validation raised KeyError instead of rendering.
+        #
+        # Also useful outside the Designer: a subclass of sCTkButtonPrimary can
+        # now inherit its parent's theme rather than silently losing it.
+        class_name = getattr(self, "_THEME_BLOCK_NAME", None) or self.__class__.__name__
+        theme_defaults = GLOBAL_THEME_REGISTRY.get(class_name) or {}
+
+        if not isinstance(theme_defaults, dict):
+            raise KeyError(f"CRITICAL STYLING EXCEPTION: Registry corrupted for type: '{class_name}'...")
+
+        # Global unresolved null traffic check
+        for style_key, style_value in theme_defaults.items():
+            if isinstance(style_value, dict):
+                for sub_key, sub_value in style_value.items():
+                    if sub_value is None:
+                        raise ValueError(f"Null theme parameter encountered at ['{class_name}']['{style_key}']['{sub_key}']")
+            elif style_value is None:
+                raise ValueError(f"Null theme parameter encountered at ['{class_name}']['{style_key}']")
+
+        # Nested color map extractions
+        self._widget_disabled_map = ThemeableWidget._convert_lists_to_tuples(theme_defaults.get("disabled_map") or {})
+        self._widget_pressed_map = ThemeableWidget._convert_lists_to_tuples(theme_defaults.get("pressed_map") or {})
+        self._widget_alarm_map = ThemeableWidget._convert_lists_to_tuples(theme_defaults.get("alarm_map") or {})
+        # readonly_map: added to support a genuine three-state model (normal/
+        # readonly/disabled) on sCTkEntryPrimary/Secondary, for widgets like
+        # sCTkSpinbox that need ttk.Spinbox's real readonly semantics (arrows
+        # stay clickable, typing is blocked) rather than collapsing everything
+        # non-disabled into "normal". Added here, not as an Entry-specific
+        # hack, so any future widget can use the same pattern.
+        self._widget_readonly_map = ThemeableWidget._convert_lists_to_tuples(theme_defaults.get("readonly_map") or {})
+
+        forbidden_keys = {"disabled_map", "pressed_map", "alarm_map", "readonly_map"}
+        CUSTOM_VECTOR_KEYS = {
+            "dial_color", "shadow_color", "text_color", "pointer_color",
+            "pointer_glow_color", "disabled_text_color", "disabled_dial_color",
+            "disabled_dimple_glow", "diameter"
+        }
+
+        self.final_kw = {}
+        is_vector_widget = any(v_key in theme_defaults for v_key in ["dial_color", "pointer_color", "diameter"])
+
+        active_vector_guards = set(CUSTOM_VECTOR_KEYS)
+        if not is_vector_widget:
+            active_vector_guards.discard("text_color")
+
+        for key, value in theme_defaults.items():
+            if key not in forbidden_keys and key not in active_vector_guards:
+                self.final_kw[key] = ThemeableWidget._sanitize_value(key, value)
+
+        for key, value in kwargs.items():
+            if value is not None and key not in forbidden_keys and key not in active_vector_guards:
+                self.final_kw[key] = ThemeableWidget._sanitize_value(key, value)
+
+        # 2. AUTOMATED STRING TRANSLATION PASSTHROUGH:
+        if "text" in self.final_kw:
+            self.final_kw["text"] = self.translator(self.final_kw["text"])
+        if "placeholder_text" in self.final_kw:
+            self.final_kw["placeholder_text"] = self.translator(self.final_kw["placeholder_text"])
+        if "label_text" in self.final_kw:
+            self.final_kw["label_text"] = self.translator(self.final_kw["label_text"])
+
+        # 3. MODERN HIGH-DPI ICON VECTOR UPGRADE PASS:
+        if "image" in self.final_kw and isinstance(self.final_kw["image"], str):
+            self.final_kw["image"] = self.image_loader(None, self.final_kw["image"])
+
+        # NOTE: self._state is set here for backward compatibility, but as of this audit
+        # no reviewed widget reads it correctly via a reachable code path (the one that
+        # did -- sCTkSegmentedButton -- was doing so by mistake; see its own fix notes).
+        # Left in place rather than removed until the remaining widgets are audited.
+        self._state = "normal"
+
+    def apply_theme(self):
+        """
+        Re-applies self.final_kw via self.configure(). This calls self.configure(), not
+        super().configure(), so it correctly dispatches to whichever configure() the
+        actual widget instance defines -- this method is NOT dead code like the removed
+        configure()/cget() overrides were.
+        """
+        if hasattr(self, "configure"):
+            self.configure(**self.final_kw)
+
+    def _finalize_themeable_lifecycle(self):
+        """POST-COMPILATION LIFECYCLE HOOK PASS: Dispatches object triggers cleanly up to Pygubu."""
+        if hasattr(self, "on_first_object_cb") and self.on_first_object_cb:
+            try: self.on_first_object_cb(self)
+            except Exception: pass
+
+    @classmethod
+    def _convert_lists_to_tuples(cls, target_dict: dict) -> dict:
+        output = {}
+        for k, v in target_dict.items():
+            if isinstance(v, list) and len(v) == 2:
+                if "transparent" in v: output[k] = "transparent"
+                else: output[k] = tuple(v)
+            elif isinstance(v, str) and k in ("fg_color", "text_color", "border_color"):
+                if v == "transparent": output[k] = "transparent"
+                else: output[k] = (v, v)
+            else:
+                output[k] = v
+        return output
+
+    @classmethod
+    def _sanitize_value(cls, key, value):
+        if key in ("fg_color", "text_color", "border_color", "button_color", "button_hover_color"):
+            if isinstance(value, list) and len(value) == 2:
+                if "transparent" in value: return "transparent"
+                return tuple(value)
+            if isinstance(value, tuple) and len(value) == 2:
+                if "transparent" in value: return "transparent"
+                return value
+            if isinstance(value, str):
+                if value == "transparent": return "transparent"
+                return (value, value)
+        if isinstance(value, list):
+            return tuple(value)
+        return value
+
+    def _resolve_color(self, color_value):
+        if color_value == "transparent": return "transparent"
+        if isinstance(color_value, (tuple, list)):
+            current_mode = str(ctk.get_appearance_mode()).lower()
+            mode_idx = 1 if current_mode == "dark" else 0
+            return color_value[mode_idx]
+        return color_value
+
+    def _record_theme_overrides(self, kwargs):
+        """
+        Records a runtime property change into the active theme map, so a later
+        repaint does not discard it.
+
+        THE PROBLEM THIS SOLVES is general to the library. Widgets repaint
+        themselves from _local_defaults -- a snapshot of the theme block taken
+        at construction -- whenever the state changes. Nothing wrote runtime
+        changes back into that snapshot, so:
+
+            widget.configure(fg_color="red")   # widget turns red
+            widget.state("disabled")
+            widget.state("normal")             # theme colour returns
+
+        In the Designer it was immediate rather than eventual, because
+        properties are applied in an order that sets `state` after the colours.
+
+        Only keys the theme ALREADY defines are updated. That is precisely the
+        set a repaint will reapply, so enumerating per-widget key lists is
+        unnecessary -- and it leaves native options the theme says nothing
+        about untouched.
+
+        THE CHANGE ALWAYS GOES TO THE NORMAL MAP, whatever state the widget is
+        in. That is not an oversight -- it follows from the Designer having ONE
+        field per property while this library keeps several maps.
+
+        An earlier version chose the map by current state, so that a colour set
+        on a disabled widget was visible immediately. It made a single field
+        mean different things at different moments:
+
+            normal:   set fg_color green   -> normal map green
+            disabled: clear fg_color       -> DISABLED map reset, normal
+                                              map still green
+            normal:   green returns
+
+        which reads as the clear having failed. One field, one meaning.
+
+        A property with its own separate field is the exception, and is handled
+        explicitly below -- text_color_disabled is the only one.
+
+        Call once near the top of a widget's configure(), before the values are
+        consumed or forwarded.
+
+        Args:
+            kwargs: The keyword dict passed to configure(). Not modified.
+        """
+        defaults = getattr(self, "_local_defaults", None)
+        if not defaults:
+            return
+
+        # Snapshot the THEME before the first override lands on it.
+        #
+        # Recording overrides into _local_defaults makes a repaint keep them,
+        # which is the point -- but it also destroys the notion of a "default".
+        # The Designer reads the default from the same dict, so after setting
+        # fg_color yellow the reported default WAS yellow, and clearing the
+        # field restored the override instead of the theme.
+        #
+        # Taken lazily rather than in __init__ so widgets need no constructor
+        # change: the first override is the last moment the maps are still
+        # pristine.
+        self._snapshot_theme_defaults()
+
+        disabled_map = getattr(self, "_custom_disabled_map", None)
+        changed = False
+
+        for key, value in kwargs.items():
+            if value == "":
+                continue
+
+            # text_color_disabled and disabled_map's text_color are the SAME
+            # thing under two names.
+            #
+            # The first is CustomTkinter's native option; the second is this
+            # library's theme key, and a repaint feeds one into the other. So a
+            # value typed into the Designer's text_color_disabled field was not
+            # recorded here -- the theme block does not contain that name -- and
+            # the next repaint overwrote it from disabled_map. The field looked
+            # inert.
+            #
+            # Recording it against the theme key it feeds makes the native
+            # property live, and keeps a single source for the colour.
+            if key == "text_color_disabled":
+                if disabled_map is not None:
+                    disabled_map["text_color"] = value
+                    changed = True
+                continue
+
+            if key in defaults:
+                defaults[key] = self._normalise_override(key, value)
+                changed = True
+
+        if changed:
+            self._repaint_after_override()
+
+    def _repaint_after_override(self):
+        """
+        Re-runs the widget's own colour pass after a theme key changes.
+
+        DERIVED values are the reason. Several widgets compute one colour from
+        another -- sCTkOptionMenuSecondary sets button_color from fg_color so
+        the arrow blends into the control, and the segmented button derives its
+        unselected fill the same way. Those are worked out in the repaint
+        method, which runs on a state change and NOT on a plain configure().
+
+        So clearing fg_color in the Designer put the theme value back on the
+        native option and left the derived ones holding the override: the
+        background reverted while the arrow, or the segment fill, stayed red.
+
+        The repaint method is found by name because widgets do not agree on
+        one. Guarded against re-entry, since a repaint configures the widget
+        and would otherwise call back into here.
+        """
+        if getattr(self, "_in_override_repaint", False):
+            return
+        # The list is in preference order, and covers every repaint entry
+        # point in the library. Canvas-drawing widgets are included because
+        # they have no colour-application method as such -- redrawing IS how
+        # they apply colours -- and without them an override was recorded but
+        # not shown until something else forced a redraw.
+        for name in ("_update_current_visual_state",
+                     "_apply_custom_theme_colors",
+                     "_apply_theme_colors",
+                     "_draw_dial_base",     # the dial family
+                     "_draw_meter"):        # sCTkSMeter, sCTkSMeterBar
+            method = getattr(self, name, None)
+            if method is None:
+                continue
+            self._in_override_repaint = True
+            try:
+                method()
+            except Exception:
+                # A widget not fully built yet. Losing one repaint is
+                # cosmetic; raising here would break the property edit.
+                pass
+            finally:
+                self._in_override_repaint = False
+            return
+
+    def _normalise_override(self, key, value):
+        """
+        Puts a value from the Designer into the shape the theme maps hold.
+
+        Theme colours are stored as (light, dark) tuples, and widgets rely on
+        that: several call tuple() on them directly. The inspector supplies a
+        plain string, so storing it raw meant a widget did tuple("red") and
+        got ('r', 'e', 'd') -- which CustomTkinter rejected:
+
+            color ('r', 'e', 'd') must be string ('transparent' or
+            'color-name' or 'hex-color') or tuple of two strings
+
+        The shape is taken from the value ALREADY in the map rather than from
+        a list of key names. _convert_lists_to_tuples() special-cases only
+        fg_color, text_color and border_color, so a string given for
+        selected_color or hover_color would still have been stored raw and
+        exploded the same way -- and every widget names its colours
+        differently.
+
+        Args:
+            key: The property name.
+            value: The raw value.
+
+        Returns:
+            The value in theme-map shape.
+        """
+        if value == "transparent":
+            return "transparent"
+
+        if isinstance(value, (list, tuple)):
+            if len(value) == 2:
+                return "transparent" if "transparent" in value else tuple(value)
+            return value
+
+        if isinstance(value, str) and key not in self._LIST_PROPERTIES:
+            existing = (getattr(self, "_local_defaults", {}) or {}).get(key)
+            # A pair of STRINGS in the map means this key is a (light, dark)
+            # colour, so a single string has to become one.
+            #
+            # _LIST_PROPERTIES is excluded first: a two-item `values` list looks
+            # exactly like a colour pair, and would otherwise be stored as
+            # ('["A","B"]', '["A","B"]') -- the same collision that made
+            # _query_value() take the property name rather than guess.
+            if (isinstance(existing, (list, tuple)) and len(existing) == 2
+                    and all(isinstance(x, str) for x in existing)):
+                return (value, value)
+
+        return value
+
+    def _snapshot_theme_defaults(self):
+        """
+        Keeps an untouched copy of the theme maps, once, for reporting
+        defaults.
+
+        See _record_theme_overrides() for why this is needed and why it is
+        lazy.
+        """
+        if getattr(self, "_pristine_defaults", None) is not None:
+            return
+        self._pristine_defaults = dict(getattr(self, "_local_defaults", {}) or {})
+        disabled_map = getattr(self, "_custom_disabled_map", None)
+        self._pristine_disabled = dict(disabled_map or {})
+
+    def _theme_default(self, key):
+        """
+        The value the THEME gives a key, ignoring any runtime override.
+
+        Use this for the `default` slot of a configure() query, so clearing a
+        field in the Designer returns to the theme rather than to whatever was
+        last set.
+
+        Args:
+            key: The property name.
+
+        Returns:
+            The theme's value, or None.
+        """
+        pristine = getattr(self, "_pristine_defaults", None)
+        if pristine is None:
+            return (getattr(self, "_local_defaults", {}) or {}).get(key)
+        return pristine.get(key)
+
+    def _theme_disabled_default(self, key):
+        """The theme's disabled_map value for a key, ignoring overrides."""
+        pristine = getattr(self, "_pristine_disabled", None)
+        if pristine is None:
+            return (getattr(self, "_custom_disabled_map", {}) or {}).get(key)
+        return pristine.get(key)
+
+    def _configure_query(self, pname, defaults=None):
+        """
+        Tkinter-style property query for a name this widget doesn't handle
+        itself.
+
+        Pygubu calls configure(name) to read a property's default whenever a
+        field is blanked in the Designer inspector, and expects a five-element
+        tuple: (name, database_name, database_class, default, current).
+
+        Forwarding the name to a native configure() does NOT produce that.
+        CustomTkinter declares configure(self, require_redraw=False, **kwargs),
+        so the property NAME arrives as require_redraw and the call returns
+        None -- which pygubu then hands straight to _set_property():
+
+            Failed to set property 'height' ... float() argument must be a
+            string or a real number, not 'NoneType'
+
+        Args:
+            pname: The property being queried.
+            defaults: Optional {name: default} for properties whose native
+                default is known from THIS widget's own constructor. Anything
+                absent reports its current value as its default, which makes
+                blanking that field a no-op.
+
+                Only state a default you can point at. A guessed default is
+                worse than none, because the guess gets applied.
+
+        Returns:
+            A Tkinter-style five-tuple.
+        """
+        try:
+            current = self.cget(pname)
+        except Exception:
+            current = None
+        # Default resolution, in order:
+        #   1. an explicit default the caller declared
+        #   2. this widget's resolved THEME value
+        #   3. the current value
+        #
+        # Step 2 is what makes clearing a field in the Designer mean something.
+        # Without it the default was whatever the property already held, so
+        # blanking reported "the default is what you have" and nothing changed
+        # -- no error, but no revert either. For a themed widget the theme IS
+        # the default, and _local_defaults holds it already resolved.
+        #
+        # Step 3 remains for properties the theme says nothing about, where a
+        # no-op is still better than a guess.
+        if defaults and pname in defaults:
+            default = defaults[pname]
+        else:
+            # The PRISTINE theme value, not _local_defaults.
+            #
+            # _record_theme_overrides() writes runtime changes into
+            # _local_defaults so a repaint keeps them -- which means that dict
+            # no longer holds the theme's value. Reading the default from it
+            # made clearing a field in the Designer restore the last override
+            # instead of the theme. _theme_default() reads the untouched copy.
+            theme_value = self._theme_default(pname)
+            default = current if theme_value is None else theme_value
+
+        # A (light, dark) pair has to be resolved to ONE colour here.
+        #
+        # Everything in this library stores colours as pairs so CustomTkinter's
+        # appearance tracking can follow the mode. But pygubu takes whatever
+        # this returns and hands it back to configure(), where Tk sees the
+        # stringified tuple as a colour name:
+        #
+        #   unknown color name "('#1A4375', '#2471A3')"
+        #
+        # _resolve_color() picks the half matching the current appearance mode,
+        # which is the value actually on screen -- and so the right answer to
+        # "what is this property now".
+        return (pname, pname, pname,
+                self._query_value(default, pname),
+                self._query_value(current, pname))
+
+    # Properties whose value is a LIST, not a colour pair. Both arrive as two
+    # strings when there are two options, and no test on the value can tell
+    # ["Apple", "Pear"] from ("white", "black") -- bare colour names look
+    # exactly like ordinary option text. The property NAME is the only
+    # reliable signal, so it is passed in rather than inferred.
+    _LIST_PROPERTIES = frozenset({"values", "labels", "columns", "items",
+                                  "filetypes"})
+
+    # Properties whose empty string is CONTENT, not a request to clear.
+    #
+    # Every configure() in this library drops `""`, and for theme values that
+    # is right: it is what the Designer sends to mean "fall back to the
+    # theme", and dropping it turns clearing an undefined property into a
+    # no-op rather than a `color is None` error (see _query_value).
+    #
+    # For these it is wrong. An empty string is an ordinary thing to ask for
+    # -- a label with nothing to say, an entry with no placeholder -- and
+    # dropping it left the OLD text in place. The call did nothing, silently,
+    # and the widget went on showing whatever it said last:
+    #
+    #     label.configure(text="")      # label still reads "vfo b 14.012.000"
+    #
+    # None of these is a theme key, so letting "" through cannot reach the
+    # theme maps: _record_theme_overrides only touches keys the theme block
+    # already defines.
+    #
+    # label_text is the caption of the labelled and scrollable frames --
+    # CTkScrollableFrame's own name for it.
+    _CONTENT_KEYS = frozenset({"text", "placeholder_text", "label_text"})
+
+    def _drop_cleared(self, kwargs):
+        """
+        Removes theme values cleared to "" from kwargs, in place.
+
+        Content keys are kept, so `configure(text="")` really does blank the
+        text. Call this instead of filtering `if v == ""` by hand -- the
+        hand-written version was in every widget, and every copy dropped
+        content along with the theme values.
+
+        Args:
+            kwargs: The keyword dict about to be forwarded to the native
+                widget. Modified in place.
+        """
+        for key, value in list(kwargs.items()):
+            if value == "" and key not in self._CONTENT_KEYS:
+                kwargs.pop(key)
+
+    def _query_value(self, value, pname=None):
+        """
+        Renders one property value in a form a configure() call can accept.
+
+        Colour pairs are resolved to the half in use; everything else is passed
+        through untouched. Deliberately NOT str() -- a number must stay a
+        number, or the widget receives "10" where it expects 10.
+        """
+        # NOTHING becomes "", not None.
+        #
+        # A theme block need not define every property a widget's query
+        # branch lists -- sCTkButtonPrimary has no border_color at all,
+        # because it is a solid-fill button, and sCTkProgressBar the same.
+        # The default reported for such a key was None, and pygubu APPLIES
+        # the default when a field is cleared:
+        #
+        #     Failed to set property 'border_color' ...
+        #     Error: color is None, for transparency set color='transparent'
+        #
+        # An empty string is dropped by every configure() in this library --
+        # through _drop_cleared() -- so clearing an undefined property becomes
+        # the no-op it should always have been. Content keys such as `text`
+        # are the exception; see _CONTENT_KEYS.
+        if value is None:
+            return ""
+
+        # A list property is JSON, whatever its length. Checked FIRST, because
+        # a two-option list is indistinguishable from a colour pair by
+        # inspection alone.
+        if pname in self._LIST_PROPERTIES:
+            try:
+                import json
+                return json.dumps(list(value))
+            except (TypeError, ValueError):
+                return value
+
+        # A (light, dark) colour pair.
+        if (isinstance(value, (tuple, list)) and len(value) == 2
+                and all(isinstance(v, str) for v in value)):
+            try:
+                return self._resolve_color(value)
+            except Exception:
+                return value[0]
+
+        # A live CTkFont is not something a font property can be set FROM.
+        # cget("font") hands one back, and pygubu's font editor expects a Tk
+        # font specification it can parse:
+        #
+        #   expected string or bytes-like object, got 'CTkFont'
+        #
+        # It is rendered as "{Family} size style" -- the same form the editor
+        # produces, so a value read out and written back round-trips.
+        # A font TUPLE -- ("Arial", 13) or ("Arial", 13, "bold") -- is how this
+        # library's theme file stores fonts, and it is what comes back once the
+        # theme is used as a property's default. pygubu parses font properties
+        # with tkfontstr_to_dict(), which wants a Tk font STRING:
+        #
+        #   expected string or bytes-like object, got 'tuple'
+        #
+        # Distinguished from a colour pair above by its second element being a
+        # number rather than a string.
+        if (isinstance(value, (tuple, list)) and 2 <= len(value) <= 4
+                and isinstance(value[0], str)
+                and isinstance(value[1], (int, float))):
+            family = str(value[0])
+            parts = [f"{{{family}}}" if " " in family else family,
+                     str(int(value[1]))]
+            parts.extend(str(extra) for extra in value[2:]
+                         if extra and str(extra) not in ("normal", "roman"))
+            return " ".join(parts)
+
+        # A list reaching here is one whose property name was not supplied.
+        # Rendered as JSON anyway, since that is what every list property in
+        # this library expects -- pygubu parses them with a strict
+        # json.loads(), which raises TypeError on a Python list rather than
+        # rejecting it cleanly.
+        if isinstance(value, list):
+            try:
+                import json
+                return json.dumps(value)
+            except (TypeError, ValueError):
+                return value
+
+        # A Tcl_Obj is what cget() hands back for a variable property --
+        # textvariable, variable, listvariable. pygubu wants the variable's
+        # NAME, and str() on a Tcl_Obj gives exactly that ("PY_VAR0"). Passed
+        # through untouched it raised:
+        #
+        #   argument of type '_tkinter.Tcl_Obj' is not a container or iterable
+        if type(value).__name__ == "Tcl_Obj":
+            return str(value)
+
+        # A Tk variable object, for the same reason: its name is what a
+        # configure() call accepts, not the object.
+        if value is not None and hasattr(value, "_name") \
+                and hasattr(value, "get") and hasattr(value, "set"):
+            return str(value)
+
+        if value is not None and type(value).__name__ == "CTkFont":
+            try:
+                family = value.cget("family")
+                size = value.cget("size")
+                parts = [f"{{{family}}}" if " " in str(family) else str(family),
+                         str(size)]
+                for style in ("weight", "slant"):
+                    try:
+                        setting = value.cget(style)
+                    except Exception:
+                        continue
+                    if setting and setting not in ("normal", "roman"):
+                        parts.append(str(setting))
+                for style in ("underline", "overstrike"):
+                    try:
+                        if value.cget(style):
+                            parts.append(style)
+                    except Exception:
+                        continue
+                return " ".join(parts)
+            except Exception:
+                return None
+
+        return value