scustomtkinter 0.2.1__py3-none-any.whl

scustomtkinter_pygubu/sCTkNotebookbo.py

@@ -0,0 +1,392 @@
+#!/usr/bin/python3
+"""
+sCTkNotebook
+
+Pygubu builder objects for the vertical-tab notebook and for the tabs
+themselves.
+
+A TAB IS NOT A WIDGET. It is created by its notebook, through add(), so the
+tab builder object has no class of its own to instantiate -- it calls the
+parent's add() and hands back the sCTkFrame that comes out. Generated code
+reads:
+
+    tab1 = notebook1.add("Receiver")
+
+which is the same arrangement sCTkTabviewbo uses for CTkTabview's tabs, and
+for the same reason.
+"""
+import tkinter as tk
+
+from pygubu.api.v1 import (
+    BuilderObject,
+    register_widget,
+    register_custom_property,
+)
+from pygubu.plugins.customtkinter.widgets import CTkFrameBO
+
+from scustomtkinter.sctk_notebook import sCTkNotebook
+
+widget_namespace = "scustomtkinter.sctk_notebook"
+widget_classname = "sCTkNotebook"
+builder_namespace = "scustomtkinter"
+section_name = "sCustomTkinter"
+
+
+class sCTkNotebookBO(CTkFrameBO):
+    class_ = sCTkNotebook
+
+    OPTIONS_CUSTOM = (
+        "side", "tab_width", "tab_style", "text_orientation",
+        "show_page_border", "show_tab_separators", "state",
+    )
+    # "command" IS IN properties, as well as in command_properties. The
+    # Designer lists only what is in `properties`; command_properties does
+    # not add to that list, it marks which listed properties are commands, to
+    # be connected to a callback rather than set as a value. Declared only in
+    # command_properties, it was registered and never shown. Pygubu's own
+    # Button declares its command in both.
+    #
+    # It stays out of OPTIONS_CUSTOM: pygubu connects it after construction,
+    # through configure(command=...), so realize() below does not pass it.
+    properties = CTkFrameBO.properties + OPTIONS_CUSTOM + ("command",)
+    command_properties = ("command",)
+
+    OPTIONS_CUSTOM_DEFAULTS = {
+        "side": "left",
+        "tab_width": "34",
+        "tab_style": "rounded",
+        "text_orientation": "auto",
+        "show_page_border": "True",
+        "show_tab_separators": "False",
+        "state": "normal",
+    }
+
+    # A container, but only for its own tabs -- see allowed_children below.
+    container = True
+    container_layout = False
+
+    def realize(self, parent, extra_init_args: dict = None):
+        """
+        Builds the notebook with its own properties as constructor arguments.
+
+        side and tab_style are validated by the widget and raise on a bad
+        value, so they have to arrive as real values rather than being set
+        afterwards -- a half-built widget in the Designer is worse than a
+        clear error.
+        """
+        if extra_init_args is None:
+            extra_init_args = {}
+
+        props = self.wmeta.properties
+        init_args = {
+            "side": props.get("side", "left"),
+            "tab_style": props.get("tab_style", "rounded"),
+            "text_orientation": props.get("text_orientation", "auto"),
+            "tab_width": int(props.get("tab_width", 34) or 34),
+            "show_page_border": self._as_bool(props.get("show_page_border", "True")),
+            "show_tab_separators": self._as_bool(
+                props.get("show_tab_separators", "False")),
+            "state": props.get("state", "normal"),
+        }
+
+        for prop in self.OPTIONS_CUSTOM:
+            extra_init_args.pop(prop, None)
+        init_args.update(extra_init_args)
+
+        real_master = parent.widget if hasattr(parent, "widget") else parent
+        self.widget = self.class_(real_master, **init_args)
+        return self.widget
+
+    @staticmethod
+    def _as_bool(value):
+        """
+        Parses the Designer's strings.
+
+        bool("False") is True, which would switch on every option whose
+        dropdown said otherwise.
+        """
+        if isinstance(value, str):
+            return value.strip().lower() in ("true", "1", "yes", "on")
+        return bool(value)
+
+    def _process_property_value(self, pname, value):
+        if pname == "tab_width":
+            return int(value)
+        if pname in ("show_page_border", "show_tab_separators"):
+            return self._as_bool(value)
+        return super()._process_property_value(pname, value)
+
+    def _code_set_property(self, targetid, pname, value, code_bag):
+        """Booleans and the width emit as tokens; the rest keep their quotes."""
+        if pname in ("show_page_border", "show_tab_separators", "tab_width"):
+            code_bag[pname] = str(value).strip("'\"")
+        elif pname in ("side", "tab_style", "text_orientation", "state"):
+            code_bag[pname] = f"'{str(value).strip(chr(39) + chr(34))}'"
+        else:
+            super()._code_set_property(targetid, pname, value, code_bag)
+
+    def _code_define_callback_args(self, cmd_pname, cmd):
+        """
+        Declares that `command` receives the tab's name, so the generated
+        handler stub has a matching parameter.
+
+        Without it a handler written from the stub would have no indication
+        that the selected tab is being handed to it -- which is the entire
+        point of the callback.
+        """
+        return ("tab",)
+
+    def code_imports(self):
+        imports = [(widget_namespace, widget_classname)]
+        imports.extend(self.code_extra_imports())
+        return imports
+
+
+builder_id = f"{builder_namespace}.{widget_classname}"
+register_widget(builder_id, sCTkNotebookBO, widget_classname,
+                ("ttk", section_name))
+
+
+# ---------------------------------------------------------------------------
+# The tab
+# ---------------------------------------------------------------------------
+class sCTkNotebookTabBO(BuilderObject):
+    """
+    A page in an sCTkNotebook.
+
+    Has no class_ of its own: a tab is made by the notebook's add(), which
+    returns the sCTkFrame that children are then parented to.
+    """
+
+    class_ = None
+    container = True
+    container_layout = True
+    layout_required = False
+    allow_bindings = False
+    properties = ("label",)
+    OPTIONS_CUSTOM_DEFAULTS = {"label": "Tab"}
+
+    def realize(self, parent, extra_init_args: dict = None):
+        """
+        Asks the parent notebook for a page.
+
+        DUPLICATE NAMES ARE RENAMED, NOT REJECTED. The widget's own add()
+        raises ValueError on a name already in use, which is right for
+        application code -- but inside the Designer that exception surfaces
+        only on the console, where nobody sees it, and the tab silently fails
+        to appear while the tree and the preview disagree. A numeric suffix is
+        appended instead, visibly, in both the tab strip and the property
+        field. Same accommodation sCTkTabviewbo makes.
+        """
+        master = parent.widget if hasattr(parent, "widget") else parent
+        label = self.wmeta.properties.get("label", self.wmeta.identifier)
+
+        existing = master.tabs()
+        if label in existing:
+            suffix = 2
+            while f"{label}_{suffix}" in existing:
+                suffix += 1
+            label = f"{label}_{suffix}"
+            self.wmeta.properties["label"] = label
+
+        self._label = label
+        self.widget = master.add(label)
+        return self.widget
+
+    def _set_property(self, target_widget, pname, value):
+        """
+        Rebuilds the notebook when a tab is renamed.
+
+        A tab's label is consumed by realize() -- it is the name add() was
+        called with -- so changing it afterwards cannot be expressed by
+        configuring the existing page. Without a rebuild the strip went on
+        showing the old caption until some unrelated edit forced a repaint.
+
+        recreate_widget() is what the Designer itself does when you add or
+        delete a widget, which is why doing that by hand made the change
+        appear. It hangs off _set_property, NOT set_property: the Designer
+        edits a property through the former, and the latter is never called.
+        """
+        if pname == "label":
+            # CONSUMED, not delegated, and not acted on here either.
+            #
+            # The base implementation forwards an unknown property to
+            # widget.configure(), and a page is an ordinary sCTkFrame:
+            #
+            #     Failed to set property 'label' on class 'None'.
+            #     Error: ['label'] are not supported arguments.
+            #
+            # The rename itself happens in configure(), which is the call the
+            # Designer makes after updating the metadata -- see there.
+            return
+
+        super()._set_property(target_widget, pname, value)
+
+    @staticmethod
+    def _find_notebook(page):
+        """
+        Climbs from a page to the notebook that owns it.
+
+        A page is parented to the notebook's internal page host, not to the
+        notebook, so the immediate parent is the wrong object.
+        """
+        try:
+            top = page.winfo_toplevel()
+            widget = page
+            for _ in range(4):
+                parent_name = widget.winfo_parent()
+                if not parent_name:
+                    return None
+                widget = top.nametowidget(parent_name)
+                if hasattr(widget, "rename") and hasattr(widget, "tabs"):
+                    return widget
+        except Exception:
+            pass
+        return None
+
+    def configure(self, target=None):
+        """
+        Applies a changed `label` by renaming the live tab.
+
+        THIS IS WHERE THE RENAME BELONGS, not in _set_property. The Designer
+        edits the metadata and then calls configure(); a no-op here left the
+        design canvas showing the old caption while the preview, which
+        rebuilds from scratch, showed the new one. sCTkTabviewTabBO learned
+        the same lesson and its docstring records it.
+
+        EVERYTHING IS DERIVED FROM self.widget, deliberately. Pygubu calls
+        configure() on builder objects whose realize() never ran, so any state
+        stashed during realize() -- the notebook, the name it was filed under
+        -- may simply not be there. The page is the only reliable anchor: walk
+        up from it to the notebook, then find the page in that notebook's
+        registry BY IDENTITY to learn what it is currently called.
+        """
+        widget = getattr(self, "widget", None)
+        if widget is None:
+            return
+
+        notebook = self._find_notebook(widget)
+        if notebook is None:
+            return
+
+        # Found by identity rather than by trusting a stored name.
+        old_name = None
+        for name, page in getattr(notebook, "_pages", {}).items():
+            if page is widget:
+                old_name = name
+                break
+        if old_name is None:
+            return
+
+        new_name = str(self.wmeta.properties.get("label", old_name))
+        if not new_name or new_name == old_name:
+            return
+
+        existing = [n for n in notebook.tabs() if n != old_name]
+        if new_name in existing:
+            suffix = 2
+            while f"{new_name}_{suffix}" in existing:
+                suffix += 1
+            new_name = f"{new_name}_{suffix}"
+            self.wmeta.properties["label"] = new_name
+
+        try:
+            notebook.rename(old_name, new_name)
+            self._label = new_name
+        except Exception:
+            # Torn down mid-edit. The preview rebuild still shows the new
+            # label, so this degrades rather than breaks.
+            return
+
+    def layout(self, target=None, *args, **kwargs):
+        """The notebook grids its own pages; a tab takes no layout."""
+        pass
+
+    def code_realize(self, boparent, code_identifier=None):
+        identifier = code_identifier or self.code_identifier()
+        label = self.wmeta.properties.get("label", "Tab")
+        return (f'{identifier} = {boparent.code_child_master()}'
+                f'.add("{label}")',)
+
+    def code_configure(self, targetid=None):
+        return tuple()
+
+    def code_layout(self, targetid=None, parentid=None):
+        return tuple()
+
+
+# ONE dot in the id, not two.
+#
+# pygubu splits a classname on "." to work out which module to import, so
+# "scustomtkinter.sCTkNotebook.Tab" made that split return a list and the
+# generated code failed on load:
+#
+#     AttributeError: 'list' object has no attribute 'startswith'
+#
+# The DISPLAY name still reads "sCTkNotebook.Tab" -- that is what appears in
+# the palette. sCTkTabviewbo uses exactly this pairing.
+tab_builder_id = f"{builder_namespace}.sCTkNotebookTab"
+register_widget(tab_builder_id, sCTkNotebookTabBO,
+                f"{widget_classname}.Tab", ("ttk", section_name))
+
+# A tab has nowhere else to live, so it is offered only inside a notebook.
+sCTkNotebookTabBO.allowed_parents = (builder_id,)
+sCTkNotebookBO.allowed_children = (tab_builder_id,)
+
+
+# ---------------------------------------------------------------------------
+# Inspector properties
+# ---------------------------------------------------------------------------
+register_custom_property(
+    builder_id, "side", "choice", values=("left", "right"),
+    state="readonly", default_value="left",
+    help="Which edge the tab strip sits on.")
+
+register_custom_property(
+    builder_id, "tab_width", "naturalnumber", default_value="34",
+    help="Width of the strip in pixels. Explicit rather than measured, "
+         "because the strip takes space from the pages. Horizontal text "
+         "needs this wide enough to hold the longest label.")
+
+register_custom_property(
+    builder_id, "tab_style", "choice", values=("rounded", "angled"),
+    state="readonly", default_value="rounded",
+    help="Rounded matches the rest of the library. Angled cuts the outer "
+         "corners, the shape of a real notebook divider.")
+
+register_custom_property(
+    builder_id, "text_orientation", "choice",
+    values=("auto", "up", "down", "horizontal"),
+    state="readonly", default_value="auto",
+    help="auto reads outside-in and flips with the side. up and down pin the "
+         "direction whichever side the strip is on. horizontal lays the text "
+         "flat and needs a wider tab_width.")
+
+register_custom_property(
+    builder_id, "show_page_border", "choice", values=("True", "False"),
+    state="readonly", default_value="True",
+    help="Draws the outline around the page, broken where the selected tab "
+         "meets it.")
+
+register_custom_property(
+    builder_id, "show_tab_separators", "choice", values=("True", "False"),
+    state="readonly", default_value="False",
+    help="A line between adjacent tabs. Earns its keep with horizontal text, "
+         "where stacked labels can run together; rarely otherwise.")
+
+register_custom_property(
+    builder_id, "state", "choice", values=("normal", "disabled"),
+    state="readonly", default_value="normal",
+    help="Disabled dims the strip and stops tab selection. It does not "
+         "cascade to the widgets on a page.")
+
+register_custom_property(
+    builder_id, "command", "commandentry",
+    help="Called with the tab's name when the operator clicks a tab. Not "
+         "called when a tab is selected in code with set() -- the "
+         "application already knows what it chose.")
+
+register_custom_property(
+    tab_builder_id, "label", "entry", default_value="Tab",
+    help="The tab's caption, and the name add() is called with. A duplicate "
+         "is renamed with a numeric suffix rather than rejected.")

scustomtkinter_pygubu/sCTkOptionMenuPrimarybo.py

@@ -0,0 +1,45 @@
+#!/usr/bin/python3
+"""
+sCTkOptionMenuPrimary
+
+Tailored version of the standard ctkOptionMenu
+
+UI source file: sCTkOptionMenuPrimary.ui
+"""
+import tkinter as tk
+import tkinter.ttk as ttk
+from customtkinter import CTkOptionMenu
+from pygubu.api.v1 import (
+    BuilderObject,
+    register_widget,
+)
+
+from pygubu.plugins.customtkinter.widgets import CTkOptionMenuBO
+from scustomtkinter.sctk_optionmenu_primary import sCTkOptionMenuPrimary
+
+
+#
+# Builder definition section
+#
+widget_namespace = "scustomtkinter.sctk_optionmenu_primary"
+widget_classname = "sCTkOptionMenuPrimary"
+builder_namespace = "scustomtkinter"
+section_name = "sCustomTkinter"
+
+
+class sCTkOptionMenuPrimaryBO(CTkOptionMenuBO):
+    class_ = sCTkOptionMenuPrimary
+
+    def code_imports(self):
+        # should return an iterable of (module, classname/function) to import
+        # or None
+        imports = [(widget_namespace, widget_classname)]
+        imports.extend(self.code_extra_imports())
+        return imports
+
+
+builder_id = f"{builder_namespace}.{widget_classname}"
+register_widget(
+    builder_id, sCTkOptionMenuPrimaryBO, widget_classname, ("ttk", section_name)
+)
+

scustomtkinter_pygubu/sCTkOptionMenuSecondarybo.py

@@ -0,0 +1,39 @@
+#!/usr/bin/python3
+
+import tkinter as tk
+import tkinter.ttk as ttk
+from customtkinter import CTkOptionMenu
+from pygubu.api.v1 import (
+    BuilderObject,
+    register_widget,
+)
+
+from pygubu.plugins.customtkinter.widgets import CTkOptionMenuBO
+from scustomtkinter.sctk_optionmenu_secondary import sCTkOptionMenuSecondary
+
+
+#
+# Builder definition section
+#
+widget_namespace = "scustomtkinter.sctk_optionmenu_secondary"
+widget_classname = "sCTkOptionMenuSecondary"
+builder_namespace = "scustomtkinter"
+section_name = "sCustomTkinter"
+
+
+class sCTkOptionMenuSecondaryBO(CTkOptionMenuBO):
+    class_ = sCTkOptionMenuSecondary
+
+    def code_imports(self):
+        # should return an iterable of (module, classname/function) to import
+        # or None
+        imports = [(widget_namespace, widget_classname)]
+        imports.extend(self.code_extra_imports())
+        return imports
+
+
+builder_id = f"{builder_namespace}.{widget_classname}"
+register_widget(
+    builder_id, sCTkOptionMenuSecondaryBO, widget_classname, ("ttk", section_name)
+)
+

scustomtkinter_pygubu/sCTkPathChooserbo.py

@@ -0,0 +1,204 @@
+#!/usr/bin/python3
+"""
+sCTkPathChooser
+
+Pygubu Builder Object for the compound sCTkPathChooser entry widget row.
+"""
+import pygubu
+
+from pygubu.api.v1 import (
+    BuilderObject,
+    register_widget,
+    register_custom_property
+)
+
+# Import the native custom class
+from scustomtkinter.sctk_path_chooser import sCTkPathChooser
+from pygubu.plugins.customtkinter.widgets import CTkFrameBO
+
+#
+# Builder definition section
+#
+widget_namespace = "scustomtkinter.sctk_path_chooser"
+widget_classname = "sCTkPathChooser"
+builder_namespace = "scustomtkinter"
+section_name = "sCustomTkinter"
+
+
+class sCTkPathChooserBO(BuilderObject):
+    class_ = sCTkPathChooser
+
+    # Expose custom compound parameters alongside theme state configurations
+    OPTIONS_CUSTOM = ("width", "height", "type", "title", "initialdir", "initialfile", "filetypes", "state", "command", "btn_width", "btn_height", "btn_text", "entry_height", "browser_width", "browser_height", "justify")
+    properties = CTkFrameBO.properties + OPTIONS_CUSTOM
+
+    command_properties = ("command",)
+
+    def _process_property_value(self, pname, value):
+        """Passes values directly to allow core widget validations to handle exceptions."""
+        return super()._process_property_value(pname, value)
+
+    def _code_define_callback_args(self, cmd_pname, cmd):
+        """
+        Declares what the callback receives, so the generated stub has a
+        matching parameter.
+
+        Without this, pygubu generates a stub taking no arguments and the
+        widget calls it with the chosen path:
+
+            TypeError: on_path() takes 1 positional argument but 2 were given
+        """
+        return ("selected_path",)
+
+    def _code_set_property(self, targetid, pname, value, code_bag):
+        """
+        Emits `filetypes` as a real Python list, not a quoted string.
+
+        The bracketed form contains double quotes, and the default handler
+        wraps the whole value in double quotes again:
+
+            sctkpathchooser1.configure(filetypes="[".py"]", ...)
+                                                 ^^^^^^^^^
+            SyntaxError: invalid syntax
+
+        Emitting the literal unquoted gives valid Python and a real list. A
+        bare comma-separated value has no brackets and no quotes, so it is
+        emitted as a quoted string and parsed by the widget as usual.
+        """
+        if pname == "filetypes" and value:
+            text = str(value).strip()
+            if text.startswith("[") and text.endswith("]"):
+                code_bag[pname] = text
+                return None
+        return super()._code_set_property(targetid, pname, value, code_bag)
+
+
+# Register the widget into Pygubu's parsing engine
+builder_id = f"{builder_namespace}.{widget_classname}"
+
+register_widget(builder_id, sCTkPathChooserBO, 'sCTkPathChooser', ("ttk", section_name))
+
+
+# Map the 'command' option directly to Pygubu's native callback editor panel
+register_custom_property(
+    builder_id,
+    "command",
+    "commandentry",
+    help="Method callback string triggered on path confirmation"
+)
+
+
+# Register custom attribute fields to display inside the Designer properties panel
+
+register_custom_property(
+    builder_id,
+    "width",
+    "naturalnumber",
+    help="Set total width in pixels of file entry and button. File path width = width - button width"
+)
+
+register_custom_property(
+    builder_id,
+    "height",
+    "naturalnumber",
+    help="Set height in pixels allocated to file path and button frame. Button and file path height set separately."
+)
+
+register_custom_property(
+    builder_id,
+    "type",
+    "choice",
+    values=("", "file", "directory"),
+    state="readonly",
+    default_value="directory",
+    help="What the chooser selects. The widget's own default is 'directory'; "
+         "filetypes only applies when this is 'file'."
+)
+
+register_custom_property(
+    builder_id,
+    "justify",
+    "choice",
+    values=("", "left", "right", "center"),
+    state="readonly",
+    help="Align long path strings to prioritize viewing starting roots or trailing filenames"
+)
+
+register_custom_property(
+    builder_id,
+    "title",
+    "entry",
+    help="Window header title string text"
+)
+
+register_custom_property(
+    builder_id,
+    "initialdir",
+    "entry",
+    help="Starting directory path location string"
+)
+
+register_custom_property(
+    builder_id,
+    "initialfile",
+    "entry",
+    help="Starting target highlight file path string"
+)
+
+register_custom_property(
+    builder_id,
+    "filetypes",
+    "entry",
+    help='Filter by file extension. Preferred: [".py", ".txt"]. Bare comma-separated (.py, .txt) also works, but cannot contain a comma inside a value.'
+)
+
+register_custom_property(
+    builder_id,
+    "entry_height",
+    "naturalnumber",
+    help="Set height in pixels of the file path field widget"
+)
+
+register_custom_property(
+    builder_id,
+    "btn_width",
+    "naturalnumber",
+    help="Set width in pixels of the button"
+)
+
+register_custom_property(
+    builder_id,
+    "btn_height",
+    "naturalnumber",
+    help="Set height in pixels of the button"
+)
+
+register_custom_property(
+    builder_id,
+    "btn_text",
+    "entry",
+    help="Override default button text (e.g. 'Select', '▶' or '>')"
+)
+
+register_custom_property(
+    builder_id,
+    "browser_width",
+    "naturalnumber",
+    help="Set width of the pop-up file browser window in pixels"
+)
+
+register_custom_property(
+    builder_id,
+    "browser_height",
+    "naturalnumber",
+    help="Set height of the pop-up file browser window in pixels"
+)
+
+register_custom_property(
+    builder_id,
+    "state",
+    "choice",
+    values=("", "normal", "disabled"),
+    state="readonly",
+    help="Set widget interaction state"
+)