codeallyadvanced 3.0.0__tar.gz → 3.1.0__tar.gz

{codeallyadvanced-3.0.0/src/codeallyadvanced.egg-info → codeallyadvanced-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeallyadvanced
-Version: 3.0.0
+Version: 3.1.0
 Summary: Humberto`s Common wxPython UI Stuff
 Author-email: "Humberto A. Sanchez II" <Humberto.A.Sanchez.II@gmail.com>
 Maintainer-email: "Humberto A. Sanchez II" <Humberto.A.Sanchez.II@gmail.com>
@@ -38,33 +38,49 @@ Dynamic: license-file
 [![PyPI version](https://badge.fury.io/py/codeallyadvanced.svg)](https://badge.fury.io/py/codeallyadvanced)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
 [![Made with Python](https://img.shields.io/badge/Made%20with-Python-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Documentation Status](https://readthedocs.org/projects/code-ally-advanced/badge/?version=latest)](https://code-ally-advanced.readthedocs.io/en/latest/?badge=latest)
 [![GitHub Copilot: No](https://img.shields.io/badge/GitHub_Copilot-No-red?logo=github&style=flat-square)](https://github.com/hasii2011/code-ally-basic/wiki/GitHub-Copilot)
 
-Host common UI artifacts for various projects I am developing
+This repository hosts common UI artifacts for various projects I develop.
+
+The documentation is on [Read the Docs](https://code-ally-advanced.readthedocs.io/en/latest/).
 
 ___
-Common wxPython UI artifacts for various projects I am developing
+Available wxPython UI components:
 
 * Dimensions Control
 * Position Control
 * MinMax Control
+* Named Spin Control
 * Directory Selector
+* Dial Selector
+* Titled Panels
+
+### Component Previews
+
+* Spinner Widgets
 
-![SpinnerWidgets](./developer/SpinnerWidgets.png)
+    ![SpinnerWidgets](./developer/SpinnerWidgets.png)
+
+* Directory Selector
 
-* DialSelector
+    ![DirectorySelector](./developer/DirectorySelector.png)
+
+* Dial Selector
 
     ![DialSelector](./developer/DialSelector.png)
 
-Written by <a href="mailto:email@humberto.a.sanchez.ii@gmail.com?subject=Hello Humberto">Humberto A. Sanchez II</a>  (C) 2025
+* Titled Panels
+
+    ![TitledPanels](./developer/TitledPanels.png)
+
+Written by <a href="mailto:humberto.a.sanchez.ii@gmail.com?subject=Hello Humberto">Humberto A. Sanchez II</a>  (C) 2026
 
 ## Note
 For all kinds of problems, requests, enhancements, bug reports, etc., drop me an e-mail.
 
 ## Developer Notes
-This project uses [buildlackey](https://github.com/hasii2011/buildlackey) for day-to-day development builds
-
-Also notice that this project does not include a `requirements.txt` file.  All dependencies are listed in the `pyproject.toml` file.
+This project uses [buildlackey](https://github.com/hasii2011/buildlackey) for day-to-day development builds.
 
 #### Install the main project dependencies
 

{codeallyadvanced-3.0.0 → codeallyadvanced-3.1.0}/README.md

@@ -3,33 +3,49 @@
 [![PyPI version](https://badge.fury.io/py/codeallyadvanced.svg)](https://badge.fury.io/py/codeallyadvanced)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
 [![Made with Python](https://img.shields.io/badge/Made%20with-Python-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Documentation Status](https://readthedocs.org/projects/code-ally-advanced/badge/?version=latest)](https://code-ally-advanced.readthedocs.io/en/latest/?badge=latest)
 [![GitHub Copilot: No](https://img.shields.io/badge/GitHub_Copilot-No-red?logo=github&style=flat-square)](https://github.com/hasii2011/code-ally-basic/wiki/GitHub-Copilot)
 
-Host common UI artifacts for various projects I am developing
+This repository hosts common UI artifacts for various projects I develop.
+
+The documentation is on [Read the Docs](https://code-ally-advanced.readthedocs.io/en/latest/).
 
 ___
-Common wxPython UI artifacts for various projects I am developing
+Available wxPython UI components:
 
 * Dimensions Control
 * Position Control
 * MinMax Control
+* Named Spin Control
 * Directory Selector
+* Dial Selector
+* Titled Panels
+
+### Component Previews
+
+* Spinner Widgets
 
-![SpinnerWidgets](./developer/SpinnerWidgets.png)
+    ![SpinnerWidgets](./developer/SpinnerWidgets.png)
+
+* Directory Selector
 
-* DialSelector
+    ![DirectorySelector](./developer/DirectorySelector.png)
+
+* Dial Selector
 
     ![DialSelector](./developer/DialSelector.png)
 
-Written by <a href="mailto:email@humberto.a.sanchez.ii@gmail.com?subject=Hello Humberto">Humberto A. Sanchez II</a>  (C) 2025
+* Titled Panels
+
+    ![TitledPanels](./developer/TitledPanels.png)
+
+Written by <a href="mailto:humberto.a.sanchez.ii@gmail.com?subject=Hello Humberto">Humberto A. Sanchez II</a>  (C) 2026
 
 ## Note
 For all kinds of problems, requests, enhancements, bug reports, etc., drop me an e-mail.
 
 ## Developer Notes
-This project uses [buildlackey](https://github.com/hasii2011/buildlackey) for day-to-day development builds
-
-Also notice that this project does not include a `requirements.txt` file.  All dependencies are listed in the `pyproject.toml` file.
+This project uses [buildlackey](https://github.com/hasii2011/buildlackey) for day-to-day development builds.
 
 #### Install the main project dependencies
 

codeallyadvanced-3.1.0/src/codeallyadvanced/_version.py

@@ -0,0 +1 @@
+__version__: str = '3.1.0'

codeallyadvanced-3.1.0/src/codeallyadvanced/ui/widgets/NamedSpinCtrl.py

@@ -0,0 +1,156 @@
+
+"""
+A composite wxPython numeric spin control paired with a descriptive text label.
+
+This module provides :class:`NamedSpinCtrl`, a self-contained component that wraps
+a :class:`wx.SpinCtrl` and an associated :class:`wx.StaticText` title,
+configured via :class:`NamedSpinControlDescription`.
+"""
+
+from typing import Callable
+
+from logging import Logger
+from logging import getLogger
+
+from enum import StrEnum
+
+from dataclasses import dataclass
+
+from wx import ID_ANY
+from wx import EVT_SPINCTRL
+from wx import SP_ARROW_KEYS
+
+from wx import Size
+from wx import SpinCtrl
+from wx import SpinEvent
+from wx import StaticText
+
+from wx.lib.sized_controls import SizedPanel
+
+NSC_CALLBACK_PARAMETER_TYPE = str | int
+"""
+Allowable return types delivered to callbacks upon value changes.
+"""
+
+NSCValueChangedCallback = Callable[[NSC_CALLBACK_PARAMETER_TYPE], None]
+"""
+Type alias for value-change notification listener functions.
+"""
+
+
+class NSCValueType(StrEnum):
+    """
+    Specifies the data type delivered to listeners on value change events.
+
+    Attributes:
+        STRING: Value is emitted as a formatted string.
+        INT: Value is emitted as a raw integer.
+    """
+    STRING = 'String'
+    INT    = 'Int'
+
+
+@dataclass
+class NamedSpinControlDescription:
+    """
+    Configuration specification for constructing a :class:`NamedSpinCtrl`.
+
+    Attributes:
+        label:       Descriptive caption displayed above the spin control.
+        controlSize: Preferred pixel dimensions for the inner :class:`wx.SpinCtrl`.
+        minValue:    Minimum permissible numeric value in the range.
+        maxValue:    Maximum permissible numeric value in the range.
+        valueType:   Enumeration designating whether events emit integers or strings.
+        valueChangedCallback: Listener invoked whenever the spin control value changes.
+    """
+    label:                str
+    controlSize:          Size
+    minValue:             int
+    maxValue:             int
+    valueType:            NSCValueType
+    valueChangedCallback: NSCValueChangedCallback
+
+class NamedSpinCtrl(SizedPanel):
+    """
+    An opinionated vertical compound widget combining a label with a spin control.
+
+    Lays out a :class:`wx.StaticText` header directly above a :class:`wx.SpinCtrl`
+    within a vertical :class:`wx.lib.sized_controls.SizedPanel`. Notifies registered
+    callbacks with type-converted values when modified via arrow buttons or keyboard.
+    """
+
+    def __init__(self, parent: SizedPanel, description: NamedSpinControlDescription):
+        """
+        Initialize the NamedSpinCtrl composite widget.
+
+        Args:
+            parent:      Parent sized container hosting this control.
+            description: Configuration parameters specifying bounds, sizing, label, and callback.
+        """
+        self.logger: Logger = getLogger(__name__)
+
+        super().__init__(parent=parent)
+
+        self.SetSizerType('vertical')
+
+        self._staticText: StaticText = StaticText(self, ID_ANY, description.label)
+
+        spinCtrl: SpinCtrl = SpinCtrl(self, id=ID_ANY, size=description.controlSize, style=SP_ARROW_KEYS)
+        spinCtrl.SetRange(description.minValue, description.maxValue)
+
+        self._spinCtrl:  SpinCtrl     = spinCtrl
+        self._valueType: NSCValueType = description.valueType
+
+        self._valueChangedCallback: NSCValueChangedCallback = description.valueChangedCallback
+
+        parent.Bind(EVT_SPINCTRL, self._onValueChanged, self._spinCtrl)
+
+    def _setToolTip(self, tip: str):
+        """
+        Assign a tooltip string to the underlying spin control widget.
+
+        Args:
+            tip: The explanatory text displayed when the mouse pointer hovers over the spin control.
+        """
+        self._spinCtrl.SetToolTip(tip)
+
+    # noinspection PyPropertyDefinition
+    # noinspection PyTypeChecker
+    toolTip = property(fget=None, fset=_setToolTip, fdel=None, doc="""Write only property to set tooltip on spin control""")
+
+    @property
+    def value(self) -> int:
+        """
+        Retrieve the spin control's current integer value.
+
+        Returns:
+            The currently displayed numeric value.
+        """
+        return self._spinCtrl.GetValue()
+
+    @value.setter
+    def value(self, newValue: int):
+        """
+        Set the spin control's numeric value.
+
+        Args:
+            newValue: The new integer value.
+        """
+        self._spinCtrl.SetValue(newValue)
+
+    def _onValueChanged(self, event: SpinEvent):
+        """
+        Handle EVT_SPINCTRL change events from the underlying SpinCtrl.
+
+        Extracts the value in the configured format (:attr:`NSCValueType.INT` or
+        :attr:`NSCValueType.STRING`) and invokes the registered change callback.
+
+        Args:
+            event: The wxPython spin control event instance.
+        """
+        if self._valueType == NSCValueType.INT:
+            newInterval: NSC_CALLBACK_PARAMETER_TYPE = event.GetInt()
+        else:
+            newInterval = event.GetString()
+
+        self._valueChangedCallback(newInterval)

codeallyadvanced-3.1.0/src/codeallyadvanced/ui/widgets/TitledPanel.py

@@ -0,0 +1,82 @@
+"""
+A lightweight titled container panel for grouping related wxPython controls.
+
+This module provides :class:`TitledPanel`, a drop-in visual alternative to
+:class:`wx.lib.sized_controls.SizedStaticBox` that groups child widgets under a
+prominent :class:`wx.StaticText` title label without rendering a heavy macOS Aqua
+gray background plates or nested borders.
+"""
+
+from enum import StrEnum
+
+from wx import ID_ANY
+
+from wx import Window
+from wx import StaticText
+
+from wx.lib.sized_controls import SizedPanel
+
+
+class PanelLayoutType(StrEnum):
+    """
+    This defines Sizer layout orientation styles supported by :class:`TitledPanel`.
+
+    Attributes:
+        HORIZONTAL: Arranges child controls in a single horizontal row.
+        VERTICAL:   Arranges child controls in a single vertical column below the header.
+        FORM:       Arranges controls into a two-column label-and-field form grid.
+        GRID:       Arranges controls into a multi-column, multi-row table grid.
+    """
+    HORIZONTAL = 'horizontal'
+    VERTICAL   = 'vertical'
+    FORM       = 'form'
+    GRID       = 'grid'
+
+
+class TitledPanel(SizedPanel):
+    """
+    A titled grouping panel built on :class:`wx.lib.sized_controls.SizedPanel`.
+
+    Serves as an uncluttered alternative to :class:`wx.StaticBox` and
+    :class:`wx.lib.sized_controls.SizedStaticBox`. It automatically injects
+    a :class:`wx.StaticText` header label at the top of the container while
+    applying the requested :class:`PanelLayoutType` sizer. Any child controls
+    instantiated with ``parent=titledPanel`` are positioned cleanly beneath the title.
+    """
+
+    def __init__(self, parent: Window, titleLabel: str, layoutType: PanelLayoutType = PanelLayoutType.VERTICAL):
+        """
+        Initialize the TitledPanel with a title header and sizer layout.
+
+        Args:
+            parent:     The parent window or container hosting this panel.
+            titleLabel: The title string displayed at the top of the panel.
+            layoutType: Sizer layout orientation (:attr:`PanelLayoutType.VERTICAL`,
+                :attr:`PanelLayoutType.HORIZONTAL`, :attr:`PanelLayoutType.FORM`,
+                or :attr:`PanelLayoutType.GRID`). Defaults to :attr:`PanelLayoutType.VERTICAL`.
+        """
+        super().__init__(parent)
+        self.SetSizerType(layoutType.value)
+        if self.GetParent() and self.GetParent().GetSizer():
+            self.SetSizerProps(expand=False)
+        self._titleLabel: StaticText = StaticText(self, ID_ANY, titleLabel)
+
+    @property
+    def label(self) -> str:
+        """
+        Retrieve the current title text displayed on the header label.
+
+        Returns:
+            The current title string.
+        """
+        return self._titleLabel.GetLabel()
+
+    @label.setter
+    def label(self, newLabel: str):
+        """
+        Update the title text displayed on the header label.
+
+        Args:
+            newLabel: The new header text to display.
+        """
+        self._titleLabel.SetLabel(newLabel)

{codeallyadvanced-3.0.0 → codeallyadvanced-3.1.0/src/codeallyadvanced.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeallyadvanced
-Version: 3.0.0
+Version: 3.1.0
 Summary: Humberto`s Common wxPython UI Stuff
 Author-email: "Humberto A. Sanchez II" <Humberto.A.Sanchez.II@gmail.com>
 Maintainer-email: "Humberto A. Sanchez II" <Humberto.A.Sanchez.II@gmail.com>
@@ -38,33 +38,49 @@ Dynamic: license-file
 [![PyPI version](https://badge.fury.io/py/codeallyadvanced.svg)](https://badge.fury.io/py/codeallyadvanced)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
 [![Made with Python](https://img.shields.io/badge/Made%20with-Python-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Documentation Status](https://readthedocs.org/projects/code-ally-advanced/badge/?version=latest)](https://code-ally-advanced.readthedocs.io/en/latest/?badge=latest)
 [![GitHub Copilot: No](https://img.shields.io/badge/GitHub_Copilot-No-red?logo=github&style=flat-square)](https://github.com/hasii2011/code-ally-basic/wiki/GitHub-Copilot)
 
-Host common UI artifacts for various projects I am developing
+This repository hosts common UI artifacts for various projects I develop.
+
+The documentation is on [Read the Docs](https://code-ally-advanced.readthedocs.io/en/latest/).
 
 ___
-Common wxPython UI artifacts for various projects I am developing
+Available wxPython UI components:
 
 * Dimensions Control
 * Position Control
 * MinMax Control
+* Named Spin Control
 * Directory Selector
+* Dial Selector
+* Titled Panels
+
+### Component Previews
+
+* Spinner Widgets
 
-![SpinnerWidgets](./developer/SpinnerWidgets.png)
+    ![SpinnerWidgets](./developer/SpinnerWidgets.png)
+
+* Directory Selector
 
-* DialSelector
+    ![DirectorySelector](./developer/DirectorySelector.png)
+
+* Dial Selector
 
     ![DialSelector](./developer/DialSelector.png)
 
-Written by <a href="mailto:email@humberto.a.sanchez.ii@gmail.com?subject=Hello Humberto">Humberto A. Sanchez II</a>  (C) 2025
+* Titled Panels
+
+    ![TitledPanels](./developer/TitledPanels.png)
+
+Written by <a href="mailto:humberto.a.sanchez.ii@gmail.com?subject=Hello Humberto">Humberto A. Sanchez II</a>  (C) 2026
 
 ## Note
 For all kinds of problems, requests, enhancements, bug reports, etc., drop me an e-mail.
 
 ## Developer Notes
-This project uses [buildlackey](https://github.com/hasii2011/buildlackey) for day-to-day development builds
-
-Also notice that this project does not include a `requirements.txt` file.  All dependencies are listed in the `pyproject.toml` file.
+This project uses [buildlackey](https://github.com/hasii2011/buildlackey) for day-to-day development builds.
 
 #### Install the main project dependencies
 

{codeallyadvanced-3.0.0 → codeallyadvanced-3.1.0}/src/codeallyadvanced.egg-info/SOURCES.txt

@@ -122,6 +122,8 @@ src/codeallyadvanced/ui/widgets/DirectorySelector.py
 src/codeallyadvanced/ui/widgets/DualSpinnerControl.py
 src/codeallyadvanced/ui/widgets/MacDialSelector.py
 src/codeallyadvanced/ui/widgets/MinMaxControl.py
+src/codeallyadvanced/ui/widgets/NamedSpinCtrl.py
 src/codeallyadvanced/ui/widgets/PositionControl.py
+src/codeallyadvanced/ui/widgets/TitledPanel.py
 src/codeallyadvanced/ui/widgets/__init__.py
 src/codeallyadvanced/ui/widgets/py.typed

codeallyadvanced-3.0.0/src/codeallyadvanced/_version.py

@@ -1 +0,0 @@
-__version__: str = '3.0.0'