ctkforge 0.1.0__tar.gz

ctkforge-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: ctkforge
+Version: 0.1.0
+Summary: CustomTkinter extension components and widgets
+Author: Rafalus
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: customtkinter>=6.0.0
+Requires-Dist: pillow>=12.0.0
+
+# CTkForge
+
+Custom extension components and widgets for [CustomTkinter](https://github.com/TomSchimansky/CustomTkinter).
+
+## Installation
+
+```bash
+pip install ctkforge
+```
+
+## Features
+
+- **[CTkPopup](docs/CTkPopup.md)**: A modern popup dialog widget for alerts, confirmations, and error messages. Includes ready-to-use types (info, warning, error, question, success), keyboard shortcuts (Enter to confirm, Escape to cancel), clean Windows 11 button styling, and automatically turns into a scrollable box for long error text. See [detailed documentation](docs/CTkPopup.md) or run [example_ctkpopup.py](examples/example_ctkpopup.py).
+
+- **[CTkSpinbox](docs/CTkSpinbox.md)**: A number input widget with classic up and down arrow buttons (`▲`/`▼`). Supports mouse wheel scrolling, arrow key adjustments, minimum/maximum limits, custom steps, and matches CustomTkinter's colors and rounded corners. See [detailed documentation](docs/CTkSpinbox.md) or run [example_ctkspinbox.py](examples/example_ctkspinbox.py).
+
+- **[CTkTable](docs/table.md)**: A fast, smooth data table widget built to handle massive datasets without slowing down. Features smart column sorting, row and cell selection, double-click cell editing, Excel-compatible copy-pasting (`Ctrl+C`), auto-fitting column widths, and optional alternating row colors. See [API reference](docs/table.md), [user guide](docs/table_user_guide.md), or run [demo_ctktable.py](examples/demo_ctktable.py).
+- **Universal DPI `unscale` Helper**: Utility function to convert raw physical pixel dimensions from Tkinter (`winfo_*`) back to unscaled 100% baseline (96 DPI) values for CustomTkinter windows.
+- **Resource Locator (`resource_path`)**: Robust asset path resolver that finds images, icons, audio, and data files across direct filesystem paths, the script entry directory (`sys.argv[0]`), and PyInstaller single-file bundle extractions (`sys._MEIPASS`).
+
+## Usage
+
+### 1. CTkPopup Dialogs
+
+```python
+import customtkinter as ctk
+from ctkforge import CTkPopup
+
+app = ctk.CTk()
+
+# Quick confirmation dialog (Enter for Yes, Escape for No)
+popup = CTkPopup(
+    master=app,
+    title="Confirm Action",
+    message="Do you want to proceed with the update?",
+    type="question",
+)
+
+choice = popup.get()
+if choice is True:
+    print("User clicked Yes")
+else:
+    print("User clicked No or closed the dialog")
+
+app.mainloop()
+```
+
+*(See [example_ctkpopup.py](examples/example_ctkpopup.py) and [demo_ctkpopup.py](examples/demo_ctkpopup.py) for interactive demos).*
+
+### 2. CTkSpinbox
+
+```python
+import customtkinter as ctk
+from ctkforge import CTkSpinbox
+
+app = ctk.CTk()
+
+spinbox = CTkSpinbox(
+    app,
+    start_value=25,
+    min_value=1,
+    max_value=100,
+    step=1,
+    width=120,
+    height=38,
+)
+spinbox.pack(padx=20, pady=20)
+
+app.mainloop()
+```
+
+*(See [example_ctkspinbox.py](examples/example_ctkspinbox.py) for the standalone snippet, and [demo_ctkspinbox.py](examples/demo_ctkspinbox.py) for a complete app).*
+
+### 3. CTkTable Data Grid
+
+```python
+import customtkinter as ctk
+from ctkforge import CTkTable
+
+app = ctk.CTk()
+app.geometry("800x400")
+
+headers = ["ID", "Employee Name", "Department", "Salary"]
+data = [
+    ["101", "Ada Lovelace", "Research", "$125,000"],
+    ["102", "Alan Turing", "Data Systems", "$135,000"],
+    ["103", "Grace Hopper", "Engineering", "$130,000"],
+]
+
+table = CTkTable(
+    app,
+    headers=headers,
+    values=data,
+    column_widths=[90, 220, 180, 140],
+    column_types={0: "int"},
+    selection_target="row",
+    selection_mode="extended",
+    editable=True,
+    alternate_row_color=("gray92", "gray14"),
+)
+table.pack(fill="both", expand=True, padx=20, pady=20)
+
+app.mainloop()
+```
+
+*(See [example_ctktable.py](examples/example_ctktable.py) and [demo_ctktable.py](examples/demo_ctktable.py) for interactive demos).*
+
+### 4. Universal DPI Unscaling (`unscale`)
+
+Convert raw physical pixel values from Tkinter (`winfo_*`) back to unscaled 100% baseline (96 DPI) values to prevent double-scaling bugs when setting CustomTkinter geometry on High-DPI displays:
+
+```python
+import customtkinter as ctk
+from ctkforge import unscale
+
+app = ctk.CTk()
+app.update_idletasks()
+
+# Unscale multiple physical dimensions simultaneously:
+width, height = unscale(app, app.winfo_width(), app.winfo_height())
+
+# Or unscale a single coordinate:
+root_x = unscale(app, app.winfo_rootx())
+
+# Set window geometry safely without High-DPI drift:
+app.geometry(f"{width}x{height}")
+```
+
+### 5. Resource Path Resolution (`resource_path`)
+
+Find files reliably in both development and PyInstaller single-file executables (`.exe`):
+
+```python
+from ctkforge import resource_path
+
+# Finds asset whether running from terminal, script folder, or PyInstaller bundle
+icon_path = resource_path("assets/custom_icon.png")
+```
+

ctkforge-0.1.0/README.md

@@ -0,0 +1,139 @@
+# CTkForge
+
+Custom extension components and widgets for [CustomTkinter](https://github.com/TomSchimansky/CustomTkinter).
+
+## Installation
+
+```bash
+pip install ctkforge
+```
+
+## Features
+
+- **[CTkPopup](docs/CTkPopup.md)**: A modern popup dialog widget for alerts, confirmations, and error messages. Includes ready-to-use types (info, warning, error, question, success), keyboard shortcuts (Enter to confirm, Escape to cancel), clean Windows 11 button styling, and automatically turns into a scrollable box for long error text. See [detailed documentation](docs/CTkPopup.md) or run [example_ctkpopup.py](examples/example_ctkpopup.py).
+
+- **[CTkSpinbox](docs/CTkSpinbox.md)**: A number input widget with classic up and down arrow buttons (`▲`/`▼`). Supports mouse wheel scrolling, arrow key adjustments, minimum/maximum limits, custom steps, and matches CustomTkinter's colors and rounded corners. See [detailed documentation](docs/CTkSpinbox.md) or run [example_ctkspinbox.py](examples/example_ctkspinbox.py).
+
+- **[CTkTable](docs/table.md)**: A fast, smooth data table widget built to handle massive datasets without slowing down. Features smart column sorting, row and cell selection, double-click cell editing, Excel-compatible copy-pasting (`Ctrl+C`), auto-fitting column widths, and optional alternating row colors. See [API reference](docs/table.md), [user guide](docs/table_user_guide.md), or run [demo_ctktable.py](examples/demo_ctktable.py).
+- **Universal DPI `unscale` Helper**: Utility function to convert raw physical pixel dimensions from Tkinter (`winfo_*`) back to unscaled 100% baseline (96 DPI) values for CustomTkinter windows.
+- **Resource Locator (`resource_path`)**: Robust asset path resolver that finds images, icons, audio, and data files across direct filesystem paths, the script entry directory (`sys.argv[0]`), and PyInstaller single-file bundle extractions (`sys._MEIPASS`).
+
+## Usage
+
+### 1. CTkPopup Dialogs
+
+```python
+import customtkinter as ctk
+from ctkforge import CTkPopup
+
+app = ctk.CTk()
+
+# Quick confirmation dialog (Enter for Yes, Escape for No)
+popup = CTkPopup(
+    master=app,
+    title="Confirm Action",
+    message="Do you want to proceed with the update?",
+    type="question",
+)
+
+choice = popup.get()
+if choice is True:
+    print("User clicked Yes")
+else:
+    print("User clicked No or closed the dialog")
+
+app.mainloop()
+```
+
+*(See [example_ctkpopup.py](examples/example_ctkpopup.py) and [demo_ctkpopup.py](examples/demo_ctkpopup.py) for interactive demos).*
+
+### 2. CTkSpinbox
+
+```python
+import customtkinter as ctk
+from ctkforge import CTkSpinbox
+
+app = ctk.CTk()
+
+spinbox = CTkSpinbox(
+    app,
+    start_value=25,
+    min_value=1,
+    max_value=100,
+    step=1,
+    width=120,
+    height=38,
+)
+spinbox.pack(padx=20, pady=20)
+
+app.mainloop()
+```
+
+*(See [example_ctkspinbox.py](examples/example_ctkspinbox.py) for the standalone snippet, and [demo_ctkspinbox.py](examples/demo_ctkspinbox.py) for a complete app).*
+
+### 3. CTkTable Data Grid
+
+```python
+import customtkinter as ctk
+from ctkforge import CTkTable
+
+app = ctk.CTk()
+app.geometry("800x400")
+
+headers = ["ID", "Employee Name", "Department", "Salary"]
+data = [
+    ["101", "Ada Lovelace", "Research", "$125,000"],
+    ["102", "Alan Turing", "Data Systems", "$135,000"],
+    ["103", "Grace Hopper", "Engineering", "$130,000"],
+]
+
+table = CTkTable(
+    app,
+    headers=headers,
+    values=data,
+    column_widths=[90, 220, 180, 140],
+    column_types={0: "int"},
+    selection_target="row",
+    selection_mode="extended",
+    editable=True,
+    alternate_row_color=("gray92", "gray14"),
+)
+table.pack(fill="both", expand=True, padx=20, pady=20)
+
+app.mainloop()
+```
+
+*(See [example_ctktable.py](examples/example_ctktable.py) and [demo_ctktable.py](examples/demo_ctktable.py) for interactive demos).*
+
+### 4. Universal DPI Unscaling (`unscale`)
+
+Convert raw physical pixel values from Tkinter (`winfo_*`) back to unscaled 100% baseline (96 DPI) values to prevent double-scaling bugs when setting CustomTkinter geometry on High-DPI displays:
+
+```python
+import customtkinter as ctk
+from ctkforge import unscale
+
+app = ctk.CTk()
+app.update_idletasks()
+
+# Unscale multiple physical dimensions simultaneously:
+width, height = unscale(app, app.winfo_width(), app.winfo_height())
+
+# Or unscale a single coordinate:
+root_x = unscale(app, app.winfo_rootx())
+
+# Set window geometry safely without High-DPI drift:
+app.geometry(f"{width}x{height}")
+```
+
+### 5. Resource Path Resolution (`resource_path`)
+
+Find files reliably in both development and PyInstaller single-file executables (`.exe`):
+
+```python
+from ctkforge import resource_path
+
+# Finds asset whether running from terminal, script folder, or PyInstaller bundle
+icon_path = resource_path("assets/custom_icon.png")
+```
+

ctkforge-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ctkforge"
+version = "0.1.0"
+description = "CustomTkinter extension components and widgets"
+readme = "README.md"
+authors = [
+    { name = "Rafalus" },
+]
+requires-python = ">=3.10"
+dependencies = [
+    "customtkinter>=6.0.0",
+    "pillow>=12.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["*.png"]

ctkforge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ctkforge-0.1.0/src/ctkforge/__init__.py

@@ -0,0 +1,26 @@
+"""CustomTkinter extension components and widgets."""
+
+from ctkforge.debug import (
+    DEBUG_BANNER,
+    enable_debug_mode,
+    is_debug_mode,
+    print_window_telemetry,
+)
+from ctkforge.geometry import scale, unscale
+from ctkforge.popup import CTkPopup
+from ctkforge.resources import resource_path
+from ctkforge.spinbox import CTkSpinbox
+from ctkforge.table import CTkTable
+
+__all__ = [
+    "DEBUG_BANNER",
+    "CTkPopup",
+    "CTkSpinbox",
+    "CTkTable",
+    "enable_debug_mode",
+    "is_debug_mode",
+    "print_window_telemetry",
+    "resource_path",
+    "scale",
+    "unscale",
+]

ctkforge-0.1.0/src/ctkforge/debug.py

@@ -0,0 +1,95 @@
+"""Runtime telemetry and debug tools for CustomTkinter windows."""
+
+from typing import Any
+
+from ctkforge.geometry import unscale
+
+DEBUG_BANNER: str = " === DEBUG MODE IS ACTIVE ==="
+_DEBUG_ACTIVE: bool = False
+
+__all__ = [
+    "DEBUG_BANNER",
+    "enable_debug_mode",
+    "is_debug_mode",
+    "print_window_telemetry",
+]
+
+
+def is_debug_mode() -> bool:
+    """Return whether debug mode is currently active across the application."""
+    return _DEBUG_ACTIVE
+
+
+def print_window_telemetry(window: Any) -> None:
+    """Print size, DPI scaling, and baseline dimensions for the active window.
+
+    Args:
+        window: The active Tk or CustomTkinter window to inspect.
+    """
+    if not hasattr(window, "winfo_exists") or not window.winfo_exists():
+        return
+
+    window.update_idletasks()
+    width = window.winfo_width()
+    height = window.winfo_height()
+    base_w, base_h = unscale(window, width, height)
+    base_req_w, base_req_h = unscale(
+        window, window.winfo_reqwidth(), window.winfo_reqheight()
+    )
+    scaling = (
+        window._get_window_scaling()
+        if hasattr(window, "_get_window_scaling")
+        else getattr(window, "_get_widget_scaling", lambda: 1.0)()
+    )
+
+    # Resolve window title
+    title_text = (
+        window.title()
+        if callable(getattr(window, "title", None))
+        else getattr(window, "_title_text", "Untitled")
+    )
+
+    class_name = window.__class__.__name__
+
+    print(f"\n--- {class_name} Telemetry ---")
+    print(f"Title:         {title_text}")
+    print(
+        f"Physical Size: {width}x{height} px @ {scaling:g} ({int(scaling * 100)}%) Scaling"
+    )
+    print(f"Baseline Size: {base_w}x{base_h} px (96 DPI)")
+    if hasattr(window, "_target_width"):
+        print(f"Target Width:  {window._target_width} px")
+    print(
+        f"Req Size:      {base_req_w}x{base_req_h} px (base) / {window.winfo_reqwidth()}x{window.winfo_reqheight()} px (phys)"
+    )
+    print("-" * (len(class_name) + 18) + "\n")
+
+
+def enable_debug_mode(app: Any, banner: str = DEBUG_BANNER) -> None:
+    """Activate debug mode across the application, popups, and future windows.
+
+    This function:
+      1. Sets the global debug state to active.
+      2. Appends the debug banner to the root application window title.
+      3. Binds <F12> globally so pressing F12 in any focused window prints its telemetry.
+
+    Args:
+        app: The root CTk or CTkToplevel application instance.
+        banner: Text appended to the window title to show debug is active.
+    """
+    global _DEBUG_ACTIVE
+    _DEBUG_ACTIVE = True
+
+    # Append banner to app title if not already present
+    if hasattr(app, "title") and callable(app.title):
+        current_title = app.title()
+        if banner not in current_title:
+            app.title(f"{current_title}{banner}")
+
+    def _handle_f12(event: Any) -> None:
+        target_window = event.widget.winfo_toplevel()
+        print_window_telemetry(target_window)
+
+    # Bind globally so whichever window has focus receives the F12 telemetry dump
+    if hasattr(app, "bind_all") and callable(app.bind_all):
+        app.bind_all("<F12>", _handle_f12)

ctkforge-0.1.0/src/ctkforge/geometry.py

@@ -0,0 +1,96 @@
+"""DPI-aware geometry, scaling, and coordinate conversion helpers for CustomTkinter."""
+
+from typing import Any, overload
+
+__all__ = ["scale", "unscale"]
+
+
+def _get_scaling(target: Any) -> float:
+    """Safely extract active DPI scaling factor from a CTk widget or window.
+
+    CustomTkinter defines `_get_window_scaling()` on CTkBaseClass, so `hasattr`
+    returns True for all widgets. However, the underlying private `__window_scaling`
+    attribute only exists on root `CTk` windows. Calling it on child widgets raises
+    AttributeError. We inspect `_get_widget_scaling` first and safely catch
+    AttributeError if `_get_window_scaling` is called on a child widget.
+    """
+    for method_name in ("_get_widget_scaling", "_get_window_scaling"):
+        method = getattr(target, method_name, None)
+        if callable(method):
+            try:
+                val = method()
+                if isinstance(val, (int, float)) and val > 0:
+                    return float(val)
+            except AttributeError:
+                continue
+    return 1.0
+
+
+@overload
+def unscale(target: Any, value: float, /) -> int: ...
+
+
+@overload
+def unscale(
+    target: Any,
+    value1: float,
+    value2: float,
+    /,
+    *values: float,
+) -> tuple[int, ...]: ...
+
+
+def unscale(target: Any, *values: float) -> int | tuple[int, ...]:
+    """Convert physical (device hardware) pixel values to logical (96 DPI baseline) integers.
+
+    Args:
+        target: A CTk widget or window providing the active DPI scaling factor.
+        *values: One or more physical pixel values to convert to logical units.
+
+    Returns:
+        A single logical integer if one value was provided, or a tuple of logical integers if multiple.
+
+    Raises:
+        ValueError: If no values are passed.
+    """
+    if not values:
+        raise ValueError("unscale() requires at least one value to convert.")
+
+    scaling = _get_scaling(target)
+    result = tuple(round(v / scaling) if scaling else round(v) for v in values)
+    return result[0] if len(result) == 1 else result
+
+
+@overload
+def scale(target: Any, value: float, /) -> int: ...
+
+
+@overload
+def scale(
+    target: Any,
+    value1: float,
+    value2: float,
+    /,
+    *values: float,
+) -> tuple[int, ...]: ...
+
+
+def scale(target: Any, *values: float) -> int | tuple[int, ...]:
+    """Convert logical (96 DPI baseline) pixel values to physical (device hardware) integers.
+
+    Args:
+        target: A CTk widget or window providing the active DPI scaling factor.
+        *values: One or more logical pixel values to convert to physical device units.
+
+    Returns:
+        A single physical integer if one value was provided, or a tuple of physical integers if multiple.
+
+    Raises:
+        ValueError: If no values are passed.
+    """
+    if not values:
+        raise ValueError("scale() requires at least one value to convert.")
+
+    scaling = _get_scaling(target)
+    result = tuple(round(v * scaling) if scaling else round(v) for v in values)
+    return result[0] if len(result) == 1 else result

ctkforge-0.1.0/src/ctkforge/popup/__init__.py

@@ -0,0 +1,20 @@
+"""CTkPopup - A robust, modern, and DPI-aware dialog replacement for CTkMessagebox.
+
+Features:
+  - 4 semantic button roles (primary, cancel, destructive, normal) with dedicated resting and hover colors
+  - Decoupled semantic return values (booleans, tokens)
+  - Hidden-staging window lifecycle preventing geometry jumps
+  - The Courier Rule: safe return values without widget destruction errors
+  - Automatic switching to copyable CTkTextbox for long logs and exceptions
+  - Option B Smart Fail-Safe icon resolution
+"""
+
+from .constants import PRESETS, ROLE_COLORS
+from .popup import CTkPopup
+
+__version__ = "1.0.0"
+__all__ = [
+    "PRESETS",
+    "ROLE_COLORS",
+    "CTkPopup",
+]