scustomtkinter 0.2.1__py3-none-any.whl

scustomtkinter/sctk_dialog_toplevel.py

@@ -0,0 +1,268 @@
+#!/usr/bin/python3
+"""
+sCTkDialogToplevel
+
+The window that holds an sCTkDialog. Owns everything to do with the
+WINDOW -- title, size, placement, modality -- so that sCTkDialog can
+concern itself only with the content inside it.
+
+Previously this class was an empty subclass of CTkToplevel and all of the
+window behaviour lived in a separate sCTkDialogMixin, which callers had to
+add by hand to their generated class. Folding it in here removes that step:
+see Dialogs.md.
+"""
+import tkinter as tk
+
+import customtkinter as ctk
+
+
+class sCTkDialogToplevel(ctk.CTkToplevel):
+    """
+    A top-level window sized, placed and (optionally) made modal on creation.
+
+    Placement is expressed RELATIVE to another window rather than in screen
+    coordinates, because that is what dialogs actually want: appear over the
+    window that opened me, nudged down and right so the parent is still
+    visible behind. Absolute coordinates break the moment the user moves the
+    application window.
+    """
+
+    # Floor for a content-sized window. Explicit width/height below these are
+    # honoured -- a caller asking for 200x100 gets it; these only apply when
+    # the size is being derived from the content.
+    MIN_WIDTH = 320
+    MIN_HEIGHT = 180
+
+    def __init__(self, master=None, *, title=None, width=None, height=None,
+                 locate_over=None, offset_x=40, offset_y=40, modal=False,
+                 transient=True, **kw):
+        """
+        Args:
+            master: The Tk parent. Required for the window to belong to the
+                right interpreter -- see the note below.
+            title: Window title bar text.
+            width: Window width in pixels. Omit to size to content, subject
+                to MIN_WIDTH.
+            height: Window height in pixels. Omit to size to content, subject
+                to MIN_HEIGHT.
+            locate_over: The window this dialog should appear over, and be
+                transient to. Defaults to master's own toplevel.
+
+                Deliberately separate from `master`: a dialog is often
+                parented to a frame or a controller widget while needing to
+                position itself over the main application window. Passing the
+                two separately avoids having to choose.
+            offset_x: Pixels right of locate_over's top-left corner.
+            offset_y: Pixels below it.
+            modal: True to grab input and block interaction with the rest of
+                the application. See _apply_modal() for the ordering this
+                requires.
+            transient: True to tie the window to locate_over -- it stays above
+                that window, minimises with it, and usually keeps out of the
+                taskbar. False gives an independent window, which is what a
+                long-lived tool panel wants. Placement is unaffected either
+                way; only the window-manager relationship changes.
+            **kw: Any native CTkToplevel argument.
+        """
+        # FIX: an extra blank window appeared when master was None.
+        #
+        # tkinter creates a default root implicitly the first time any widget
+        # is made without one -- and that root is a real, visible, empty
+        # window. A dialog constructed with no master therefore produced TWO
+        # windows: the dialog, and a blank one behind it.
+        #
+        # If a root already exists we adopt it. If not, one is created and
+        # immediately withdrawn, so it services the Tcl interpreter without
+        # ever being seen. Withdrawing rather than avoiding it is necessary:
+        # Tk requires a root, and letting tkinter make one silently is exactly
+        # what caused the problem.
+        self._implicit_root = None
+        if master is None:
+            existing = getattr(tk, "_default_root", None)
+            if existing is None:
+                self._implicit_root = ctk.CTk()
+                self._implicit_root.withdraw()
+                master = self._implicit_root
+            else:
+                master = existing
+
+        super().__init__(master, **kw)
+
+        # locate_over defaults to whichever window owns master. winfo_toplevel()
+        # walks up for us, so a dialog parented to a deeply nested frame still
+        # positions itself over the right window.
+        if locate_over is None and master is not None:
+            try:
+                locate_over = master.winfo_toplevel()
+            except Exception:
+                locate_over = None
+        self._locate_over = locate_over
+        self._offset_x = int(offset_x)
+        self._offset_y = int(offset_y)
+        self._requested_width = width
+        self._requested_height = height
+
+        if title:
+            self.title(title)
+
+        # transient() ties the dialog to its parent for the window manager:
+        # it stays above that window and usually skips the taskbar. Done
+        # before placement so the WM has the relationship when the window maps.
+        if transient and self._locate_over is not None:
+            try:
+                self.transient(self._locate_over)
+            except Exception:
+                pass
+
+        self.place_over()
+
+        if modal:
+            self._apply_modal()
+
+    def place_over(self, locate_over=None, offset_x=None, offset_y=None):
+        """
+        Positions the window relative to another one.
+
+        Callable again later -- if the parent window moves and the dialog
+        should follow, or to re-place after a resize.
+
+        Falls back to centring on screen when there is no reference window,
+        which is better than landing at whatever coordinates the window
+        manager chose.
+
+        Args:
+            locate_over: Reference window. Defaults to the one given at
+                construction.
+            offset_x: Pixels right of its top-left corner.
+            offset_y: Pixels below it.
+        """
+        if locate_over is not None:
+            self._locate_over = locate_over
+        if offset_x is not None:
+            self._offset_x = int(offset_x)
+        if offset_y is not None:
+            self._offset_y = int(offset_y)
+
+        # Required before any winfo_* geometry query: without it the values
+        # are whatever they were before the pending layout ran, which for a
+        # freshly created window is 1x1 at 0,0.
+        self.update_idletasks()
+
+        # The minimum applies ONLY to a dimension being derived from content.
+        # An explicit size is honoured exactly: a caller asking for 200x100
+        # gets 200x100, because they had a reason to ask.
+        if self._requested_width:
+            width = self._requested_width
+        else:
+            width = max(self.winfo_reqwidth(), self.MIN_WIDTH)
+
+        if self._requested_height:
+            height = self._requested_height
+        else:
+            height = max(self.winfo_reqheight(), self.MIN_HEIGHT)
+
+        ref = self._locate_over
+        try:
+            usable_ref = ref is not None and ref.winfo_exists()
+        except Exception:
+            usable_ref = False
+
+        if usable_ref:
+            # rootx/rooty rather than x/y: these are screen coordinates, which
+            # is what geometry() expects. x/y would be relative to the parent's
+            # own parent and place the dialog somewhere unrelated.
+            x = ref.winfo_rootx() + self._offset_x
+            y = ref.winfo_rooty() + self._offset_y
+        else:
+            x = (self.winfo_screenwidth() // 2) - (width // 2)
+            y = (self.winfo_screenheight() // 2) - (height // 2)
+
+        # Keep the window on screen. A large offset from a parent near the
+        # right edge would otherwise put the dialog partly or wholly off it.
+        x = max(0, min(x, self.winfo_screenwidth() - width))
+        y = max(0, min(y, self.winfo_screenheight() - height))
+
+        # Always set both dimensions. Setting only the position and letting Tk
+        # size the window works only while nothing has been requested; once a
+        # width is given, Tk keeps whatever height it last computed -- which
+        # was the empty-window height if this ran before the content existed.
+        self.geometry(f"{width}x{height}+{x}+{y}")
+
+    def set_size(self, width=None, height=None):
+        """
+        Changes the window size, keeping it where it is.
+
+        Args:
+            width: New width in pixels, or None to leave it. Pass 0 or an
+                empty value to go back to sizing to content.
+            height: Same, for height.
+        """
+        if width is not None:
+            self._requested_width = int(width) if width else None
+        if height is not None:
+            self._requested_height = int(height) if height else None
+        self.place_over()
+
+    def get_size(self):
+        """
+        Returns the window's (width, height).
+
+        Reports the REQUESTED size where one was given, and the actual size
+        otherwise -- so a dialog sized to its content reports what it really
+        is rather than None.
+        """
+        try:
+            self.update_idletasks()
+            actual_w, actual_h = self.winfo_width(), self.winfo_height()
+        except Exception:
+            actual_w = actual_h = 0
+        return (self._requested_width or actual_w,
+                self._requested_height or actual_h)
+
+    def _apply_modal(self):
+        """
+        Takes an input grab, blocking interaction with the rest of the
+        application.
+
+        wait_visibility() first is NOT optional: on X11 a grab on a window
+        that is not yet viewable raises TclError. It is harmless on macOS and
+        Windows, so it is done unconditionally rather than platform-tested.
+        """
+        try:
+            self.wait_visibility()
+            self.grab_set()
+        except Exception:
+            # Window destroyed between construction and this call.
+            pass
+
+    def destroy(self):
+        """
+        Destroys the window, and the implicit root if this widget created one.
+
+        Without this, a dialog built with no master would leave the withdrawn
+        root alive after closing and the interpreter would never exit.
+        """
+        implicit = getattr(self, "_implicit_root", None)
+        super().destroy()
+        if implicit is not None:
+            try:
+                implicit.destroy()
+            except Exception:
+                pass
+
+    def release_modal(self):
+        """Releases the input grab, leaving the window open but non-blocking."""
+        try:
+            self.grab_release()
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    root = ctk.CTk()
+    ctk.CTkButton(
+        root, text="Open dialog window",
+        command=lambda: sCTkDialogToplevel(
+            root, title="Example", width=320, height=200, modal=True),
+    ).pack(padx=40, pady=40)
+    root.mainloop()

scustomtkinter/sctk_entry_primary.py

@@ -0,0 +1,400 @@
+#!/usr/bin/python3
+"""
+sCTkEntryPrimary
+
+A theme-compliant, high-emphasis single-line text entry widget -- the more
+prominent of the library's two entry tiers (see also sCTkEntrySecondary).
+Inherits directly from ctk.CTkEntry so CustomTkinter handles native rendering
+and text editing; this class layers automatic light/dark theme resolution and
+a distinct enabled/disabled visual state on top.
+
+Base class order matters here: `class sCTkEntryPrimary(ctk.CTkEntry,
+ThemeableWidget)` puts the native CTk class first, so every `super()` call in
+this file's own methods resolves to ctk.CTkEntry -- 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.
+
+Disabling uses CTk's native state="disabled", consistent with every other
+widget in this library confirmed to correctly block interaction this way (the
+button family, sCTkSegmentedButton, sCTkOptionMenuPrimary). An earlier version
+used native "readonly" instead, on an unverified claim that "disabled" caused
+CustomTkinter rendering issues -- tested directly and confirmed unnecessary
+for the disabled/normal distinction.
+
+Now supports a genuine three-state model: normal / readonly / disabled,
+matching real ttk.Spinbox semantics (readonly means the field can't be typed
+into directly, but stays focusable/selectable -- distinct from disabled,
+which blocks all interaction). Added specifically to support sCTkSpinbox's
+own readonly mode correctly, which previously collapsed everything
+non-disabled into "normal", silently discarding any readonly request. Uses
+CTk's native state="readonly", the third of the three real Tk Entry states
+(normal/readonly/disabled) -- not independently confirmed by direct testing
+the way disabled/normal were; test readonly specifically, including the
+disable/enable-cycle cursor-placeholder scenario already confirmed and fixed
+for the normal<->disabled transition, since readonly hasn't been checked
+against that same failure mode.
+"""
+from typing import Any, Optional
+import customtkinter as ctk
+from .themeable_widget import ThemeableWidget, defer
+
+
+class sCTkEntryPrimary(ctk.CTkEntry, ThemeableWidget):
+    """Themeable, high-emphasis text entry field.
+
+    Adds to native ctk.CTkEntry:
+      - 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 genuine three-state visual model: normal / readonly / disabled,
+        using CTk's native state option for all three (state="normal"
+        confirmed correct by direct testing; state="disabled" confirmed
+        correct by direct testing; state="readonly" not independently
+        confirmed -- see module docstring).
+      - Pygubu Designer property introspection for `state`, `fg_color`,
+        `text_color`, `border_color`, and `placeholder_text_color` via a
+        single-argument configure() call.
+
+    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.
+
+    placeholder_text_color is a real, themed key (not a fallback to
+    text_color) -- confirmed against CustomTkinter's own shipped themes, where
+    it's deliberately more muted than the main text color (e.g. gray52/gray62
+    vs. gray14/gray84 in the stock dark-blue theme). Note CTkEntry has no
+    separate font for placeholder text vs. typed text -- both always share the
+    single `font` property; this is a real ceiling in the underlying widget,
+    not a gap in this theme file.
+    """
+
+    def __init__(self, master: Optional[Any] = None, **kw: Any) -> None:
+        """
+        Args:
+            master: Parent container.
+            **kw: Any native CTkEntry argument (e.g. `placeholder_text`,
+                `width`), or a theme-key override (see the "sCTkEntryPrimary"
+                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.
+        ThemeableWidget.__init__(self, kw)
+
+        # 2. Deep-copy the resolved map onto this instance, so later changes
+        # here never leak back into the shared theme registry.
+        self._local_defaults = dict(self.final_kw)
+        self._custom_disabled_map = dict(self._widget_disabled_map)
+        # readonly_map: see module docstring for the three-state model this
+        # supports. Required only when readonly is actually requested -- see
+        # _update_current_visual_state()'s validation.
+        self._custom_readonly_map = dict(self._widget_readonly_map)
+
+        # Extract "state" from final_kw (after ThemeableWidget's merge, unlike
+        # the label widgets which extract it from kw before that merge) --
+        # this means an explicit state= kwarg correctly overrides any
+        # "state" the theme JSON might define at the top level, since kwargs
+        # are merged into final_kw after the theme defaults. Not a bug, just
+        # a different valid approach from the label family's.
+        state_init = self.final_kw.pop("state", "normal")
+
+        # 3. Initialize CustomTkinter natively with the clean final kwargs array.
+        super().__init__(master, **self.final_kw)
+
+        # 4. Apply the requested initial state now that the native widget exists.
+        self._custom_current_state = "normal"
+        self.state(state_init)
+
+        # 5. Register lifecycle handshake hook, notifying Pygubu-style consumers
+        # that construction is complete.
+        self._finalize_themeable_lifecycle()
+
+    def configure(self, *args: Any, **kwargs: Any) -> Any:
+        """
+        Standard widget configuration, with Pygubu/positional-argument handling.
+
+        Args:
+            *args: At most one positional argument is meaningful:
+                - a dict: merged into kwargs and processed normally below.
+                - the literal string "state": returns a Tkinter-style
+                  (name, name, name, default, current) tuple.
+                - one of "fg_color"/"text_color"/"border_color"/
+                  "placeholder_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 CTkEntry 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, and the fallback forwarded the wrapped
+        # tuple itself to super().configure() -- 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", "text_color", "border_color", "placeholder_text_color"]:
+                    current = self._custom_current_state
+                    if current == "disabled":
+                        val = self._custom_disabled_map.get(pname)
+                    elif current == "readonly":
+                        val = self._custom_readonly_map.get(pname)
+                    else:
+                        val = self._local_defaults.get(pname)
+                    return (pname, pname, pname, self._query_value(self._theme_default(pname)), self._query_value(val))
+
+                return self._configure_query(pname)
+
+        # Runtime overrides have to reach the map a repaint reads, or the
+        # repaint 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"))
+
+        self._drop_cleared(kwargs)
+
+        if kwargs:
+            return super().configure(**kwargs)
+        return None
+
+    # Tkinter/CTk convention binds .config to .configure as a SEPARATE class
+    # attribute -- it does not automatically track whichever configure() a
+    # subclass defines. Without this line, calling .config(...) on an instance
+    # would silently skip this entire override and land on the native widget's
+    # configure() directly, bypassing theming and state handling entirely.
+    config = configure
+
+    def _set_appearance_mode(self, mode_string: str) -> None:
+        """
+        Forwards CustomTkinter's internal light/dark mode change notification to
+        the native widget.
+
+        No longer manually re-triggers _update_current_visual_state(). That
+        method now passes raw (light, dark) tuples straight through to
+        configure() instead of pre-resolving to a single color, so CTk's own
+        appearance-mode tracking should repaint correctly on its own -- the
+        same approach validated on sCTkComboBox, sCTkSegmentedButton, and 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 _write_through_state(self, action, *args, **kwargs):
+        """
+        Runs a text-modifying call even when the field is disabled.
+
+        A disabled Tk entry silently ignores insert() and delete() -- no error,
+        no text. That bites in generated code, because pygubu emits the state
+        before the content:
+
+            sctkentryprimary1.configure(state="disabled")
+            sctkentryprimary1.delete(0, "end")
+            sctkentryprimary1.insert(0, 'mark')
+
+        which produced a permanently empty disabled field. Setting text on a
+        disabled widget is a normal thing for an application to do -- the state
+        is about what the USER may edit, not about what the program may write.
+
+        The native state is lifted for the write and restored afterwards, which
+        is the same approach sCTkPathChooser.set() already uses. The widget's
+        own _custom_current_state is untouched, so the colours do not flicker.
+
+        Args:
+            action: The bound native method to call.
+            *args, **kwargs: Passed through to it.
+
+        Returns:
+            Whatever the native method returns.
+        """
+        was_disabled = self._custom_current_state == "disabled"
+        if was_disabled:
+            try:
+                super().configure(state="normal")
+            except Exception:
+                was_disabled = False
+        try:
+            return action(*args, **kwargs)
+        finally:
+            if was_disabled:
+                try:
+                    super().configure(state="disabled")
+                except Exception:
+                    pass
+
+    def insert(self, *args, **kwargs):
+        """Inserts text, even while disabled -- see _write_through_state()."""
+        return self._write_through_state(super().insert, *args, **kwargs)
+
+    def delete(self, *args, **kwargs):
+        """Deletes text, even while disabled -- see _write_through_state()."""
+        return self._write_through_state(super().delete, *args, **kwargs)
+
+    def get_state(self) -> str:
+        """Equivalent to calling state() with no argument."""
+        return self.state()
+
+    def state(self, state_string: Optional[str] = None) -> str:
+        """
+        Gets or sets the widget's normal/readonly/disabled visual state.
+
+        Args:
+            state_string: If None, returns the current state without changing
+                anything. Otherwise: "normal"/"enabled"/"active" all map to
+                "normal"; "readonly" (case-insensitive) maps to "readonly";
+                "disabled" (case-insensitive) maps to "disabled". Any other
+                value matches none of these and leaves the internal state flag
+                unchanged, though _update_current_visual_state() still runs
+                (harmlessly re-applying the same colors).
+
+        Returns:
+            The resulting state ("normal", "readonly", or "disabled", lowercase).
+        """
+        if state_string is None:
+            return getattr(self, "_custom_current_state", "normal")
+
+        mode = str(state_string).lower()
+        if mode in ("normal", "enabled", "active"):
+            self._custom_current_state = "normal"
+        elif mode == "readonly":
+            self._custom_current_state = "readonly"
+        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, then sets the native interactive lock.
+
+        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.
+        Every value here traces back to sCTkThemes.json; there are no
+        hardcoded colors in this method.
+
+        fg_color, border_color, text_color, and placeholder_text_color are
+        required to be present in readonly_map specifically when readonly is
+        the current state -- if any are missing, this raises immediately
+        rather than substituting a hardcoded color or silently falling back
+        to normal/disabled colors. This check only runs when readonly is
+        actually requested, so existing code that never uses readonly is
+        unaffected regardless of whether readonly_map exists in the theme
+        file yet.
+        """
+        current = self._custom_current_state
+
+        if current == "disabled":
+            target_map = self._custom_disabled_map
+        elif current == "readonly":
+            target_map = self._custom_readonly_map
+            for required_key in ("fg_color", "border_color", "text_color", "placeholder_text_color"):
+                if target_map.get(required_key) is None:
+                    raise KeyError(
+                        f"'{self.__class__.__name__}' theme block is missing '{required_key}' "
+                        f"in readonly_map -- required because state 'readonly' was requested."
+                    )
+        else:
+            target_map = self._local_defaults
+
+        config_payload = {}
+        for key in ("fg_color", "border_color", "text_color", "placeholder_text_color"):
+            val = target_map.get(key)
+            if val is not None:
+                config_payload[key] = val
+
+        if config_payload:
+            super().configure(**config_payload)
+
+        # Confirmed correct by direct testing: native "disabled" properly
+        # blocks interaction. state="readonly" is the third real native Tk
+        # Entry state (normal/readonly/disabled) but is NOT independently
+        # confirmed here -- see module docstring. Deferred cursor-reset is
+        # applied for both normal and readonly, since both leave the field
+        # focusable/showable; whether readonly specifically needs it (i.e.
+        # whether the same disable/enable-cycle bug applies to a
+        # disabled<->readonly or normal<->readonly transition) has not been
+        # tested.
+        if current == "disabled":
+            super().configure(state="disabled")
+        else:
+            super().configure(state=current)
+            defer(self, "idle", self._reset_cursor_if_showing_placeholder)
+
+    def _reset_cursor_if_showing_placeholder(self) -> None:
+        """
+        Resets the cursor to position 0, but only if the field is currently
+        showing its placeholder text -- never touches the cursor if the field
+        holds real user-typed content.
+
+        FIX: after a disable -> enable cycle, clicking the field placed the
+        cursor at the END of the placeholder text instead of position 0 --
+        confirmed by direct testing. Likely cause: CustomTkinter's own
+        placeholder system re-inserts the placeholder string when the widget
+        regains a non-focused, empty state (which disabling appears to
+        trigger via focus loss), and a plain text insert leaves the cursor
+        positioned after whatever was just inserted -- i.e. at the end --
+        unless something explicitly resets it afterward. Deferred via
+        after_idle so this runs after CTk's own internal refresh, the same
+        reasoning as the after_idle fix on sCTkButtonPrimary's state-
+        transition race.
+
+        Now also called on transitions into "readonly", not just "normal" --
+        this was confirmed and fixed specifically for the disabled<->normal
+        transition; whether the same underlying mechanism (or something else
+        entirely) affects a disabled<->readonly or normal<->readonly
+        transition has not been independently tested. Calling this
+        unconditionally on both non-disabled states is a precaution, not a
+        confirmed necessity for readonly specifically.
+
+        Deliberately does NOT use CTkEntry's private, underscore-prefixed
+        internal attributes (e.g. self._is_focused, self._activate_placeholder())
+        to detect placeholder state, even though those exist -- relying on
+        undocumented internals would break silently on a future CustomTkinter
+        version. Since the placeholder is implemented by genuinely inserting
+        the placeholder string as the field's real text content (confirmed
+        from CustomTkinter's own source), comparing self.get() against the
+        configured placeholder_text via public, documented API achieves the
+        same result without that risk. The only false-positive case is a user
+        typing content that exactly matches the placeholder text verbatim, in
+        which case resetting the cursor to 0 is a harmless, barely-noticeable
+        side effect, not a real problem.
+        """
+        placeholder = self.cget("placeholder_text")
+        if placeholder and self.get() == placeholder:
+            self.icursor(0)