scustomtkinter 0.2.1__py3-none-any.whl

scustomtkinter_pygubu/sCTkDialbo.py

@@ -0,0 +1,371 @@
+#!/usr/bin/python3
+"""
+sCTkDialbo
+
+Unified Pygubu Builder Objects for the complete sCTkDial custom widget suite.
+Houses sCTkDialContinuous, sCTkDialRange, and sCTkDialSelector builders
+side-by-side, sharing the metadata configuration pipeline.
+"""
+import pygubu
+from pygubu.api.v1 import (
+    BuilderObject,
+    register_widget,
+    register_custom_property
+)
+from pygubu.plugins.customtkinter.widgets import CTkFrameBO
+
+# Import the native custom classes directly out of your single-file source module
+from scustomtkinter.sctk_dial import sCTkDialContinuous, sCTkDialRange, sCTkDialSelector
+from scustomtkinter.themeable_widget import parse_list_property, parse_font_property
+
+builder_namespace = "scustomtkinter"
+section_name = "sCustomTkinter"
+
+
+# =====================================================================
+# 1. BUILDER OBJECT: INFINITE FLYWHEEL TUNING ENCODER (CONTINUOUS)
+# =====================================================================
+class sCTkDialContinuousBO(BuilderObject):
+    class_ = sCTkDialContinuous
+    classname = "sCTkDialContinuous"
+    _code_classname = "sCTkDialContinuous"
+    container = False
+
+    # width and height come from CTkFrameBO.properties below, so only `state`
+    # is listed here. `properties` decides what the inspector SHOWS; the
+    # copy_custom_property() calls in designer/properties.py supply the editor
+    # definition for each name. Both are required -- copying alone leaves a
+    # property invisible, listing alone leaves it with no editor.
+    OPTIONS_STANDARD = ("state",)
+    OPTIONS_CUSTOM = ("divisions", "knob_diameter", "command", "left_click_callback", "right_click_callback",
+                      "double_click_command", "shift_double_click_command",
+                      "latching",
+                      "text_color", "dial_color", "pointer_glow_color")
+    properties = CTkFrameBO.properties + OPTIONS_STANDARD + OPTIONS_CUSTOM
+    command_properties = ("command", "left_click_callback",
+                          "right_click_callback", "double_click_command",
+                          "shift_double_click_command")
+
+    def _code_define_callback_args(self, cmd_pname, cmd):
+        """
+        Declares what each callback receives, so the generated stub has
+        matching parameters.
+
+        Without this, pygubu generates every stub with no arguments -- and the
+        dial calls `command` with a value:
+
+            TypeError: on_turn() takes 1 positional argument but 2 were given
+
+        The two click callbacks genuinely take nothing, so only `command` gets
+        a parameter. Continuous reports a signed step delta rather than a position, since it has none.
+        """
+        if cmd_pname in ("double_click_command", "shift_double_click_command"):
+            # Called with the dial itself, so a handler can act on it without
+            # a closure over the variable name -- typically to arm a latching
+            # dial:
+            #
+            #     def on_double_click(self, dial):
+            #         dial.toggle_pressed()
+            return ("dial",)
+        if cmd_pname in ("left_click_callback", "right_click_callback"):
+            # Deferred to the base rather than returning () -- pygubu joins the
+            # names onto "self, ", so an empty tuple left the separator with
+            # nothing after it:
+            #
+            #     def left_dialRange_CB(self, ):
+            #
+            # Valid Python, but untidy. The base class already produces a stub
+            # with no extra parameters.
+            return super()._code_define_callback_args(cmd_pname, cmd)
+        return ("step_delta",)
+
+
+    # NOTE: realize() no longer forces width and height from the knob size.
+    #
+    # It used to write both canvas dimensions from `diameter`, overwriting
+    # whatever the user had set in the inspector -- so a dial could not be
+    # given a canvas wider than it was tall, and long labels had nowhere to go.
+    #
+    # knob_diameter now names the KNOB and width/height name the CANVAS, which
+    # is what those words should always have meant. The widget supplies a
+    # canvas default around the knob when none is given, so a bare
+    # knob_diameter still works -- see sCTKDialBase._default_canvas_size().
+
+
+# =====================================================================
+# 2. BUILDER OBJECT: HARD END-STOP POTENTIOMETER (RANGE)
+# =====================================================================
+class sCTkDialRangeBO(BuilderObject):
+    class_ = sCTkDialRange
+    classname = "sCTkDialRange"
+    _code_classname = "sCTkDialRange"
+    container = False
+
+    # width and height come from CTkFrameBO.properties below, so only `state`
+    # is listed here. `properties` decides what the inspector SHOWS; the
+    # copy_custom_property() calls in designer/properties.py supply the editor
+    # definition for each name. Both are required -- copying alone leaves a
+    # property invisible, listing alone leaves it with no editor.
+    OPTIONS_STANDARD = ("state",)
+    OPTIONS_CUSTOM = ("from_", "to", "divisions", "knob_diameter", "arc_angle","command", "left_click_callback", "right_click_callback", "label_font",
+                      "double_click_command", "shift_double_click_command",
+                      "latching",
+                      "text_color", "dial_color", "pointer_color")
+    properties = CTkFrameBO.properties + OPTIONS_STANDARD + OPTIONS_CUSTOM
+    command_properties = ("command", "left_click_callback",
+                          "right_click_callback", "double_click_command",
+                          "shift_double_click_command")
+
+    def _code_define_callback_args(self, cmd_pname, cmd):
+        """
+        Declares what each callback receives, so the generated stub has
+        matching parameters.
+
+        Without this, pygubu generates every stub with no arguments -- and the
+        dial calls `command` with a value:
+
+            TypeError: on_turn() takes 1 positional argument but 2 were given
+
+        The two click callbacks genuinely take nothing, so only `command` gets
+        a parameter. Range reports the new value.
+        """
+        if cmd_pname in ("double_click_command", "shift_double_click_command"):
+            # Called with the dial itself, so a handler can act on it without
+            # a closure over the variable name -- typically to arm a latching
+            # dial:
+            #
+            #     def on_double_click(self, dial):
+            #         dial.toggle_pressed()
+            return ("dial",)
+        if cmd_pname in ("left_click_callback", "right_click_callback"):
+            # Deferred to the base rather than returning () -- pygubu joins the
+            # names onto "self, ", so an empty tuple left the separator with
+            # nothing after it:
+            #
+            #     def left_dialRange_CB(self, ):
+            #
+            # Valid Python, but untidy. The base class already produces a stub
+            # with no extra parameters.
+            return super()._code_define_callback_args(cmd_pname, cmd)
+        return ("value",)
+
+
+    # NOTE: realize() no longer forces width and height from the knob size.
+    # See the equivalent note on sCTkDialContinuousBO above.
+
+
+# =====================================================================
+# 3. BUILDER OBJECT: DISCRETE SWITCH SELECTOR (SELECTOR)
+# =====================================================================
+class sCTkDialSelectorBO(BuilderObject):
+    class_ = sCTkDialSelector
+    classname = "sCTkDialSelector"
+    _code_classname = "sCTkDialSelector"
+    container = False
+
+    # width and height come from CTkFrameBO.properties below, so only `state`
+    # is listed here. `properties` decides what the inspector SHOWS; the
+    # copy_custom_property() calls in designer/properties.py supply the editor
+    # definition for each name. Both are required -- copying alone leaves a
+    # property invisible, listing alone leaves it with no editor.
+    OPTIONS_STANDARD = ("state",)
+    OPTIONS_CUSTOM = ("knob_diameter", "arc_angle","command", "left_click_callback", "right_click_callback", "labels", "label_font",
+                      "double_click_command", "shift_double_click_command",
+                      "latching",
+                      "text_color", "dial_color", "pointer_color")  # Labels handles lists, usually initialized in code
+    properties = CTkFrameBO.properties + OPTIONS_STANDARD + OPTIONS_CUSTOM
+    command_properties = ("command", "left_click_callback",
+                          "right_click_callback", "double_click_command",
+                          "shift_double_click_command")
+
+    def _code_define_callback_args(self, cmd_pname, cmd):
+        """
+        Declares what each callback receives, so the generated stub has
+        matching parameters.
+
+        Without this, pygubu generates every stub with no arguments -- and the
+        dial calls `command` with a value:
+
+            TypeError: on_turn() takes 1 positional argument but 2 were given
+
+        The two click callbacks genuinely take nothing, so only `command` gets
+        a parameter. Selector reports the index of the chosen label, not the label itself.
+        """
+        if cmd_pname in ("double_click_command", "shift_double_click_command"):
+            # Called with the dial itself, so a handler can act on it without
+            # a closure over the variable name -- typically to arm a latching
+            # dial:
+            #
+            #     def on_double_click(self, dial):
+            #         dial.toggle_pressed()
+            return ("dial",)
+        if cmd_pname in ("left_click_callback", "right_click_callback"):
+            # Deferred to the base rather than returning () -- pygubu joins the
+            # names onto "self, ", so an empty tuple left the separator with
+            # nothing after it:
+            #
+            #     def left_dialRange_CB(self, ):
+            #
+            # Valid Python, but untidy. The base class already produces a stub
+            # with no extra parameters.
+            return super()._code_define_callback_args(cmd_pname, cmd)
+        return ("selected_index",)
+
+
+    def _process_property_value(self, name, value):
+        if name == 'label_font':
+            # Shared parser: handles the "{}" Tk emits for "no style",
+            # which reaches a canvas item as unknown font style "".
+            return parse_font_property(value)
+        if name == 'labels':
+            # FIX: was value.split(","), which did not strip whitespace -- so
+            # "AM, FM, LSB" produced ["AM", " FM", " LSB"] and the dial drew
+            # labels with leading spaces. The shared parser also accepts the
+            # Python-literal form, so this property now behaves identically to
+            # sCTkTableview's `columns` and sCTkSelector's `items`.
+            return parse_list_property(value)
+        return value
+
+    def _code_set_property(self, targetid, pname, value, code_bag):
+        """
+        Emits `labels` as a real Python list, not a quoted string.
+
+        The bracketed form -- the one this widget's own help text recommends --
+        contains double quotes, and the default handler wraps the whole value
+        in double quotes again:
+
+            sctkdialselector1.configure(labels="["AM", "FM"]", ...)
+                                               ^^^^^^^^^^^^^
+            SyntaxError: invalid syntax
+
+        Emitting the literal unquoted gives valid Python and a real list, so
+        the widget receives one directly rather than parsing a string back out
+        of it. Same approach sCTkSelectorbo uses for `items` and
+        sCTkFileExplorerbo for `filetypes`.
+
+        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 == "labels" 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)
+
+    # NOTE: realize() no longer forces width and height from the knob size.
+    # See the equivalent note on sCTkDialContinuousBO above.
+    #
+    # This one mattered most: a Selector's labels are user text and can be any
+    # length, so a square canvas locked to the knob size was exactly the wrong
+    # constraint -- there was no way to widen it for a long label.
+
+
+# =====================================================================
+# UNIFIED MODULE-LEVEL PYGUBU REGISTRATION LEDGER
+# Registers all three semantic variations simultaneously inside the palette.
+# =====================================================================
+
+# --- 1. CONTINUOUS VFO ENCODER MATRIX REGISTRY ---
+id_continuous = f"{builder_namespace}.sCTkDialContinuous"
+register_widget(id_continuous, sCTkDialContinuousBO, "sCTkDialContinuous", ("ttk", section_name))
+# `state` appears in OPTIONS_STANDARD for all three dials but was
+# registered for none of them, so Pygubu supplied its own definition --
+# which is why the Selector and Range dials offered a third value that
+# the Continuous dial did not. Registering it explicitly makes all
+# three agree and matches the widget's real two-state model.
+register_custom_property(id_continuous, "text_color", "colorentry", help="Colour of the labels AND the tick marks -- both are drawn with this one key. Blank uses the theme's text_color.")
+register_custom_property(id_continuous, "dial_color", "colorentry", help="Colour of the knob face. Blank uses the theme's dial_color.")
+register_custom_property(id_continuous, "pointer_glow_color", "colorentry", help="Colour of the glow around the pointer. Blank uses the theme's pointer_glow_color.")
+# `pressed` is deliberately NOT a Designer property.
+#
+# It is the dial's initial armed state, and the inspector reflects the LIVE
+# widget -- so double-clicking a dial on the design canvas set it True, and
+# pygubu then wrote pressed=True into the generated code as a non-default.
+# The application started armed, which is the opposite of what latching is
+# for. It remains a constructor argument for code that genuinely wants a dial
+# to start switched on.
+register_custom_property(id_continuous, "latching", "choice", values=("True", "False"),
+                         default_value="False", help="Opt-in. True makes the dial start switched off and ignore clicks, drags and the wheel until armed -- typically by wiring double_click_command to toggle_pressed(). It then draws from the theme's pressed_map. False, the default, is always live.")
+register_custom_property(id_continuous, "state", "choice", values=("normal", "disabled"), help="Enabled or dimmed and inert.")
+register_custom_property(id_continuous, "width", "naturalnumber", help="Width in pixels.")
+register_custom_property(id_continuous, "height", "naturalnumber", help="Height in pixels.")
+register_custom_property(id_continuous, "divisions", "naturalnumber", default_value=24, help="Flywheel detents per 360 turn.")
+register_custom_property(id_continuous, "knob_diameter", "naturalnumber", default_value=120,
+                         help="Diameter of the knob itself, in pixels. Set width and height for the canvas around it.")
+register_custom_property(id_continuous, "command", "commandentry", help="Callback for knob turn by mousewheel.")
+register_custom_property(id_continuous, "left_click_callback", "commandentry", help="Callback for left mouse click.")
+register_custom_property(id_continuous, "double_click_command", "commandentry",
+                         help="Callback for a double-click on the knob. Receives the dial itself. "
+                              "Wire it to toggle_pressed() to arm a latching dial.")
+register_custom_property(id_continuous, "shift_double_click_command", "commandentry",
+                         help="Callback for a shift-double-click on the knob. Receives the dial itself. "
+                              "Its own gesture because a plain double-click competes with click-stepping; "
+                              "wire it to disarm a latching dial.")
+register_custom_property(id_continuous, "right_click_callback", "commandentry", help="Callback for right mouse click.")
+
+# --- 2. RANGED POTENTIOMETER MATRIX REGISTRY ---
+id_range = f"{builder_namespace}.sCTkDialRange"
+register_widget(id_range, sCTkDialRangeBO, "sCTkDialRange", ("ttk", section_name))
+# `state` appears in OPTIONS_STANDARD for all three dials but was
+# registered for none of them, so Pygubu supplied its own definition --
+# which is why the Selector and Range dials offered a third value that
+# the Continuous dial did not. Registering it explicitly makes all
+# three agree and matches the widget's real two-state model.
+register_custom_property(id_range, "label_font", "fontentry", help="Font for the labels drawn around the dial. Blank uses the theme's label_font.")
+register_custom_property(id_range, "text_color", "colorentry", help="Colour of the labels AND the tick marks -- both are drawn with this one key. Blank uses the theme's text_color.")
+register_custom_property(id_range, "dial_color", "colorentry", help="Colour of the knob face. Blank uses the theme's dial_color.")
+register_custom_property(id_range, "pointer_color", "colorentry", help="Colour of the pointer on the knob. Blank uses the theme's pointer_color.")
+register_custom_property(id_range, "latching", "choice", values=("True", "False"),
+                         default_value="False", help="Opt-in. True makes the dial start switched off and ignore clicks, drags and the wheel until armed -- typically by wiring double_click_command to toggle_pressed(). It then draws from the theme's pressed_map. False, the default, is always live.")
+register_custom_property(id_range, "state", "choice", values=("normal", "disabled"), help="Enabled or dimmed and inert.")
+register_custom_property(id_range, "width", "naturalnumber", help="Width in pixels.")
+register_custom_property(id_range, "height", "naturalnumber", help="Height in pixels.")
+register_custom_property(id_range, "from_", "integernumber", default_value=0, help="Absolute minimum boundary limit.")
+register_custom_property(id_range, "to", "integernumber", default_value=100, help="Absolute maximum boundary limit.")
+register_custom_property(id_range, "divisions", "naturalnumber", default_value=5, help="Number of calibration tick lines drawn.")
+register_custom_property(id_range, "knob_diameter", "naturalnumber", default_value=120,
+                         help="Diameter of the knob itself, in pixels. Widen the canvas with width and height if labels are clipped.")
+register_custom_property(id_range, "arc_angle", "naturalnumber", default_value=270, help="Symmetrical active arc sweep.")
+register_custom_property(id_range, "command", "commandentry", help="Callback for knob turn by mousewheel.")
+register_custom_property(id_range, "left_click_callback", "commandentry", help="Callback for left mouse click.")
+register_custom_property(id_range, "double_click_command", "commandentry",
+                         help="Callback for a double-click on the knob. Receives the dial itself. "
+                              "Wire it to toggle_pressed() to arm a latching dial.")
+register_custom_property(id_range, "shift_double_click_command", "commandentry",
+                         help="Callback for a shift-double-click on the knob. Receives the dial itself. "
+                              "Its own gesture because a plain double-click competes with click-stepping; "
+                              "wire it to disarm a latching dial.")
+register_custom_property(id_range, "right_click_callback", "commandentry", help="Callback for right mouse click.")
+
+# --- 3. MODE SELECTOR MATRIX REGISTRY ---
+id_selector = f"{builder_namespace}.sCTkDialSelector"
+register_widget(id_selector, sCTkDialSelectorBO, "sCTkDialSelector", ("ttk", section_name))
+# `state` appears in OPTIONS_STANDARD for all three dials but was
+# registered for none of them, so Pygubu supplied its own definition --
+# which is why the Selector and Range dials offered a third value that
+# the Continuous dial did not. Registering it explicitly makes all
+# three agree and matches the widget's real two-state model.
+register_custom_property(id_selector, "label_font", "fontentry", help="Font for the labels drawn around the dial. Blank uses the theme's label_font.")
+register_custom_property(id_selector, "text_color", "colorentry", help="Colour of the labels AND the tick marks -- both are drawn with this one key. Blank uses the theme's text_color.")
+register_custom_property(id_selector, "dial_color", "colorentry", help="Colour of the knob face. Blank uses the theme's dial_color.")
+register_custom_property(id_selector, "pointer_color", "colorentry", help="Colour of the pointer on the knob. Blank uses the theme's pointer_color.")
+register_custom_property(id_selector, "latching", "choice", values=("True", "False"),
+                         default_value="False", help="Opt-in. True makes the dial start switched off and ignore clicks, drags and the wheel until armed -- typically by wiring double_click_command to toggle_pressed(). It then draws from the theme's pressed_map. False, the default, is always live.")
+register_custom_property(id_selector, "state", "choice", values=("normal", "disabled"), help="Enabled or dimmed and inert.")
+register_custom_property(id_selector, "width", "naturalnumber", help="Width in pixels.")
+register_custom_property(id_selector, "height", "naturalnumber", help="Height in pixels.")
+register_custom_property(id_selector, "knob_diameter", "naturalnumber", default_value=120,
+                         help="Diameter of the knob itself, in pixels. Widen the canvas with width and height if labels are clipped.")
+register_custom_property(id_selector, "arc_angle", "naturalnumber", default_value=270, help="Symmetrical active arc sweep.")
+register_custom_property(id_selector, "command", "commandentry", help="Callback for knob turn by mousewheel.")
+register_custom_property(id_selector, "left_click_callback", "commandentry", help="Callback for left mouse click.")
+register_custom_property(id_selector, "double_click_command", "commandentry",
+                         help="Callback for a double-click on the knob. Receives the dial itself. "
+                              "Wire it to toggle_pressed() to arm a latching dial.")
+register_custom_property(id_selector, "shift_double_click_command", "commandentry",
+                         help="Callback for a shift-double-click on the knob. Receives the dial itself. "
+                              "Its own gesture because a plain double-click competes with click-stepping; "
+                              "wire it to disarm a latching dial.")
+register_custom_property(id_selector, "right_click_callback", "commandentry", help="Callback for right mouse click.")
+register_custom_property(id_selector, "labels", "entry", help='Preferred: ["A", "B", "C"]. Bare comma-separated (A, B, C) also works, but cannot contain a comma inside a value.')