protonic 0.1.0__py3-none-any.whl

protonic/__init__.py

@@ -0,0 +1,10 @@
+"""
+Protonic: Instant OS App Prototyping & Declarative UI Engine.
+"""
+
+from .app import App, load, bg
+from .proxy import ElementProxy
+from .node import Node
+
+__version__ = "0.1.0"
+__all__ = ["App", "load", "bg", "ElementProxy", "Node", "__version__"]

protonic/app.py

@@ -0,0 +1,278 @@
+"""
+Proton Application Engine & Event Loop Bridge.
+"""
+
+import sys
+import threading
+import queue
+from pathlib import Path
+from typing import Dict, Any, Callable, Optional, Union
+
+from .node import Node
+from .parser import parse_xml
+from .proxy import ElementProxy
+from .backend_tk import TkBackend
+
+
+def bg(func: Callable) -> Callable:
+    """
+    Decorator that runs a handler function in a dedicated background worker thread,
+    keeping the GUI thread and 60fps rendering completely silky and unblocked.
+    """
+    def wrapper(*args, **kwargs):
+        thread = threading.Thread(target=func, args=args, kwargs=kwargs, daemon=True)
+        thread.start()
+        return thread
+    return wrapper
+
+
+class App:
+    """
+    Main Proton Application runtime.
+    """
+
+    def __init__(self, xml_source: Optional[Union[str, Path]] = None, xml: Optional[Union[str, Path]] = None):
+        source = xml if xml is not None else xml_source
+        self._xml_source = source
+        self.root_node: Optional[Node] = None
+        self._ready_handlers: list = []
+        self._click_handlers: Dict[str, Callable] = {}
+        self._change_handlers: Dict[str, Callable] = {}
+        self._shortcuts: Dict[str, Callable] = {}
+        self._event_queue: queue.Queue = queue.Queue()
+        self._backend: Optional[TkBackend] = None
+        self._proxies: Dict[str, ElementProxy] = {}
+
+        if source is not None:
+            self.load(source)
+
+    def load(self, xml_source: Union[str, Path]) -> "App":
+        """Loads and parses Proton XML source (string or file path)."""
+        self._xml_source = xml_source
+        self.root_node = parse_xml(xml_source)
+        return self
+
+    def register_handle(self, target_id: str, handle: Any) -> None:
+        """Registers a backend widget handle with an element proxy."""
+        if target_id in self._proxies:
+            self._proxies[target_id]._backend = handle
+        else:
+            self._proxies[target_id] = ElementProxy(target_id, self, backend_handle=handle)
+
+    def get_node(self, node_id: str) -> Optional[Node]:
+        """Looks up a Node in the AST by id."""
+        if self.root_node is None:
+            return None
+        return self.root_node.find_by_id(node_id)
+
+    def __getitem__(self, selector: str) -> ElementProxy:
+        """
+        Element selector accessor.
+        app['#id'] returns an ElementProxy for that widget.
+        """
+        target_id = selector.lstrip("#")
+        if target_id not in self._proxies:
+            handle = self._backend.get_handle(target_id) if self._backend else None
+            self._proxies[target_id] = ElementProxy(target_id, self, backend_handle=handle)
+        return self._proxies[target_id]
+
+    def __setitem__(self, selector: str, value: Any) -> None:
+        """
+        Syntactic sugar: app['#status'] = 'Active' sets .val or .text.
+        """
+        proxy = self[selector]
+        node = self.get_node(proxy.id)
+        if node and node.tag in ("input", "slider", "switch", "select", "list", "textarea", "progress", "table", "tableview", "treeview"):
+            proxy.val = value
+        else:
+            proxy.text = str(value)
+
+    # --- Decorators & Event Registrations ---
+
+    @staticmethod
+    def bg(func: Callable) -> Callable:
+        """Decorator for running tasks in a background thread."""
+        return bg(func)
+
+    def action(self, name: str) -> Callable:
+        """Decorator for action handlers mapped via do="action_name": @app.action('do_add')"""
+        clean_name = name.strip()
+        def decorator(func: Callable) -> Callable:
+            self._click_handlers[clean_name] = func
+            return func
+        return decorator
+
+    def click(self, selector: str) -> Callable:
+        """Decorator for button / widget click events: @app.click('#submit')"""
+        target_id = selector.lstrip("#")
+        def decorator(func: Callable) -> Callable:
+            self._click_handlers[target_id] = func
+            return func
+        return decorator
+
+    def double_click(self, selector: str) -> Callable:
+        """Decorator for double click events on tables/lists/trees: @app.double_click('#files_table')"""
+        target_id = selector.lstrip("#")
+        specific_key = f"{target_id}:double_click"
+        def decorator(func: Callable) -> Callable:
+            self._click_handlers[specific_key] = func
+            return func
+        return decorator
+
+    def submit(self, selector: str) -> Callable:
+        """Decorator for enter/submit events on inputs: @app.submit('#path_input')"""
+        target_id = selector.lstrip("#")
+        specific_key = f"{target_id}:submit"
+        def decorator(func: Callable) -> Callable:
+            self._click_handlers[specific_key] = func
+            return func
+        return decorator
+
+    def change(self, selector: str) -> Callable:
+        """Decorator for value change events (slider, switch, input): @app.change('#slider')"""
+        target_id = selector.lstrip("#")
+        def decorator(func: Callable) -> Callable:
+            self._change_handlers[target_id] = func
+            return func
+        return decorator
+
+    def shortcut(self, hotkey: str) -> Callable:
+        """
+        Decorator to bind a global keyboard accelerator / hotkey.
+        Example:
+            @app.shortcut('Ctrl+S')
+            @app.key('F5')
+            @app.key('Escape')
+        """
+        def decorator(func: Callable) -> Callable:
+            self.register_shortcut(hotkey, func)
+            return func
+        return decorator
+
+    key = shortcut  # Universal alias: @app.key('Ctrl+Q')
+
+    def register_shortcut(self, hotkey: str, handler: Callable) -> None:
+        """Registers a global keyboard shortcut with the runtime and active backend."""
+        clean = hotkey.strip()
+        self._shortcuts[clean] = handler
+        if self._backend and self._backend.root:
+            self._backend.bind_shortcut(clean, handler)
+
+    # --- Internal Event Triggers (called by Backend) ---
+
+    def trigger_click(self, node: Node) -> None:
+        """Dispatches click event to registered handler and/or node 'do' attribute."""
+        if node.id and node.id in self._click_handlers:
+            self._click_handlers[node.id]()
+        if node.do and node.do in self._click_handlers:
+            self._click_handlers[node.do]()
+
+    def trigger_action(self, node: Node, event_type: str, *args, **kwargs) -> None:
+        """Dispatches specialized events (e.g. double_click, submit)."""
+        specific_key = f"{node.id}:{event_type}" if node.id else None
+        if specific_key and specific_key in self._click_handlers:
+            try:
+                self._click_handlers[specific_key](*args, **kwargs)
+            except TypeError:
+                self._click_handlers[specific_key]()
+        elif node.id and node.id in self._click_handlers:
+            try:
+                self._click_handlers[node.id](*args, **kwargs)
+            except TypeError:
+                self._click_handlers[node.id]()
+        elif node.do and node.do in self._click_handlers:
+            try:
+                self._click_handlers[node.do](*args, **kwargs)
+            except TypeError:
+                self._click_handlers[node.do]()
+
+    def trigger_change(self, node: Node, val: Any) -> None:
+        """Dispatches change event to registered handler."""
+        if node.id and node.id in self._change_handlers:
+            self._change_handlers[node.id](val)
+
+    def ready(self, func: Callable) -> Callable:
+        """Decorator for lifecycle callbacks executed when UI is mapped and ready: @app.ready"""
+        self._ready_handlers.append(func)
+        return func
+
+    def trigger_ready(self) -> None:
+        """Dispatches ready events to registered startup handlers."""
+        for handler in self._ready_handlers:
+            try:
+                handler()
+            except Exception as e:
+                print(f"[Proton Ready Error] {e}", file=sys.stderr)
+
+    # --- Threading & Main Dispatch ---
+
+    def dispatch_to_main(self, action: Callable[[], None]) -> None:
+        """Queues an action to be safely executed on the main GUI thread."""
+        if self._backend:
+            if threading.current_thread() is threading.main_thread():
+                action()
+            else:
+                self._backend.post_action(action)
+        else:
+            action()
+
+    # --- Standard Dialogs ---
+
+    def alert(self, title: str, message: str) -> None:
+        """Shows an alert modal dialog."""
+        if self._backend:
+            self._backend.show_alert(title, message)
+        else:
+            print(f"[ALERT: {title}] {message}")
+
+    def confirm(self, title: str, message: str) -> bool:
+        """Shows a confirmation modal dialog (Yes/No). Returns True if confirmed."""
+        if self._backend:
+            return self._backend.show_confirm(title, message)
+        return True
+
+    def open_file(self, title: str = "Open File", filetypes: Optional[list] = None) -> Optional[str]:
+        """Shows native open file dialog. Returns selected file path or None."""
+        if self._backend:
+            return self._backend.show_open_file(title, filetypes)
+        return None
+
+    def save_file(self, title: str = "Save File", default_extension: str = "", filetypes: Optional[list] = None) -> Optional[str]:
+        """Shows native save file dialog. Returns selected file path or None."""
+        if self._backend:
+            return self._backend.show_save_file(title, default_extension, filetypes)
+        return None
+
+    def choose_dir(self, title: str = "Select Directory") -> Optional[str]:
+        """Shows native directory picker dialog. Returns selected folder path or None."""
+        if self._backend:
+            return self._backend.show_choose_dir(title)
+        return None
+
+    def after(self, ms: int, func: Callable) -> Optional[str]:
+        """Schedules a function to run after ms milliseconds on the main thread."""
+        if self._backend and hasattr(self._backend, "root") and self._backend.root:
+            return self._backend.root.after(ms, func)
+        return None
+
+    def cancel_after(self, after_id: Optional[str]) -> None:
+        """Cancels a scheduled after timer."""
+        if after_id and self._backend and hasattr(self._backend, "root") and self._backend.root:
+            try:
+                self._backend.root.after_cancel(after_id)
+            except Exception:
+                pass
+
+    # --- Run Loop ---
+
+    def run(self) -> None:
+        """Starts the native Proton window and enters the GUI event loop."""
+        if self.root_node is None:
+            raise RuntimeError("Cannot run Proton App: No XML UI loaded.")
+        self._backend = TkBackend(self)
+        self._backend.render_and_run(self.root_node)
+
+
+def load(xml_source: Union[str, Path]) -> App:
+    """Convenience helper to load an XML layout and return an App instance."""
+    return App(xml_source)