ctkforge 0.1.0__py3-none-any.whl

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/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/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/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",
+]

ctkforge/popup/buttons.py

@@ -0,0 +1,145 @@
+"""Button normalization and styling helpers for CTkPopup.
+
+Internal helper module. Not part of the public API.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+import customtkinter as ctk
+
+from .constants import ROLE_COLORS
+
+__all__: list[str] = []
+
+
+def normalize_buttons(raw_buttons: Any) -> list[dict[str, Any]]:
+    """Convert various button input styles into a standardized list of button dicts.
+
+    Supported input formats:
+      - Full dictionary:
+          [{"label": "Delete", "value": "del", "role": "destructive"}]
+      - Tuples:
+          [("Save", True)]                     -> role defaults to "primary"
+          [("Delete", False, "destructive")]  -> explicit role
+      - Plain strings:
+          ["OK"]               -> 1 button: role="primary"
+          ["Yes", "No"]        -> 2 buttons: first="primary", second="cancel"
+          ["Save", "Skip", "Cancel"] -> 3+ buttons: first="primary", last="cancel", middle="normal"
+
+    Returns:
+        List of dicts, each guaranteed to have 'label', 'value', and 'role' keys.
+    """
+    if not raw_buttons:
+        return [{"label": "OK", "value": "ok", "role": "primary"}]
+
+    # If developer accidentally passed a single string or dict instead of a list
+    if isinstance(raw_buttons, (str, dict, tuple)):
+        raw_buttons = [raw_buttons]
+
+    normalized: list[dict[str, Any]] = []
+    total = len(raw_buttons)
+
+    for index, item in enumerate(raw_buttons):
+        # 1. Full dictionary format
+        if isinstance(item, dict):
+            # Support both 'text' and 'label' for standard CustomTkinter syntax
+            label = str(item.get("text", item.get("label", "OK")))
+            value = item.get("value", label)
+            role = str(item.get("role", "normal"))
+            spec: dict[str, Any] = {"label": label, "value": value, "role": role}
+
+            # Optional custom color overrides per button
+            for color_key in ("fg_color", "hover_color", "text_color"):
+                if color_key in item:
+                    spec[color_key] = item[color_key]
+            if "color" in item and "fg_color" not in spec:
+                spec["fg_color"] = item["color"]
+
+            normalized.append(spec)
+
+        # 2. Tuple format
+        elif isinstance(item, tuple):
+            if len(item) == 1:
+                label = str(item[0])
+                value = label
+                role = "primary" if index == 0 else "normal"
+            elif len(item) == 2:
+                label = str(item[0])
+                value = item[1]
+                role = "primary" if index == 0 else "normal"
+            else:
+                label = str(item[0])
+                value = item[1]
+                role = str(item[2])
+            normalized.append({"label": label, "value": value, "role": role})
+
+        # 3. Plain string format
+        elif isinstance(item, str):
+            label = item
+            value = item
+
+            if total == 1:
+                role = "primary"
+            elif total == 2:
+                role = "primary" if index == 0 else "cancel"
+            else:
+                if index == 0:
+                    role = "primary"
+                elif index == total - 1:
+                    role = "cancel"
+                else:
+                    role = "normal"
+
+            normalized.append({"label": label, "value": value, "role": role})
+
+        # Fallback for unrecognized types
+        else:
+            text = str(item)
+            normalized.append({"label": text, "value": item, "role": "normal"})
+
+    return normalized
+
+
+def create_button(
+    master: Any,
+    spec: dict[str, Any],
+    on_click: Callable[[Any], None],
+    role_colors: dict[str, dict[str, Any]] | None = None,
+) -> ctk.CTkButton:
+    """Create a styled CTkButton based on its semantic role.
+
+    Args:
+        master: The parent container widget.
+        spec: Button definition dictionary containing 'label', 'value', and 'role'.
+        on_click: Callback function invoked with button's semantic value when clicked.
+        role_colors: Optional role-to-color mapping overriding default ROLE_COLORS.
+
+    Returns:
+        Configured ctk.CTkButton instance.
+    """
+    colors_map = role_colors or ROLE_COLORS
+    role = spec.get("role", "normal")
+    styling = colors_map.get(role, colors_map.get("normal", {}))
+
+    kwargs: dict[str, Any] = {
+        "text": spec.get("label", "OK"),
+        "command": lambda: on_click(spec.get("value")),
+        "height": 36,
+        "corner_radius": 6,
+    }
+
+    # Only pass explicit colors if defined (None lets CTk inherit theme accent)
+    if styling.get("fg_color") is not None:
+        kwargs["fg_color"] = styling["fg_color"]
+    if styling.get("hover_color") is not None:
+        kwargs["hover_color"] = styling["hover_color"]
+    if styling.get("text_color") is not None:
+        kwargs["text_color"] = styling["text_color"]
+
+    # Explicit per-button overrides take precedence
+    for color_key in ("fg_color", "hover_color", "text_color"):
+        if spec.get(color_key) is not None:
+            kwargs[color_key] = spec[color_key]
+
+    return ctk.CTkButton(master, **kwargs)

ctkforge/popup/constants.py

@@ -0,0 +1,107 @@
+"""Configuration constants, presets, and role color palettes for CTkPopup.
+
+All presets and role colors are defined at the module/class level so developers
+can customize themes and localization in one central place.
+"""
+
+from typing import Any
+
+# fmt: off
+# Layout dimensions and thresholds
+MAX_LABEL_HEIGHT: int = 300
+TEXTBOX_HEIGHT: int = 220
+TEXTBOX_WIDTH_PADDING: int = 40
+DEFAULT_POPUP_WIDTH: int = 478  # Baseline width (floor is ~355px for 2 buttons; ~478px fits full wrap 340 + icon 138)
+DEFAULT_WRAPLENGTH: int = 340  # Maximum horizontal wrap boundary for text
+ICON_DISPLAY_SIZE: tuple[int, int] = (64, 64)
+
+# Styling and typography tokens
+MESSAGE_FONT_SIZE: int = 13
+POPUP_BORDER_COLOR: tuple[str, str] = ("gray80", "gray25")
+POPUP_BORDER_WIDTH: int = 1
+# fmt: on
+
+# Color definitions for the 4 essential button roles.
+# Each role contains light and dark mode hex tuples: (light_color, dark_color).
+# "primary" uses None so it automatically inherits CustomTkinter's active accent color.
+ROLE_COLORS: dict[str, dict[str, Any]] = {
+    "primary": {
+        "fg_color": None,
+        "hover_color": None,
+        "text_color": None,
+    },
+    "destructive": {
+        "fg_color": ("#DC2626", "#EF4444"),
+        "hover_color": ("#B91C1C", "#DC2626"),
+        "text_color": ("#FFFFFF", "#FFFFFF"),
+    },
+    "cancel": {
+        "fg_color": ("#E5E7EB", "#374151"),
+        "hover_color": ("#D1D5DB", "#4B5563"),
+        "text_color": ("#1F2937", "#F9FAFB"),
+    },
+    "normal": {
+        "fg_color": ("#F3F4F6", "#1F2937"),
+        "hover_color": ("#E5E7EB", "#374151"),
+        "text_color": ("#374151", "#E5E7EB"),
+    },
+}
+
+# The 5 standard preset configurations for dialogs.
+# Exposes only title, icon, buttons, and keyboard action defaults.
+# Button layout follows Windows Standard (Microsoft Guidelines):
+# Primary action comes first (left), and Cancel is on the far right:
+#   [ Proceed ]  [ Cancel ]
+#   [ Delete ]   [ Cancel ]
+#   [ Yes ]      [ No ]
+# (Windows users read left-to-right and expect the affirmative action first).
+PRESETS: dict[str, dict[str, Any]] = {
+    "info": {
+        "title": "Information",
+        "icon": "info.png",
+        "buttons": [{"label": "OK", "value": "ok", "role": "primary"}],
+        "default_button": "ok",
+        "cancel_button": "ok",
+    },
+    "warning": {
+        "title": "Warning",
+        "icon": "warning.png",
+        "buttons": [
+            {"label": "Proceed", "value": True, "role": "primary"},
+            {"label": "Cancel", "value": False, "role": "cancel"},
+        ],
+        "default_button": True,
+        "cancel_button": False,
+    },
+    "error": {
+        "title": "Error",
+        "icon": "error.png",
+        "buttons": [{"label": "Dismiss", "value": "dismiss", "role": "destructive"}],
+        "default_button": "dismiss",
+        "cancel_button": "dismiss",
+    },
+    "question": {
+        "title": "Confirm",
+        "icon": "question.png",
+        "buttons": [
+            {"label": "Yes", "value": True, "role": "primary"},
+            {"label": "No", "value": False, "role": "cancel"},
+        ],
+        "default_button": True,
+        "cancel_button": False,
+    },
+    "success": {
+        "title": "Success",
+        "icon": "success.png",
+        "buttons": [{"label": "OK", "value": "ok", "role": "primary"}],
+        "default_button": "ok",
+        "cancel_button": "ok",
+    },
+}
+
+# Public customization tables (safe for application-wide customization).
+# All other constants in this file are internal layout defaults subject to change.
+__all__ = [
+    "PRESETS",
+    "ROLE_COLORS",
+]

ctkforge/popup/icons.py

@@ -0,0 +1,135 @@
+"""Icon resolution, loading, and high-DPI scaling for CTkPopup.
+
+Internal helper module. Not part of the public API.
+"""
+
+import importlib.resources
+import sys
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+import customtkinter as ctk
+from PIL import Image
+
+from ctkforge.resources import resource_path
+
+from .constants import ICON_DISPLAY_SIZE, PRESETS
+
+__all__: list[str] = []
+
+
+def load_image_as_ctk(
+    image_path: Path,
+    display_size: tuple[int, int] = ICON_DISPLAY_SIZE,
+) -> ctk.CTkImage:
+    """Open an image file with Pillow and wrap it into a DPI-aware CTkImage.
+
+    Pillow handles the master file (e.g., 256x256), while CustomTkinter downscales
+    it using Lanczos filtering to the logical display size (e.g., 48x48).
+    """
+    with Image.open(image_path) as img:
+        pil_img = img.copy()
+    return ctk.CTkImage(light_image=pil_img, dark_image=pil_img, size=display_size)
+
+
+def load_stock_icon(
+    icon_name: str,
+    display_size: tuple[int, int] = ICON_DISPLAY_SIZE,
+) -> ctk.CTkImage | None:
+    """Load a bundled stock icon from the popup/icons/ package directory.
+
+    Args:
+        icon_name: Base name (e.g. 'warning' or 'warning.png').
+        display_size: Target logical dimensions on screen.
+
+    Returns:
+        Configured ctk.CTkImage, or None if not found.
+    """
+    filename = icon_name if icon_name.endswith(".png") else f"{icon_name}.png"
+
+    with suppress(OSError, TypeError, ValueError, ModuleNotFoundError):
+        # Modern standard library package resource locator
+        resource_ref = importlib.resources.files(__package__).joinpath("icons", filename)
+        # In Python 3.9+, as_file yields a context or path
+        with importlib.resources.as_file(resource_ref) as path:
+            if path.is_file():
+                return load_image_as_ctk(path, display_size)
+
+    # Direct filesystem fallback for development / unpacked trees
+    local_path = Path(__file__).resolve().parent / "icons" / filename
+    if local_path.is_file():
+        return load_image_as_ctk(local_path, display_size)
+
+    return None
+
+
+def resolve_icon(
+    icon_input: Any,
+    preset_name: str | None = None,
+    display_size: tuple[int, int] = ICON_DISPLAY_SIZE,
+) -> ctk.CTkImage | None:
+    """Resolve an icon input through the fallback priority chain.
+
+    Priority Chain:
+      1. Pre-configured ctk.CTkImage -> use as-is.
+      2. Preset keyword or bundled stock icon filename.
+      3. Unified resource locator via resource_path (CWD, PyInstaller _MEIPASS, sys.argv[0]).
+      4. Option B Smart Fail-Safe: Log warning and fall back to stock preset icon.
+
+    Args:
+        icon_input: Image object, file path, stock preset name, or None.
+        preset_name: Optional active preset name (e.g., 'warning', 'error') for fallback.
+        display_size: Target logical display size.
+
+    Returns:
+        ctk.CTkImage if resolved, or None if no icon can be shown.
+    """
+    if icon_input is None:
+        if preset_name and preset_name in PRESETS:
+            stock_name = PRESETS[preset_name].get("icon", f"{preset_name}.png")
+            return load_stock_icon(stock_name, display_size)
+        return None
+
+    # Step 1: Already a ctk.CTkImage
+    if isinstance(icon_input, ctk.CTkImage):
+        return icon_input
+
+    # If it's a known stock preset keyword (e.g. "warning", "info")
+    if isinstance(icon_input, str) and icon_input in PRESETS:
+        stock_name = PRESETS[icon_input].get("icon", f"{icon_input}.png")
+        stock_img = load_stock_icon(stock_name, display_size)
+        if stock_img is not None:
+            return stock_img
+
+    if isinstance(icon_input, (str, Path)):
+        str_path = str(icon_input)
+
+        # Also check if it's a stock icon filename directly (e.g., "warning.png")
+        stock_img = load_stock_icon(str_path, display_size)
+        if stock_img is not None:
+            return stock_img
+
+        # Step 2: Unified resource locator (CWD, PyInstaller _MEIPASS, sys.argv[0])
+        resolved_file = resource_path(str_path)
+        if resolved_file is not None and resolved_file.is_file():
+            try:
+                return load_image_as_ctk(resolved_file, display_size)
+            except (OSError, ValueError) as e:
+                print(
+                    f"[CTkPopup Warning]: Error reading icon file '{resolved_file}': {e}",
+                    file=sys.stderr,
+                )
+
+    # Step 5: Option B Smart Fail-Safe
+    print(
+        f"[CTkPopup Warning]: Custom icon '{icon_input}' could not be resolved. "
+        f"Falling back to preset stock icon.",
+        file=sys.stderr,
+    )
+
+    if preset_name and preset_name in PRESETS:
+        stock_name = PRESETS[preset_name].get("icon", f"{preset_name}.png")
+        return load_stock_icon(stock_name, display_size)
+
+    return None