scustomtkinter 0.2.1__py3-none-any.whl

scustomtkinter/sctk_frame_labeled_primary.py

@@ -0,0 +1,667 @@
+#!/usr/bin/python3
+"""
+sCTkFrameLabeledPrimary
+
+A theme-compliant labeled scrollable container panel -- the higher-emphasis
+of the library's two labeled scrollable frame tiers (see also
+sCTkFrameLabeledSecondary). Inherits directly from ctk.CTkScrollableFrame so
+CustomTkinter handles native scrolling and layout; this class layers
+automatic light/dark theme resolution, a visual-only "disabled" state, and
+scrollbar-hiding on top.
+
+Base class order matters here: `class sCTkFrameLabeledPrimary(
+ctk.CTkScrollableFrame, ThemeableWidget)` puts the native CTk class first, so
+every `super()` call in this file's own methods resolves to
+ctk.CTkScrollableFrame -- 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.
+
+"Disabled" here is purely visual -- there is no native way to lock a
+CTkFrame-derived container's own interactivity the way a control can be
+locked.  Disabling this widget dims its own colors; it does NOT
+automatically disable child widgets placed inside it -- that's the caller's
+responsibility, exactly as demonstrated in this project's own test harness
+for this widget (looping over the frame's children and calling
+.configure(state=...) on each one individually).
+
+Deliberately not scrollable: this widget uses ctk.CTkScrollableFrame purely
+to access its native label_text/label_font/label_text_color feature (plain
+CTkFrame has no built-in label option) -- not because scrolling is wanted.
+The model here is ttk.LabelFrame, which doesn't scroll at all. The scrollbar
+is suppressed by matching its colors to the frame background and collapsing
+its width to 0, which removes the visible/interactive scrollbar entirely.
+Confirmed by the maintainer: this is the intended design, not a gap.
+SIZED TO ITS CONTENTS, for the same reason: a ttk.LabelFrame is as tall as
+what is in it, while CTkScrollableFrame defaults to 200 points high whatever
+it holds. Give it a `height` and that is honoured instead, with anything past
+it clipped -- this panel does not scroll. See _begin_content_sizing().
+"""
+import customtkinter as ctk
+from typing import Any, Optional
+from .themeable_widget import ThemeableWidget, defer
+
+
+# How long to wait before measuring again when nothing has been drawn yet,
+# and how many times to bother. A second in all: if the panel is not on
+# screen by then it is hidden or destroyed, and its height does not matter.
+_FIT_RETRY_MS = 50
+_FIT_MAX_ATTEMPTS = 20
+
+class sCTkFrameLabeledPrimary(ctk.CTkScrollableFrame, ThemeableWidget):
+    """Themeable, high-emphasis labeled scrollable container.
+
+    Adds to native ctk.CTkScrollableFrame:
+      - 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 visual-only "disabled" state (see module docstring) -- dims border,
+        fill, and label text colors; does not lock interactivity, and does
+        not cascade to child widgets automatically.
+      - Pygubu Designer property introspection for `state`, `fg_color`,
+        `border_color`, and `label_text_color` via a single-argument
+        configure() call.
+      - Scrollbar hiding: the internal scrollbar's colors are forced to match
+        the frame's own background and its width collapsed to 0, making it
+        invisible while (presumably) leaving scrolling itself functional.
+      - winfo_children()/get_children()/get_all_children(): by default,
+        winfo_children() filters out children whose class name is exactly
+        "CTkLabel", "Label", "CTkFrame", or "Frame" -- internal furniture
+        CTkScrollableFrame creates for its own title row and canvas wrapper,
+        which would otherwise clutter a naive "what did I add to this frame"
+        query. get_children() is this filtered view; get_all_children()
+        returns the raw, unfiltered list.
+
+    KNOWN LIMITATION: the winfo_children() filter is a class-NAME string
+    check, not a "was this created internally" check. A plain,
+    un-themed customtkinter.CTkLabel or customtkinter.CTkFrame added
+    directly as a child (bypassing the sCTk-prefixed equivalents) would be
+    incorrectly filtered out of get_children() too, since its class name
+    matches the same strings being excluded. Themed sCTk widgets (e.g.
+    sCTkLabelPrimary) are unaffected, since their class names don't match.
+
+    Deliberately not scrollable -- unlike sCTkScrollableFrame, this class has
+    no scroll-binding code (no _toggle_scroll_bindings, no macOS touchpad
+    handling), despite both wrapping the same native CTkScrollableFrame. This
+    is intentional, confirmed by the maintainer: the model here is
+    ttk.LabelFrame, which never scrolls. CTkScrollableFrame is used purely
+    for its built-in label feature, and the internal scrollbar is
+    deliberately suppressed (see _hide_internal_scrollbars()) rather than
+    left functional.
+
+    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 the button
+    family. Not separately re-confirmed for this specific widget.
+
+    WHITELIST GUARD: if a composite widget inherits sCTkFrameLabeledPrimary as
+    its own base class and explicitly calls ThemeableWidget.__init__ itself
+    before calling super().__init__(), that composite's own final_kw could
+    contain keys native ctk.CTkScrollableFrame knows nothing about. Confirmed
+    directly against CustomTkinter's own source, CTkScrollableFrame.__init__
+    has NO **kwargs catch-all at all -- every parameter is explicitly named,
+    so ANY unrecognized keyword reaching it raises TypeError immediately.
+    _NATIVE_CTKSCROLLABLEFRAME_KWARGS filters final_kw down to only the keys
+    the real native constructor accepts before that call. This only matters
+    for the Pattern-B composition scenario described above; for direct
+    construction of a plain sCTkFrameLabeledPrimary, final_kw already only
+    contains this widget's own theme keys, so the filter is a no-op.
+    """
+
+    # Confirmed directly against CustomTkinter's own ctk_scrollable_frame.py
+    # source: every one of CTkScrollableFrame.__init__'s named parameters,
+    # excluding "master" (always passed positionally, never part of the
+    # filtered kwargs dict).
+    _NATIVE_CTKSCROLLABLEFRAME_KWARGS = frozenset({
+        "width", "height", "corner_radius", "border_width", "bg_color",
+        "fg_color", "border_color", "scrollbar_fg_color",
+        "scrollbar_button_color", "scrollbar_button_hover_color",
+        "label_fg_color", "label_text_color", "label_text", "label_font",
+        "label_anchor", "orientation",
+    })
+
+    def __init__(self, master: Optional[Any] = None, **kwargs: Any) -> None:
+        """
+        Args:
+            master: Parent container.
+            **kwargs: Any native CTkScrollableFrame argument (e.g. `label_text`),
+                or a theme-key override (see the "sCTkFrameLabeledPrimary"
+                block in sCTkThemes.json, including its disabled_map).
+        """
+        # 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.
+        # Noted BEFORE the theme logic runs, which merges the theme's own keys
+        # into the same dictionary: what matters is whether the CALLER asked
+        # for a height, not whether one ends up in final_kw.
+        asked_height = kwargs.get("height")
+
+        ThemeableWidget.__init__(self, kwargs)
+
+        # 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.
+        # 3. Initialize CustomTkinter natively. Only forwards the subset of
+        # final_kw that native CTkScrollableFrame actually accepts -- see this
+        # class's docstring ("WHITELIST GUARD") for why this filtering exists.
+        native_kwargs = {k: v for k, v in self.final_kw.items() if k in self._NATIVE_CTKSCROLLABLEFRAME_KWARGS}
+        super().__init__(master, **native_kwargs)
+
+        self._custom_current_state = "normal"
+
+        # 4. Hide the scrollbar visually on first construction.
+        self._hide_internal_scrollbars()
+
+        # 5. Register lifecycle handshake hook, notifying Pygubu-style consumers
+        # that construction is complete.
+        # Sized to its contents unless the caller said otherwise -- see
+        # _begin_content_sizing for why this is not the caller's job.
+        self._begin_content_sizing(asked_height)
+
+        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 the
+        button family.
+
+        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"/"label_text_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 CTkScrollableFrame 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.
+        """
+        # 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", "label_text_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 the
+        # repaint 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)
+
+        self._drop_cleared(kwargs)
+
+        if kwargs:
+            result = super().configure(**kwargs)
+            self._hide_internal_scrollbars()
+            # FIX (2026-11-11): the title row, its font or the border changed,
+            # so the chrome around the content did -- measure it again. It is
+            # measured once and kept (see fit_to_content), so without this a
+            # title given after the content (as in Pygubu Designer) left the
+            # panel a title-row short until the content next changed.
+            if any(k in kwargs for k in self._CHROME_OPTIONS):
+                self._refit_chrome()
+            return result
+        return None
+
+    # Options that change the room around the content -- see _refit_chrome.
+    _CHROME_OPTIONS = ("label_text", "label_font", "border_width", "corner_radius")
+
+    def _refit_chrome(self) -> None:
+        """Forgets the measured chrome and fits again, unless the height is fixed."""
+        if getattr(self, "_height_is_fixed", True):
+            return
+        self._fit_chrome = None
+        self._fitted_height = None
+        self._fit_attempts = 0
+        self._ask_to_fit()
+
+    # 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
+
+
+    # ------------------------------------------------------------------
+    # Sizing: as tall as its contents, like the ttk.LabelFrame it models
+    # ------------------------------------------------------------------
+    def _begin_content_sizing(self, explicit_height: Any) -> None:
+        """
+        Makes the panel as tall as what is in it.
+
+        WHY THIS EXISTS. This widget is a labeled PANEL -- see the module
+        docstring -- but it is built on CTkScrollableFrame, which is sized for
+        scrolling: it defaults to 200 points high whatever it holds. A panel
+        that stands half empty, or clips its last row, is wrong in a way the
+        caller cannot easily put right, because the height has to go on a
+        frame the caller never sees.
+
+        THE THREE WIDGETS. CTkScrollableFrame is an outer frame, a canvas
+        inside it, and the inner frame the content goes into -- and the object
+        the caller holds is the innermost. So `self.master` is the CANVAS, and
+        a height set on the widget or on its master is recorded and then
+        overridden when the outer frame resizes to what the canvas asks for.
+        `_parent_frame` is the one on screen, and propagation off is what
+        makes a height set there stick.
+
+        An explicit height is honoured as given -- the caller has said what
+        they want, and content beyond it is clipped, since this panel does not
+        scroll. Without one, the height follows the content.
+        """
+        self._fitted_height = None
+        self._fit_chrome = None
+        self._fit_attempts = 0
+        self._fitting = False
+        self._fit_scheduled = False
+        self._height_is_fixed = explicit_height is not None
+        outer = getattr(self, "_parent_frame", None)
+        if outer is None:                       # not the structure expected
+            return
+
+        if self._height_is_fixed:
+            # Once Tk has worked out the width: _freeze_outer reads it before
+            # turning propagation off, and at construction it is not known.
+            # explicit_height is in CustomTkinter units already.
+            defer(self, "idle", lambda: self._freeze_outer(int(explicit_height), scaled=True))
+            return
+
+        # The content's size changing is the signal to measure again -- but
+        # NOT NOW: this fires during the layout that is still happening, and
+        # our own resize fires it too. _ask_to_fit defers it to one pass on
+        # the next tick.
+        self.bind("<Configure>", lambda event: self._ask_to_fit(), add="+")
+        self._ask_to_fit()
+
+    def _ask_to_fit(self) -> None:
+        """
+        Asks for ONE measuring pass shortly, however many times it is called.
+
+        Everything about this widget's own resizing arrives in bursts -- a
+        row added, the window resized, our own height write coming back as
+        another Configure -- and measuring inside any of them reads a
+        half-finished layout. Coalescing them into one pass afterwards is
+        what makes the answer stable.
+        """
+        # NOT WHILE MEASURING. Settling the layout and setting the height both
+        # raise Configure events of our own making; treating those as new
+        # requests means every pass schedules the next one, for ever -- a
+        # timer waking up every 50ms doing nothing, which writes no height
+        # and so would never have shown on screen.
+        if self._height_is_fixed or self._fit_scheduled or getattr(self, "_fitting", False):
+            return
+        self._fit_scheduled = True
+        try:
+            # FIX (2026-11-11): THE FIRST PASS AT IDLE, retries on the timer.
+            # Pygubu Designer builds a form, lets Tk settle (update_idletasks)
+            # and then measures the window once to size its design canvas; a
+            # first fit 50 ms later came after that, so the canvas kept the
+            # unfitted size and the next widget down was squashed. Idle work
+            # is done during that settling. Only the FIRST pass: an idle pass
+            # that queued another idle pass spun for ever -- see
+            # fit_to_content -- so a retry still waits on the timer.
+            if self._fit_attempts == 0:
+                defer(self, "idle", self._fit_now)
+            else:
+                defer(self, _FIT_RETRY_MS, self._fit_now)
+        except Exception:
+            self._fit_scheduled = False
+
+    def _fit_now(self) -> None:
+        self._fit_scheduled = False
+        self.fit_to_content()
+
+    def fit_to_content(self) -> None:
+        """
+        Sets the panel's height to what its contents come to.
+
+        Called automatically as the content changes. Public because content
+        added long after construction -- a row appended to a settings group,
+        say -- may not change the inner frame's own size in a way Tk reports,
+        and then the caller needs a way to say "measure again".
+
+        Does nothing when a height was given explicitly.
+
+        THE CHROME IS MEASURED ONCE, NOT CALCULATED. The panel needs room for
+        its contents PLUS the title bar, its padding and the border -- about
+        66 points, not the ~34 a first version worked out from the label's own
+        height and the border width. That arithmetic looked right and drew
+        every panel one row short. The difference between the outer frame and
+        the canvas inside it IS that chrome, whatever it is made of.
+
+        Measured ONCE because measuring it again mid-resize reads a
+        half-updated canvas, gives a different answer, and sets the height
+        again -- which resizes the canvas, which arrives back here. That
+        recursed until Python stopped it.
+        """
+        if getattr(self, "_height_is_fixed", False) or getattr(self, "_fitting", False):
+            return
+        outer = getattr(self, "_parent_frame", None)
+        canvas = getattr(self, "_parent_canvas", None) or self.master
+        if outer is None or canvas is None:
+            return
+
+        self._fitting = True
+        try:
+            # SETTLE THE LAYOUT FIRST. Called by hand straight after a row is
+            # added -- which is what this method is public for -- Tk has not
+            # yet recomputed what the content asks for, so measuring now reads
+            # the height from before the row. Re-entry is guarded above, so
+            # letting Tk catch up here is safe.
+            try:
+                self.update_idletasks()
+            except Exception:
+                pass
+            content = self.winfo_reqheight()
+            if content <= 1:                    # not laid out yet
+                self._retry_fit()
+                return
+
+            if self._fit_chrome is None and not getattr(self, "_outer_frozen", False):
+                # FIX (2026-11-11): BEFORE THE HEIGHT IS FROZEN the outer frame
+                # still asks for exactly the canvas plus the chrome, so the
+                # requested sizes give the chrome without anything being drawn
+                # -- which the first pass, at idle, needs. Once frozen, the
+                # outer frame asks for what was set, so a re-measure (a new
+                # title) reads the drawn heights below instead.
+                outer_req = outer.winfo_reqheight()
+                canvas_req = canvas.winfo_reqheight()
+                if outer_req > 1 and canvas_req > 1 and outer_req > canvas_req:
+                    self._fit_chrome = outer_req - canvas_req
+            if self._fit_chrome is None:
+                outer_height = outer.winfo_height()
+                canvas_height = canvas.winfo_height()
+                if outer_height <= 1 or canvas_height <= 1:
+                    # NOTHING IS DRAWN YET, so the chrome cannot be measured.
+                    # Try again shortly -- on a TIMER, not after_idle, and not
+                    # for ever. after_idle here spun: it queues work for the
+                    # next idle moment, and queueing it again from inside that
+                    # work means Tk never becomes idle, so the window is never
+                    # drawn, so the sizes are never known.
+                    self._retry_fit()
+                    return
+                self._fit_chrome = max(0, outer_height - canvas_height)
+
+            wanted = content + self._fit_chrome
+            if wanted != self._fitted_height:
+                self._fitted_height = wanted
+                self._freeze_outer(wanted)
+        except Exception:
+            pass
+        finally:
+            self._fitting = False
+
+    def _freeze_outer(self, height, scaled: bool = False) -> None:
+        """
+        Gives the outer frame a fixed height, keeping its width.
+
+        FIX (2026-11-11), the Designer's collapsed labelled frame: a height
+        only sticks with propagation off, and propagation off fixes BOTH
+        dimensions at the frame's own width/height options. CustomTkinter
+        creates the outer frame with width 0 -- it takes its size from the
+        canvas inside -- so turning propagation off left it 0 wide. Packed or
+        gridded to fill, as in an application, the parent's width hid that;
+        packed plainly, as in Pygubu Designer's preview, the panel collapsed
+        to a sliver with its content off to one side. So the width it had
+        while propagating is read first, ONCE (afterwards it would only read
+        back what was set), and set alongside the height.
+
+        `height` is in pixels as measured, unless `scaled` says it is already
+        in CustomTkinter units; CTkFrame.configure() applies the widget
+        scaling itself, so pixels are converted back first -- otherwise a
+        scaled display (Windows at 150 %) got every fitted height scaled
+        twice.
+        """
+        outer = getattr(self, "_parent_frame", None)
+        if outer is None:
+            return
+        try:
+            if not outer.winfo_exists():
+                return
+            unscale = getattr(outer, "_reverse_widget_scaling", None) or (lambda v: v)
+            if getattr(self, "_outer_width", None) is None:
+                try:
+                    outer.update_idletasks()
+                except Exception:
+                    pass
+                width_px = max(outer.winfo_reqwidth(), outer.winfo_width())
+                self._outer_width = unscale(width_px) if width_px > 1 else None
+            settings = {"height": height if scaled else unscale(height)}
+            if self._outer_width:
+                settings["width"] = self._outer_width
+            outer.configure(**settings)
+            outer.pack_propagate(False)
+            outer.grid_propagate(False)
+            self._outer_frozen = True
+        except Exception:
+            pass
+
+    def _retry_fit(self) -> None:
+        """Waits and measures again -- a limited number of times."""
+        self._fit_attempts += 1
+        if self._fit_attempts > _FIT_MAX_ATTEMPTS:
+            return                              # hidden, or destroyed
+        self._fit_scheduled = False
+        self._ask_to_fit()
+
+    def winfo_children(self, include_private: bool = False) -> list:
+        """
+        By default, filters out children whose exact class name is "CTkLabel",
+        "Label", "CTkFrame", or "Frame" -- internal furniture CTkScrollableFrame
+        creates for its own title row and canvas wrapper. See this class's
+        docstring for a known limitation of this approach.
+
+        Args:
+            include_private: If True, returns the raw, unfiltered list instead.
+
+        Returns:
+            A list of child widgets.
+        """
+        raw_children = super().winfo_children()
+        if include_private:
+            return raw_children
+
+        filtered_children = []
+        for child in raw_children:
+            if child.__class__.__name__ not in ["CTkLabel", "Label", "CTkFrame", "Frame"]:
+                filtered_children.append(child)
+        return filtered_children
+
+    def get_children(self) -> list:
+        """Equivalent to winfo_children(include_private=False)."""
+        return self.winfo_children(include_private=False)
+
+    def get_all_children(self) -> list:
+        """Equivalent to winfo_children(include_private=True)."""
+        return self.winfo_children(include_private=True)
+
+    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 visual "disabled" state. This is purely
+        cosmetic -- see module docstring for why there's no native
+        interactivity lock, and why child widgets are not automatically
+        disabled along with the frame.
+
+        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.
+
+        Returns:
+            The resulting state ("normal" or "disabled").
+        """
+        if mode is None:
+            return getattr(self, "_custom_current_state", "normal")
+
+        mode = mode.lower()
+        if mode in ("normal", "enabled", "active"):
+            self._custom_current_state = "normal"
+            self._update_current_visual_state()
+
+        elif mode == "disabled":
+            super_payload = {}
+            for key in ("fg_color", "border_color", "label_text_color"):
+                val = self._custom_disabled_map.get(key)
+                if val is not None:
+                    super_payload[key] = val
+
+            if super_payload:
+                super().configure(**super_payload)
+
+            self._custom_current_state = "disabled"
+            self._hide_internal_scrollbars()
+        return self._custom_current_state
+
+    def _update_current_visual_state(self) -> None:
+        """
+        Recomputes and applies this widget's colors from the theme file, for
+        the normal (enabled) state.
+
+        Called after construction (indirectly) and on every state("normal")
+        call.
+
+        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.
+        """
+        config_payload = {}
+        for key in ("fg_color", "border_color", "label_text_color", "border_width", "label_font"):
+            val = self._local_defaults.get(key)
+            if val is not None:
+                config_payload[key] = val
+
+        if config_payload:
+            super().configure(**config_payload)
+        self._hide_internal_scrollbars()
+
+    def _hide_internal_scrollbars(self) -> None:
+        """
+        Forces the internal scrollbar's colors to match the frame's own
+        background and collapses its width to 0, making it visually
+        invisible.
+
+        If fg_color resolves to the literal string "transparent" (e.g. if a
+        caller explicitly overrides it), falls back to a hardcoded neutral
+        pair rather than passing "transparent" through to the scrollbar,
+        since there's no single real background color to match in that case.
+        This fallback is not theme-driven and is a deliberate exception to
+        this project's general "no hardcoded colors" principle -- there's no
+        required theme key this could reasonably read from instead, since the
+        whole point is handling the case where the real background is
+        genuinely ambiguous (transparent).
+        """
+        try:
+            bg_color_raw = super().cget("fg_color")
+            resolved_bg = bg_color_raw
+
+            if bg_color_raw == "transparent":
+                current_mode = str(ctk.get_appearance_mode()).lower()
+                resolved_bg = "#2B2B2B" if current_mode == "dark" else "#DBDBDB"
+
+            if hasattr(self, "_scrollbar") and self._scrollbar is not None:
+                self._scrollbar.configure(
+                    fg_color=resolved_bg,
+                    button_color=resolved_bg,
+                    button_hover_color=resolved_bg,
+                    width=0
+                )
+        except Exception:
+            pass
+        self._clear_right_border()
+
+
+    def _clear_right_border(self) -> None:
+        """
+        FIX: keeps the right-hand border visible below the title.
+
+        CTkScrollableFrame grids its canvas with spacing on the LEFT only --
+        padx=(border_spacing, 0) -- and leaves the right to the scrollbar,
+        which it grids in the next column with no spacing at all, out to the
+        frame's outer edge. Hidden by width 0 and the background colour, the
+        scrollbar still filled that strip, and painted over the border from
+        the title down: every group's right edge stopped below its title bar,
+        the left edge whole, the bottom corner back again.
+
+        So the scrollbar comes out of the grid, and the canvas gets the same
+        spacing on the right as on the left. Called from
+        _hide_internal_scrollbars(), which runs after construction and after
+        every configure() -- the native configure re-grids both.
+        """
+        try:
+            if getattr(self, "_orientation", "vertical") != "vertical":
+                return
+            scrollbar = getattr(self, "_scrollbar", None)
+            if scrollbar is not None:
+                scrollbar.grid_remove()
+            frame = getattr(self, "_parent_frame", None)
+            canvas = getattr(self, "_parent_canvas", None)
+            if frame is None or canvas is None:
+                return
+            spacing = self._apply_widget_scaling(
+                frame.cget("corner_radius") + frame.cget("border_width"))
+            canvas.grid_configure(padx=(spacing, spacing))
+        except Exception:
+            pass
+
+    def get_container(self):
+        """Returns self. Provided for API symmetry with composite widgets that wrap a separate inner container."""
+        return self