scustomtkinter 0.2.1__py3-none-any.whl

scustomtkinter/sctk_label_tertiary.py

@@ -0,0 +1,278 @@
+#!/usr/bin/python3
+"""
+sCTkLabelTertiary
+
+A theme-compliant, low-emphasis inline description label widget -- the
+lowest-emphasis of the library's three label tiers (see also sCTkLabelPrimary,
+sCTkLabelSecondary). Inherits directly from ctk.CTkLabel so CustomTkinter
+handles native rendering; this class layers automatic light/dark theme
+resolution and a distinct enabled/disabled visual state on top.
+
+Base class order matters here: `class sCTkLabelTertiary(ctk.CTkLabel,
+ThemeableWidget)` puts the native CTk class first, so every `super()` call in
+this file's own methods resolves to ctk.CTkLabel -- 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.
+
+Unlike the button/checkbox family, "disabled" here is purely visual (dimmed
+text color) -- CTkLabel has no native click handling to block in the first
+place.
+
+Internal state attribute is named self._custom_current_state, matching the
+convention used across the rest of the library -- an earlier version of this
+file used self._current_state instead, inconsistent both within the label
+family (sCTkLabelSecondary already used _custom_current_state) and against
+every other themed widget. Purely an internal rename; doesn't affect the
+public state()/get_state() API.
+"""
+from typing import Any, Optional
+import customtkinter as ctk
+from .themeable_widget import ThemeableWidget
+
+
+class sCTkLabelTertiary(ctk.CTkLabel, ThemeableWidget):
+    """Themeable, low-emphasis inline description label.
+
+    Adds to native ctk.CTkLabel:
+      - 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 -- purely a text-color dim,
+        since labels have no native interactivity to block.
+      - Pygubu Designer property introspection for `state`, `fg_color`, and
+        `text_color` via a single-argument configure() call, plus a cget()
+        override so querying "state" doesn't raise (native CTkLabel has no
+        real "state" option to cget in the first place).
+
+    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.
+    """
+
+    def __init__(self, master: Optional[Any] = None, **kwargs: Any) -> None:
+        """
+        Args:
+            master: Parent container.
+            **kwargs: `state` is pulled out explicitly below (applied after
+                construction, via self.configure(), rather than passed to the
+                native constructor). Everything else is either a native
+                CTkLabel argument (e.g. `text`, `font`) or a theme-key override
+                (see the "sCTkLabelTertiary" block in sCTkThemes.json).
+        """
+        # 1. Capture the initial state before ThemeableWidget's own kwargs pass,
+        # so it doesn't get merged into final_kw and sent to the native
+        # constructor.
+        # NO PLACEHOLDER TEXT. CustomTkinter defaults `text` to the class
+        # name, so a CTkLabel built without text reads "CTkLabel". 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.
+        kwargs.setdefault("text", "")
+        state_init = kwargs.pop("state", "normal")
+
+        # 2. Fire our shared theme logic. This resolves final_kw
+        # (construction-time properties) and the disabled color map. See
+        # ThemeableWidget.__init__ for what actually happens here.
+        ThemeableWidget.__init__(self, kwargs)
+
+        # 3. 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)
+
+        # Remove any stray "state" key from final_kw -- already extracted
+        # above, but guards against it being reintroduced by a theme override.
+        self.final_kw.pop("state", None)
+
+        # 4. Initialize CustomTkinter natively with the clean final kwargs array.
+        super().__init__(master, **self.final_kw)
+
+        # 5. Apply the requested initial state now that the native widget exists.
+        self._custom_current_state = "normal"
+        self.configure(state=state_init)
+
+        # 6. 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 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.
+                - "fg_color" or "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 CTkLabel 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`), so the query branches
+        # below never matched anything. 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", "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
+        # _update_current_visual_state() 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"))
+
+        # Theme values cleared to "" are dropped; `text=""` is kept, so a
+        # label 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 cget(self, attribute_name: str) -> Any:
+        """
+        Intercepts "state" queries so they route through state() instead of
+        being forwarded to the native widget, which has no real "state" option
+        to cget in the first place and would otherwise raise.
+
+        Args:
+            attribute_name: The property name being queried.
+
+        Returns:
+            self.state() if attribute_name is "state" (case-insensitive),
+            otherwise whatever the native CTkLabel.cget() returns.
+        """
+        if str(attribute_name).lower() == "state":
+            return self.state()
+        return super().cget(attribute_name)
+
+    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 visual 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 matches
+                neither branch and leaves 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"
+            self._update_current_visual_state()
+        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:
+        """
+        Recomputes and applies this widget's colors from the theme file, based
+        on the current state.
+
+        Called after construction and on every state() change.
+
+        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.
+
+        text_color is required to be present in whichever map is active (the
+        top-level block for normal state, disabled_map for disabled) -- if
+        it's missing, this raises immediately rather than silently falling
+        back to a default or silently omitting the property. An earlier
+        version fell back to CTk's own global ThemeManager default; per this
+        project's design, ThemeableWidget-based widgets are meant to fail hard
+        on incomplete theme data, not paper over it.
+        """
+        is_disabled = self._custom_current_state == "disabled"
+        target_map = self._custom_disabled_map if is_disabled else self._local_defaults
+
+        if target_map.get("text_color") is None:
+            raise KeyError(
+                f"'{getattr(self, '_THEME_BLOCK_NAME', None) or self.__class__.__name__}' "
+                f"theme block is missing 'text_color' in its "
+                f"{'disabled_map' if is_disabled else 'top-level'} section of sCTkThemes.json."
+            )
+
+        config_payload = {}
+        for key in ("fg_color", "text_color", "font"):
+            val = target_map.get(key)
+            if val is not None:
+                config_payload[key] = val
+
+        super().configure(**config_payload)

scustomtkinter/sctk_messagebox.py

@@ -0,0 +1,275 @@
+#!/usr/bin/python3
+"""
+sCTkMessage
+
+An advanced, themeable dialog window system subclassed from ctk.CTkToplevel.
+Supports customizable single prompt text or dual choice prompts returning boolean states.
+Derived from Message class by Fastattack, 2024.
+https://github.com/fastattackv/MoreCustomTkinterWidget
+"""
+import os
+import textwrap
+
+import customtkinter as ctk
+from .themeable_widget import ThemeableWidget
+
+from PIL import Image
+from typing import Literal, Union, Tuple, Optional
+
+from .sctk_button_primary import sCTkButtonPrimary
+from .sctk_button_secondary import sCTkButtonSecondary
+from .sctk_label_primary import sCTkLabelPrimary
+
+class sCTkMessagebox(ctk.CTkToplevel, ThemeableWidget):
+    """Advanced themeable message dialog window supporting single or dual prompt states."""
+
+    # Required at the TOP LEVEL of the theme block.
+    # type_font styles the "[ERROR]" / "[INFO]" marker, which is deliberately
+    # distinct from the message body's `font`. It was hardcoded as
+    # ("Arial", 12, "bold") at both sites below, so the theme file had no way
+    # to reach it while every other value on those lines was themed.
+    _REQUIRED_THEME_KEYS = ("font", "text_color", "fg_color", "type_font")
+
+    # WHITELIST GUARD. Native CTkToplevel names fg_color explicitly and passes
+    # everything else through to tkinter.Toplevel, which raises TclError on any
+    # option it doesn't know. Theme keys like `font` and `text_color` are for
+    # this widget's own label, NOT for the window, so final_kw is filtered down
+    # to this set before the native constructor sees it.
+    _NATIVE_CTKTOPLEVEL_KWARGS = frozenset({"fg_color"})
+
+    # There is no disabled_map and no state(): this is a modal dialog. It grabs
+    # input on construction and destroys itself on dismissal, so there is no
+    # window of time in which a disabled appearance would mean anything.
+
+    def __init__(self,
+                 title: str,
+                 message: str,
+                 typ: Literal["info", "warning", "error"],
+                 master: any = None,
+                 buttons: Literal["ok", "yes_no"] = "ok",
+                 ok_text: str = "Ok",
+                 yes_text: str = "Yes",
+                 no_text: str = "No",
+                 width: int = 400,
+                 *args, **kwargs):
+
+        # 1. Fire our shared theme logic first to extract registry configurations safely
+        ThemeableWidget.__init__(self, kwargs)
+
+        # 2. 🛠️ THE MUTATION SAFEGUARD DEEP COPY:
+        self._local_defaults = dict(self.final_kw)
+        self._validate_theme_keys()
+
+        # 3. Initialize CTkToplevel natively.
+        #
+        # FIX: this previously forwarded the RAW kwargs dict rather than the
+        # resolved final_kw, so the theme block never reached the native
+        # constructor at all -- the dialog window itself was unthemed, and
+        # ThemeableWidget's resolution work was discarded for everything
+        # except the two keys read back manually below. Passing final_kw
+        # through the whitelist above fixes that and simultaneously protects
+        # the native constructor: a caller passing font= to this widget would
+        # previously have had it forwarded to tkinter.Toplevel, which raises
+        # TclError on an option it doesn't recognize.
+        native_kwargs = {k: v for k, v in self.final_kw.items()
+                         if k in self._NATIVE_CTKTOPLEVEL_KWARGS}
+        super().__init__(master=master, *args, **native_kwargs)
+        self.withdraw()
+
+        self._result = None
+        self.lift()
+        self.attributes("-topmost", True)
+        self.resizable(False, False)
+        self.grab_set()
+        self.title(title)
+
+        # No fallbacks: validated at construction, so both lookups resolve.
+        font_config = self._local_defaults.get("font")
+        text_color_config = self._local_defaults.get("text_color")
+
+        # 4. Custom Local Icon Asset Extraction Loops
+        # 4. 🔑 DYNAMIC ASSET PATH ANCHOR: Safely navigates down into assets/images/
+        current_script_dir = os.path.dirname(os.path.abspath(__file__))
+        images_dir = os.path.normpath(os.path.join(current_script_dir, "assets", "images"))
+
+        light_icon_path = os.path.join(images_dir, f"{typ}.png")
+        dark_icon_path = os.path.join(images_dir, f"{typ}_dark.png")
+
+        # Fallback to standard light version if an explicit dark-theme variant is missing
+        if not os.path.exists(dark_icon_path):
+            dark_icon_path = light_icon_path
+
+        if os.path.exists(light_icon_path):
+            try:
+                pil_light = Image.open(light_icon_path)
+                pil_dark = Image.open(dark_icon_path)
+                ctk_image = ctk.CTkImage(light_image=pil_light, dark_image=pil_dark, size=(85, 85))
+                self.image_label = sCTkLabelPrimary(self, text="", image=ctk_image, width=85, height=85)
+                self.image_label.grid(row=0, column=0, padx=(15, 5), pady=20, sticky="n")
+            except Exception as image_err:
+                # Graceful extraction safety recovery trace
+                print(f"⚠️ sCustomTkinter Warning -> Image format initialization error: {image_err}")
+                self.image_label = sCTkLabelPrimary(
+                    self, text=f"[{typ.upper()}]",
+                    font=self._local_defaults.get("type_font"))
+                self.image_label.grid(row=0, column=0, padx=(15, 5), pady=20, sticky="n")
+        else:
+            # Safe text-based interface fallback if filesystem layout tracks vanish
+            print(f"⚠️ sCustomTkinter Warning -> Missing visual alert asset from target path: {light_icon_path}")
+            self.image_label = sCTkLabelPrimary(
+                self, text=f"[{typ.upper()}]",
+                font=self._local_defaults.get("type_font"))
+            self.image_label.grid(row=0, column=0, padx=(15, 5), pady=20, sticky="n")
+
+        max_text_width_pixels = width - 180
+        char_limit_per_line = max(20, int(max_text_width_pixels / 11.5))
+        wrapped_message = "\n".join(textwrap.wrap(message, width=char_limit_per_line))
+
+        self.label = sCTkLabelPrimary(self, text=wrapped_message, font=font_config, text_color=text_color_config, justify="left", anchor="w", wraplength=max_text_width_pixels)
+        self.label.grid(row=0, column=1, padx=(10, 35), pady=20, sticky="w")
+
+        if buttons == "yes_no":
+            self.yes_button = sCTkButtonPrimary(self, text=yes_text, command=self.on_yes)
+            self.yes_button.grid(row=1, column=0, padx=(15, 5), pady=15, sticky="ew")
+            self.no_button = sCTkButtonSecondary(self, text=no_text, command=self.on_no)
+            self.no_button.grid(row=1, column=1, padx=(5, 15), pady=15, sticky="ew")
+            self.bind("<Return>", self.on_yes)
+            self.grid_columnconfigure(0, weight=1, uniform="dialog_buttons")
+            self.grid_columnconfigure(1, weight=1, uniform="dialog_buttons")
+        else:
+            self.ok_button = sCTkButtonPrimary(self, text=ok_text, command=self.on_ok)
+            self.ok_button.grid(row=1, column=0, columnspan=2, padx=15, pady=15)
+            self.bind("<Return>", self.on_ok)
+            self.grid_columnconfigure(0, weight=1)
+            self.grid_columnconfigure(1, weight=1)
+
+        self._center_window(target_width=width)
+        self.deiconify()
+
+        # 🔑 REGISTER LIFECYCLE HANDSHAKE HOOK: Unlocks full Pygubu parent support out of the box
+        self._finalize_themeable_lifecycle()
+    def _center_window(self, target_width: int):
+        self.update_idletasks()
+        width = target_width
+        height = self.winfo_reqheight()
+        if self.master and hasattr(self.master, "winfo_x"):
+            x = self.master.winfo_x() + (self.master.winfo_width() // 2) - (width // 2)
+            y = self.master.winfo_y() + (self.master.winfo_height() // 2) - (height // 2)
+        else:
+            x = (self.winfo_screenwidth() // 2) - (width // 2)
+            y = (self.winfo_screenheight() // 2) - (height // 2)
+        self.geometry(f"{width}x{height}+{max(0, x)}+{max(0, y)}")
+
+    def _validate_theme_keys(self) -> None:
+        """
+        Hard-fails at construction on an incomplete theme block, naming the
+        missing key.
+
+        Raises:
+            KeyError: naming the first missing key found.
+        """
+        # Resolved the way ThemeableWidget resolves it, so the message names
+        # the block actually read rather than the subclass's own name.
+        name = getattr(self, "_THEME_BLOCK_NAME", None) or self.__class__.__name__
+        for key in self._REQUIRED_THEME_KEYS:
+            if self._local_defaults.get(key) is None:
+                raise KeyError(
+                    f"'{name}' theme block is missing '{key}' at the top level "
+                    f"of sCTkThemes.json."
+                )
+
+    def configure(self, *args, **kwargs):
+        """
+        Standard configuration with positional-argument handling.
+
+        Three separate bugs were fixed here:
+
+        1. `super().configure(args)` passed the whole TUPLE as one positional
+           argument rather than unwrapping it, so every single-argument query
+           forwarded a malformed value.
+        2. `if args and isinstance(args, dict)` -- args is ALWAYS a tuple, so
+           the dict-merge branch was dead code. Same tautology fixed across
+           the batch-one widgets.
+        3. No `config = configure` alias existed, so `.config(...)` bypassed
+           this override entirely and landed on the native widget.
+        """
+        if len(args) == 1:
+            if isinstance(args[0], dict):
+                kwargs = {**args[0], **kwargs}
+            else:
+                # FIX: forwarding a property NAME to native configure()
+                # passes it as require_redraw -- CustomTkinter declares
+                # configure(self, require_redraw=False, **kwargs) -- so the
+                # call returns None, which pygubu then hands straight back to
+                # _set_property(). Reached whenever a field is blanked in the
+                # Designer inspector, which calls configure(name) to read a
+                # property's default and expects a Tkinter-style five-tuple.
+                #
+                # _configure_query() builds one -- see themeable_widget.py.
+                return self._configure_query(args[0])
+
+        self._drop_cleared(kwargs)
+        if kwargs: return super().configure(**kwargs)
+        return None
+
+    # Tkinter binds .config to .configure as a SEPARATE class attribute -- it
+    # does not track a subclass's override. Without this, .config(...) skips
+    # everything above.
+    config = configure
+
+    def _close_dialog(self):
+        self.grab_release()
+        self.destroy()
+
+    def on_ok(self, event=None):
+        self._result = True
+        self._close_dialog()
+
+    def on_yes(self, event=None):
+        self._result = True
+        self._close_dialog()
+
+    def on_no(self, event=None):
+        self._result = False
+        self._close_dialog()
+
+    def wait_end(self) -> Optional[bool]:
+        if self.master: self.master.wait_window(self)
+        else: self.wait_window(self)
+        return self._result
+
+# =====================================================================
+# ⚡ STANDALONE RE-ROUTING CHANNELS (OUTDENTED TO ZERO INDENT SPACES!)
+# =====================================================================
+def showinfo(title: str, message: str, ok_text: str = "Ok", width: int = 400, master: any = None) -> Optional[bool]:
+    return sCTkMessagebox(title, message, "info", master=master, buttons="ok", ok_text=ok_text, width=width).wait_end()
+
+def showwarning(title: str, message: str, ok_text: str = "Ok", width: int = 400, master: any = None) -> Optional[bool]:
+    return sCTkMessagebox(title, message, "warning", master=master, buttons="ok", ok_text=ok_text, width=width).wait_end()
+
+def showerror(title: str, message: str, ok_text: str = "Ok", width: int = 400, master: any = None) -> Optional[bool]:
+    return sCTkMessagebox(title, message, "error", master=master, buttons="ok", ok_text=ok_text, width=width).wait_end()
+
+def askyesno(title: str, message: str, yes_text: str = "Yes", no_text: str = "No", width: int = 400, master: any = None) -> bool:
+    val = sCTkMessagebox(title, message, "info", master=master, buttons="yes_no", yes_text=yes_text, no_text=no_text, width=width).wait_end()
+    return True if val is True else False
+
+def askwarningyesno(title: str, message: str, yes_text: str = "Yes", no_text: str = "No", width: int = 400, master: any = None) -> bool:
+    val = sCTkMessagebox(title, message, "warning", master=master, buttons="yes_no", yes_text=yes_text, no_text=no_text, width=width).wait_end()
+    return True if val is True else False
+
+def askerroryesno(title: str, message: str, yes_text: str = "Yes", no_text: str = "No", width: int = 400, master: any = None) -> bool:
+    val = sCTkMessagebox(title, message, "error", master=master, buttons="yes_no", yes_text=yes_text, no_text=no_text, width=width).wait_end()
+    return True if val is True else False
+
+
+# =====================================================================
+# 🔑 THE DYNAMIC BACK-BIND: Injects attributes onto the Class token namespace!
+# =====================================================================
+# This forces sCTkMessage.showinfo(...) to work perfectly everywhere!
+sCTkMessagebox.showinfo = showinfo
+sCTkMessagebox.showwarning = showwarning
+sCTkMessagebox.showerror = showerror
+sCTkMessagebox.askyesno = askyesno
+sCTkMessagebox.askwarningyesno = askwarningyesno
+sCTkMessagebox.askerroryesno = askerroryesno