ren-ui-python 0.1.0__py3-none-any.whl

ren_ui/widgets.py

@@ -0,0 +1,380 @@
+from __future__ import annotations
+
+import ctypes
+import math
+from pathlib import Path
+from typing import Literal
+
+from ._native import utf8
+from .resources import image_path
+
+
+def _dimension(value, name, *, positive=False):
+    value = float(value)
+    if not math.isfinite(value) or value < 0 or (positive and value == 0):
+        raise ValueError(f"{name} must be {'positive' if positive else 'nonnegative'} and finite")
+    return value
+
+
+class Widget:
+    kind = ""
+
+    def __init__(self, text="", *, on_change=None, enabled=True):
+        utf8(text)
+        if on_change is not None and not callable(on_change):
+            raise TypeError("on_change must be callable")
+        self._text = text
+        self._value = 0
+        self._enabled = bool(enabled)
+        self.on_change = on_change
+        self._window = None
+        self._id = None
+
+    def _call(self, name, *args):
+        window = self._window
+        window._check_open()
+        return window.app._native.call(name, window.app._handle, window._id, self._id, *args)
+
+    def _mount(self, window, parent=0):
+        if self._window is not None:
+            raise ValueError("A widget can only belong to one window")
+        extra = getattr(self, "label", "")
+        a, b = (getattr(self, "spacing", 0), getattr(self, "padding", 0))
+        if self.kind == "slider":
+            a, b = self.minimum, self.maximum
+        elif self.kind == "image":
+            a, b = self.width, self.height
+            extra = self.fit
+        elif self.kind == "textarea":
+            a = self.wrap
+        self._id = window.app._native.call(
+            "view_create", window.app._handle, window._id, parent,
+            utf8(self.kind), utf8(self._text), utf8(extra), a, b,
+        )
+        self._window = window
+        window._widgets[self._id] = self
+        if self.kind == "button" and self._icon is not None:
+            self._call("button_icon", utf8(str(self._icon)), self.icon_size)
+        if self.kind in ("checkbox", "slider"):
+            self.value = self._value
+        if not self._enabled:
+            self.enabled = False
+        for child in getattr(self, "children", ()):
+            child._mount(window, self._id)
+
+    @property
+    def text(self):
+        if self._window:
+            return self._call("view_text").decode("utf-8")
+        return self._text
+
+    @text.setter
+    def text(self, value):
+        encoded = utf8(value)
+        if self._window:
+            self._call("view_set_text", encoded)
+        self._text = value
+
+    @property
+    def value(self):
+        if self._window:
+            result = ctypes.c_int()
+            self._call("view_value", ctypes.byref(result))
+            return result.value
+        return self._value
+
+    @value.setter
+    def value(self, value):
+        value = int(value)
+        if self.kind == "slider" and not self.minimum <= value <= self.maximum:
+            raise ValueError("slider value is outside its range")
+        if self.kind == "checkbox" and value not in (0, 1):
+            raise ValueError("checkbox value must be 0 or 1")
+        if self._window:
+            self._call("view_set_value", value)
+        self._value = value
+
+    @property
+    def enabled(self):
+        return self._enabled
+
+    @enabled.setter
+    def enabled(self, value):
+        if self._window:
+            self._call("view_enabled", bool(value))
+        self._enabled = bool(value)
+
+
+class Label(Widget):
+    kind = "label"
+
+
+class Button(Widget):
+    kind = "button"
+
+    def __init__(self, text, onclick=None, *, enabled=True,
+                 icon: str | Path | None = None, icon_size: int = 24):
+        super().__init__(text, on_change=onclick, enabled=enabled)
+        if type(icon_size) is not int or not 1 <= icon_size <= 256:
+            raise ValueError("icon_size must be an integer from 1 to 256")
+        self._icon_size = icon_size
+        self._icon = image_path(icon) if icon is not None else None
+
+    @property
+    def icon_size(self) -> int:
+        return self._icon_size
+
+    @property
+    def icon(self) -> Path | None:
+        return self._icon
+
+    @icon.setter
+    def icon(self, source: str | Path | None):
+        path = image_path(source) if source is not None else None
+        if self._window:
+            self._call("button_icon", utf8(str(path)) if path else b"", self.icon_size)
+        self._icon = path
+
+    def onclick(self, callback):
+        """Register one click handler; usable as a decorator or a method.
+
+        Replaces the previous handler and returns the original function.
+        The handler receives the same Event as a constructor callback.
+        """
+        if not callable(callback):
+            raise TypeError("onclick must be callable")
+        self.on_change = callback
+        return callback
+
+    def click(self):
+        """Send the native button invocation through the window's event loop."""
+        if self._window is None:
+            raise RuntimeError("Show the window before invoking a button")
+        if self.enabled:
+            self._call("view_invoke")
+
+
+class Image(Widget):
+    """An image in a fixed-size viewport, decoded by Haiku's Translation Kit."""
+    kind = "image"
+
+    def __init__(self, source: str | Path, *, width: float = 320, height: float = 200,
+                 fit: Literal["contain", "cover", "stretch"] = "contain"):
+        self._width = _dimension(width, "width", positive=True)
+        self._height = _dimension(height, "height", positive=True)
+        if self._width > 4096 or self._height > 4096:
+            raise ValueError("Image dimensions must not exceed 4096")
+        if fit not in ("contain", "cover", "stretch"):
+            raise ValueError("fit must be contain, cover, or stretch")
+        self._fit = fit
+        self._source = image_path(source)
+        super().__init__(str(self._source))
+
+    @property
+    def width(self) -> float:
+        return self._width
+
+    @property
+    def height(self) -> float:
+        return self._height
+
+    @property
+    def fit(self) -> str:
+        return self._fit
+
+    @property
+    def source(self) -> Path:
+        return self._source
+
+    @source.setter
+    def source(self, source: str | Path):
+        path = image_path(source)
+        if self._window:
+            self._call("image_source", utf8(str(path)))
+        self._source = path
+        self._text = str(path)
+
+
+class TextInput(Widget):
+    kind = "text"
+
+    def __init__(self, text="", *, label="", on_change=None, enabled=True):
+        super().__init__(text, on_change=on_change, enabled=enabled)
+        utf8(label)
+        self.label = label
+
+
+class TextArea(Widget):
+    """Scrollable UTF-8 text, up to 1 MiB, with native editing and undo.
+
+    Changes, including assignments to text after mounting, emit on_change.
+    wrap is a construction option; editable can be changed at runtime.
+    """
+    kind = "textarea"
+    MAX_BYTES = 1024 * 1024
+
+    def __init__(self, text="", *, on_change=None, editable=True, wrap=True):
+        self._validate_text(text)
+        super().__init__(text, on_change=on_change, enabled=editable)
+        self.wrap = bool(wrap)
+
+    @staticmethod
+    def _validate_text(value):
+        if len(utf8(value)) > TextArea.MAX_BYTES:
+            raise ValueError("TextArea supports at most 1 MiB of UTF-8 text")
+
+    @Widget.text.setter
+    def text(self, value):
+        self._validate_text(value)
+        Widget.text.fset(self, value)
+
+    @property
+    def editable(self):
+        return self.enabled
+
+    @editable.setter
+    def editable(self, value):
+        self.enabled = value
+
+
+class CheckBox(Widget):
+    kind = "checkbox"
+
+    def __init__(self, text, *, checked=False, on_change=None, enabled=True):
+        super().__init__(text, on_change=on_change, enabled=enabled)
+        self._value = int(bool(checked))
+
+    @property
+    def checked(self):
+        return bool(self.value)
+
+    @checked.setter
+    def checked(self, value):
+        self.value = int(bool(value))
+
+
+class Slider(Widget):
+    kind = "slider"
+
+    def __init__(self, text="", *, minimum=0, maximum=100, value=0, on_change=None):
+        super().__init__(text, on_change=on_change)
+        # The ABI carries layout/range values as floats; keep integers exact.
+        if not all(isinstance(v, int) and abs(v) <= 2**24 for v in (minimum, maximum, value)):
+            raise ValueError("slider bounds and value must be integers within +/- 2**24")
+        if minimum >= maximum:
+            raise ValueError("minimum must be less than maximum")
+        self.minimum, self.maximum = minimum, maximum
+        self.value = value
+
+
+class Column(Widget):
+    kind = "column"
+
+    def __init__(self, *children, spacing=8, padding=12):
+        super().__init__()
+        if not all(isinstance(child, Widget) for child in children):
+            raise TypeError("Layouts only accept widgets")
+        self.children = tuple(children)
+        self.spacing = _dimension(spacing, "spacing")
+        self.padding = _dimension(padding, "padding")
+
+
+class Row(Column):
+    kind = "row"
+
+
+class Window:
+    def __init__(self, app, title, content, *, width=480, height=280, resizable=True, onclose=None, on_close=None):
+        utf8(title)
+        if not isinstance(content, Widget):
+            raise TypeError("content must be a widget or layout")
+        if on_close is not None and not callable(on_close):
+            raise TypeError("on_close must be callable")
+        self.app, self.content, self.on_close = app, content, on_close
+        self._title = title
+        self.width = _dimension(width, "width", positive=True)
+        self.height = _dimension(height, "height", positive=True)
+        self.resizable = bool(resizable)
+        self._id = None
+        self._closed = False
+        self._closing = False
+        self._onclose = None
+        if onclose is not None:
+            self.onclose(onclose)
+        self._widgets = {}
+
+    def _check_open(self):
+        self.app._check_ui_thread()
+        if self._closed or self._closing or self.app._closed:
+            raise RuntimeError("Window has closed or is closing")
+
+    def onclose(self, callback):
+        """Register a close guard. Only a literal True allows the close.
+
+        Receives Event(source=self, kind="close_requested"). Also a decorator;
+        replaces the previous guard and returns the original function.
+        """
+        if not callable(callback):
+            raise TypeError("onclose must be callable")
+        self._onclose = callback
+        return callback
+
+    def _decide_close(self, event):
+        allow = False
+        try:
+            allow = self._onclose is None or self._onclose(event) is True
+        finally:
+            # An exception cancels the request and re-enables future attempts.
+            self.app._native.call("window_close_reply", self.app._handle, self._id, allow)
+            self._closing = allow
+
+    def _validate_tree(self):
+        seen = set()
+        def visit(widget):
+            if id(widget) in seen or widget._window is not None:
+                raise ValueError("Each widget must appear exactly once and cannot be reused")
+            seen.add(id(widget))
+            for child in getattr(widget, "children", ()):
+                visit(child)
+        visit(self.content)
+
+    def show(self):
+        self._check_open()
+        if self._id is None:
+            self._validate_tree()
+            native = self.app._ensure_native()
+            self._id = native.call("window_create", self.app._handle, utf8(self.title),
+                                   self.width, self.height, self.resizable)
+            self.app._windows[self._id] = self
+            try:
+                # A bare widget is hosted like Column(widget): without a layout
+                # its preferred size would cap the window below the requested size.
+                root = self.content if isinstance(self.content, Column) else Column(self.content)
+                root._mount(self)
+            except Exception:
+                self.close()
+                raise
+        self.app._native.call("window_show", self.app._handle, self._id)
+        return self
+
+    def close(self):
+        """Request a close asynchronously through onclose, if registered."""
+        self.app._check_ui_thread()
+        if self._closed or self._closing or self.app._closed:
+            return
+        if self._id is not None:
+            self.app._native.call("window_close", self.app._handle, self._id)
+        else:
+            self._closed = True  # No native window or close event before show().
+
+    @property
+    def title(self):
+        return self._title
+
+    @title.setter
+    def title(self, value):
+        encoded = utf8(value)
+        self._check_open()
+        if self._id is not None:
+            self.app._native.call("window_title", self.app._handle, self._id, encoded)
+        self._title = value

ren_ui_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: ren-ui-python
+Version: 0.1.0
+Summary: Native RenkuOS/HaikuOS desktop apps in Python, packaged as HPKG
+Author-email: Lee JunHaeng aka rainygirl <rainygirl@gmail.com>
+License-Expression: MIT
+Project-URL: Documentation, https://ren-ui-python.rainygirl.com/
+Keywords: haiku,renkuos,gui,native,hpkg
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Other OS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: C++
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ren-ui-python
+
+Write native RenkuOS/HaikuOS desktop apps in plain Python and package them as `.hpkg`.
+
+The windows, buttons and dialogs are the system's own controls, driven through a small C++ bridge to `libbe`. There is no web view and no extra syntax to learn beyond Python.
+
+```python
+from ren_ui import Application, Event, Window, Column, Row, Label, TextInput, Button
+
+with Application("application/x-vnd.example-hello") as app:
+    message = Label("Welcome!")
+    name = TextInput(label="Name:")
+    greet_button = Button("Say hello")
+
+    @greet_button.onclick
+    def greet(event: Event):
+        message.text = f"Hello, {name.text or 'Haiku'}!"
+
+    Window(app, "Hello", Column(message, name, Row(greet_button, padding=0))).show()
+    app.run()
+```
+
+## Documentation
+
+**<https://ren-ui-python.rainygirl.com/>** - reference and tutorials in English, 한국어, 日本語, Italiano and Français.
+
+## Requirements
+
+- Running apps and building packages: RenkuOS or Haiku (x86_64, 32-bit x86 hybrid, arm64), Python 3.11 or newer with a shared `libpython`, and a C++17 compiler (`ren doctor` checks the tools).
+- Other systems (macOS, Linux, Windows): the package installs and you can create, check and stage projects, but windows cannot be shown.
+
+## Install
+
+```sh
+pip install ren-ui-python
+```
+
+## Command line
+
+```sh
+ren init my_app      # create a project
+ren check my_app     # validate the manifest and sources (any OS)
+ren doctor           # check the build tools
+ren run my_app       # compile the bridge and run the app
+ren build my_app     # produce an installable .hpkg
+```
+
+A built package depends on the system's Python library (for example `lib:libpython3.12`), so `pkgman install` pulls in Python automatically.
+
+## What is included
+
+- Widgets: `Label`, `Button`, `TextInput`, `TextArea`, `CheckBox`, `Slider`, `Image`, laid out with `Column` and `Row`
+- `ren_ui.system`: alerts and confirmations, native open/save file panels, clipboard, opening URLs, the settings directory
+- The `ren` tool: project scaffold, validation, HPKG packaging with app signature, icon and Deskbar entry
+
+## License
+
+MIT

ren_ui_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+ren_ui/__init__.py,sha256=4Y1PmeU5j23zmuEHzlCcVUcnN6soSUkltOBTM45klyo,432
+ren_ui/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+ren_ui/_native.py,sha256=KTHsIGLHG5fVcSdfhfTS0_mHME3TjTtnKE78zRGG8WE,2907
+ren_ui/app.py,sha256=9ZoOBPUeXzFMAnWclgi6W4gsxS6gP6ZQc3nDSN0wepw,5637
+ren_ui/build.py,sha256=zw_5m7AiFHw1JcpQVXvI-z8QklIg_plv8rbAHA9t2Us,13039
+ren_ui/cli.py,sha256=btDNi185_zFyjcQGUfHrz-ela1C1YACAEIylimr59rk,6701
+ren_ui/project.py,sha256=9H-d_2km-gF6CMUk4dUJkLNDHp_Mpgie-TKkZ4XqX8U,9976
+ren_ui/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ren_ui/resources.py,sha256=9DL2ioFogrd_Fqn4mqzUi2_gTS5qE_at4CR7qMy-HuM,1208
+ren_ui/system.py,sha256=CyXttiKEd7Yns2ziwmQYWGvBszpflB-NJLndwn9Amdw,2605
+ren_ui/widgets.py,sha256=Q0xpmKvvF5GlNxnwiu7k5L_I32vjWQQtR7dUyjT1_q4,12829
+ren_ui/native/bridge.cpp,sha256=px_hwpqsHJoCkjaBX6YZShjnH8TEy6_j5aJZD0P3hpo,25738
+ren_ui/native/icon.cpp,sha256=SD8zUQiI7umRVhR1QZxjZpE_PKmomCVlIkRaE60xBRo,3180
+ren_ui/native/launcher.cpp,sha256=BTx4AZeCwb1grZNlqKTlo5FJ0kaM3nEmCfQH8S74LbM,2371
+ren_ui_python-0.1.0.dist-info/licenses/LICENSE,sha256=UalO_7O5rJWiGc4bYF0OH8J9Qhs5dfHtxWFulh_BKjQ,1083
+ren_ui_python-0.1.0.dist-info/METADATA,sha256=p5a3gvfXogEoVaGusZzEv0tXve6BMpdHaMyUQTzkxhM,3119
+ren_ui_python-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ren_ui_python-0.1.0.dist-info/entry_points.txt,sha256=LOkVNW7u9QKiSoTpTn4D-PBn7SuVlws5Gs9wHCPZM2g,65
+ren_ui_python-0.1.0.dist-info/top_level.txt,sha256=9NpBXuu4pH2npjBvFuTgZhg-QhPeshZxZByoj3WUDSg,7
+ren_ui_python-0.1.0.dist-info/RECORD,,

ren_ui_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ren_ui_python-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ren = ren_ui.cli:main
+ren-ui = ren_ui.cli:main

ren_ui_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ren-ui-python contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ren_ui_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ren_ui