runtui 0.1.0__tar.gz

runtui-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+dist/
+build/
+*.egg-info/

runtui-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: runtui
+Version: 0.1.0
+Summary: Modern pure-Python cross-platform TUI framework with RAD designer, themes, mouse support, embedded terminals, and rich widgets
+Project-URL: Homepage, https://github.com/erickrus/runtui
+Project-URL: Repository, https://github.com/erickrus/runtui
+Project-URL: Bug Tracker, https://github.com/erickrus/runtui/issues
+Project-URL: Documentation, https://github.com/erickrus/runtui#readme
+Author-email: Erickrus <hyinghao@gmail.com>
+License: MIT
+Keywords: curses-alternative,mouse,rad,terminal-ui,tui,widgets
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# RunTUI — Modern Terminal UI Framework for Python
+
+*Build beautiful, interactive, mouse-aware terminal applications in pure Python — no curses, no ncurses, no external dependencies.*
+
+<p align="center">
+  <img src="https://github.com/Erickrus/runtui/blob/main/images/demo.gif?raw=true" alt="runtui in action — animated demo">
+</p>
+
+`runtui` is a full-featured, cross-platform **TUI (Text User Interface)** library written in **100% pure Python**.  
+It brings modern desktop-like experience into your terminal: windows, dialogs, forms, image rendering, embedded terminals, mouse support, theming, layout managers and even a **visual RAD (Rapid Application Development) designer**.
+
+Works seamlessly on **Linux**, **macOS**, and **Windows**
+
+## ✨ Highlights
+
+- Pure Python — zero compiled dependencies
+- Cross-platform (Linux, macOS, Windows)
+- Rich set of **widgets** — Button, Input, Password, TextArea, Dropdown, ListBox, CheckBox, Radio, Calendar, ColorPicker, ProgressBar, Image, **real Terminal**, etc.
+- Multiple **layout** engines: Absolute, Box, Dock, Grid
+- Theme engine with built-in themes: Dark, Light, Nord, Solarized, Turbo Vision / Borland style
+- Mouse support (click, drag, scroll, hover)
+- Window manager with floating & tiled windows + taskbar
+- Dialogs: MessageBox, File Open/Save, Custom Forms
+- **Visual RAD designer** (`rad_designer.py`) — drag & drop UI building + code generation
+- Embedded **terminal** widget with PTY support (run vim, htop, bash, python REPL, … inside your app!)
+- Clean event loop, timers, key bindings, context menus
+
+## Installation
+
+```bash
+git clone https://github.com/Erickrus/runtui.git
+cd runtui
+pip install -e .
+# or
+pip install .
+```
+
+More examples in the [`examples/`](examples/) folder:
+
+- `cal.py`               — Calendar
+- `calc.py`              — Calculator
+- `chatbox.py`           — LLM Chat App
+- `clock.py`             — A basic clock program
+- `demo_app.py`          — widget showcase
+- `mine.py`              - window's mine game
+- `notes.py`             — mac os like personal notes
+- `rad_designer.py`      — visual designer (very cool!)
+- `puzzle.py`            — mac os like puzzle game
+- `tui_os.py`            — tui desktop / OS-like interface
+
+It is highly recommended to run everything inside `tui_os.py` by browse these python files in Finder.
+
+
+## Why choose runtui over other TUI libraries?
+
+| Feature                     | runtui      | Textual     | urwid      | py_cui     | rich + textual |
+|-----------------------------|-------------|-------------|------------|------------|----------------|
+| Pure Python                 | ✓           | ✓           | ✓          | ✓          | ✓              |
+| Cross-platform (good)       | ✓           | ✓           | △          | ✓          | ✓              |
+| Mouse support               | ✓           | ✓           | ✗          | ✓          | ✓              |
+| Built-in themes             | ✓ (many)    | ✓ (CSS)     | ✗          | ✗          | ✓              |
+| Embedded terminal widget    | ✓ (PTY)     | ✗           | ✗          | ✗          | ✗              |
+| Visual RAD designer         | ✓           | ✗           | ✗          | ✗          | ✗              |
+| Image rendering             | ✓           | ✓           | ✗          | ✗          | ✓              |
+| Floating windows + taskbar  | ✓           | △           | ✗          | ✗          | ✗              |
+| LLM Chat App                | ✓           | ✗           | ✗          | ✗          | ✗              |
+
+
+## License
+
+MIT
+
+---
+
+Made with ❤️ in the terminal  
+Start building your next TUI masterpiece today!

runtui-0.1.0/README.md

@@ -0,0 +1,76 @@
+# RunTUI — Modern Terminal UI Framework for Python
+
+*Build beautiful, interactive, mouse-aware terminal applications in pure Python — no curses, no ncurses, no external dependencies.*
+
+<p align="center">
+  <img src="https://github.com/Erickrus/runtui/blob/main/images/demo.gif?raw=true" alt="runtui in action — animated demo">
+</p>
+
+`runtui` is a full-featured, cross-platform **TUI (Text User Interface)** library written in **100% pure Python**.  
+It brings modern desktop-like experience into your terminal: windows, dialogs, forms, image rendering, embedded terminals, mouse support, theming, layout managers and even a **visual RAD (Rapid Application Development) designer**.
+
+Works seamlessly on **Linux**, **macOS**, and **Windows**
+
+## ✨ Highlights
+
+- Pure Python — zero compiled dependencies
+- Cross-platform (Linux, macOS, Windows)
+- Rich set of **widgets** — Button, Input, Password, TextArea, Dropdown, ListBox, CheckBox, Radio, Calendar, ColorPicker, ProgressBar, Image, **real Terminal**, etc.
+- Multiple **layout** engines: Absolute, Box, Dock, Grid
+- Theme engine with built-in themes: Dark, Light, Nord, Solarized, Turbo Vision / Borland style
+- Mouse support (click, drag, scroll, hover)
+- Window manager with floating & tiled windows + taskbar
+- Dialogs: MessageBox, File Open/Save, Custom Forms
+- **Visual RAD designer** (`rad_designer.py`) — drag & drop UI building + code generation
+- Embedded **terminal** widget with PTY support (run vim, htop, bash, python REPL, … inside your app!)
+- Clean event loop, timers, key bindings, context menus
+
+## Installation
+
+```bash
+git clone https://github.com/Erickrus/runtui.git
+cd runtui
+pip install -e .
+# or
+pip install .
+```
+
+More examples in the [`examples/`](examples/) folder:
+
+- `cal.py`               — Calendar
+- `calc.py`              — Calculator
+- `chatbox.py`           — LLM Chat App
+- `clock.py`             — A basic clock program
+- `demo_app.py`          — widget showcase
+- `mine.py`              - window's mine game
+- `notes.py`             — mac os like personal notes
+- `rad_designer.py`      — visual designer (very cool!)
+- `puzzle.py`            — mac os like puzzle game
+- `tui_os.py`            — tui desktop / OS-like interface
+
+It is highly recommended to run everything inside `tui_os.py` by browse these python files in Finder.
+
+
+## Why choose runtui over other TUI libraries?
+
+| Feature                     | runtui      | Textual     | urwid      | py_cui     | rich + textual |
+|-----------------------------|-------------|-------------|------------|------------|----------------|
+| Pure Python                 | ✓           | ✓           | ✓          | ✓          | ✓              |
+| Cross-platform (good)       | ✓           | ✓           | △          | ✓          | ✓              |
+| Mouse support               | ✓           | ✓           | ✗          | ✓          | ✓              |
+| Built-in themes             | ✓ (many)    | ✓ (CSS)     | ✗          | ✗          | ✓              |
+| Embedded terminal widget    | ✓ (PTY)     | ✗           | ✗          | ✗          | ✗              |
+| Visual RAD designer         | ✓           | ✗           | ✗          | ✗          | ✗              |
+| Image rendering             | ✓           | ✓           | ✗          | ✗          | ✓              |
+| Floating windows + taskbar  | ✓           | △           | ✗          | ✗          | ✗              |
+| LLM Chat App                | ✓           | ✗           | ✗          | ✗          | ✗              |
+
+
+## License
+
+MIT
+
+---
+
+Made with ❤️ in the terminal  
+Start building your next TUI masterpiece today!

runtui-0.1.0/docs/__init__.md

@@ -0,0 +1,30 @@
+# runtui Package
+
+The main runtui package exports the core classes and widgets for building terminal user interfaces.
+
+## Exports
+
+The following classes and functions are exported from the main package:
+
+| Name | Module | Description |
+|------|--------|-------------|
+| `App` | `app` | Main application class for running TUI applications |
+| `Window` | `windows.window` | Top-level window widget with title bar and chrome |
+| `MenuBar` | `widgets.menu` | Top-level menu bar widget |
+| `Menu` | `widgets.menu` | Dropdown menu container |
+| `MenuItem` | `widgets.menu` | Individual menu item |
+| `RadioGroup` | `widgets.radio` | Group container for radio buttons |
+
+## Usage
+
+```python
+from runtui import App, Window
+
+class MyApp(App):
+    def on_ready(self):
+        window = Window(title="My Window")
+        self.add_window(window)
+
+app = MyApp()
+app.run()
+```

runtui-0.1.0/docs/app.md

@@ -0,0 +1,174 @@
+# app.py - Application Class
+
+The main application class that manages the terminal UI lifecycle, event loop, and rendering.
+
+---
+
+## Class: `Desktop`
+
+Desktop background widget that fills with a checkerboard pattern.
+
+### Methods
+
+#### `paint`
+```python
+def paint(self, painter: Painter) -> None
+```
+Draw the desktop background with alternating character pattern.
+
+---
+
+## Class: `App`
+
+The base class for runtui applications. Handles terminal setup, event processing, and rendering.
+
+### Constructor
+
+```python
+def __init__(self, theme: str = "turbo_vision") -> None
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `theme` | `str` | `"turbo_vision"` | Theme name to use |
+
+### Available Themes
+
+- `"turbo_vision"` - Classic DOS-era look (default)
+- `"github"` - GitHub-inspired light theme
+- `"vscode"` - VS Code dark theme
+- `"gruvbox"` - Gruvbox dark theme
+- `"high_contrast"` - High contrast accessibility
+- `"legacy_system"` - DOS/BIOS theme
+- `"black_white"` - Monochrome theme
+- `"dark"` - Dark theme
+- `"light"` - Light theme
+- `"nord"` - Nord color scheme
+- `"solarized"` - Solarized theme
+
+### Properties
+
+#### `running`
+```python
+@property
+def running(self) -> bool
+```
+Returns `True` if the application is currently running.
+
+### Methods
+
+#### `run`
+```python
+def run(self) -> None
+```
+Start the application main loop. Blocks until `quit()` is called.
+
+#### `quit`
+```python
+def quit(self) -> None
+```
+Stop the application and restore the terminal to normal mode.
+
+#### `on_ready`
+```python
+def on_ready(self) -> None
+```
+Callback called after the application is initialized and ready. Override this method to set up your UI.
+
+#### `add_window`
+```python
+def add_window(self, window: Window) -> None
+```
+Add a window to the desktop.
+
+**Parameters:**
+- `window` (`Window`): The window to add
+
+#### `remove_window`
+```python
+def remove_window(self, window: Window) -> None
+```
+Remove a window from the desktop.
+
+**Parameters:**
+- `window` (`Window`): The window to remove
+
+#### `set_menu`
+```python
+def set_menu(self, menu_bar: MenuBar) -> None
+```
+Set the application menu bar.
+
+**Parameters:**
+- `menu_bar` (`MenuBar`): The menu bar widget to use
+
+#### `invalidate_all`
+```python
+def invalidate_all(self) -> None
+```
+Force a full repaint of the screen.
+
+#### `set_theme`
+```python
+def set_theme(self, name: str) -> None
+```
+Change the active theme.
+
+**Parameters:**
+- `name` (`str`): Theme name to activate
+
+#### `call_later`
+```python
+def call_later(self, delay: float, callback: Callable[[], None]) -> TimerHandle | None
+```
+Schedule a callback to be executed after a delay.
+
+**Parameters:**
+- `delay` (`float`): Delay in seconds
+- `callback` (`Callable[[], None]`): The function to call
+
+**Returns:** `TimerHandle | None` - Handle to cancel the timer
+
+#### `set_interval`
+```python
+def set_interval(self, interval: float, callback: Callable[[], None]) -> TimerHandle | None
+```
+Start a repeating timer.
+
+**Parameters:**
+- `interval` (`float`): Interval in seconds
+- `callback` (`Callable[[], None]`): Function to call on each tick
+
+**Returns:** `TimerHandle | None` - Handle to stop the timer
+
+### Global Key Bindings
+
+| Key | Action |
+|-----|--------|
+| Ctrl+Q | Quit application |
+| Alt+Tab | Cycle to next window |
+| Alt+Shift+Tab | Cycle to previous window |
+| Tab | Focus next widget |
+| Shift+Tab | Focus previous widget |
+| F10 | Activate menu bar |
+
+### Usage
+
+```python
+from runtui import App, Window, Label
+
+class MyApp(App):
+    def __init__(self):
+        super().__init__(theme="turbo_vision")
+
+    def on_ready(self):
+        window = Window(title="My App")
+        window.set_content(Label("Hello, World!"))
+        self.add_window(window)
+
+if __name__ == "__main__":
+    app = MyApp()
+    app.run()
+```

runtui-0.1.0/docs/backend/__init__.md

@@ -0,0 +1,19 @@
+# backend Package
+
+Terminal backend abstraction layer for cross-platform terminal I/O.
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `base` | Abstract backend interface |
+| `detect` | Platform detection to select the appropriate backend |
+| `unix` | Unix (Linux/macOS) terminal backend |
+| `windows` | Windows terminal backend |
+
+## Platform Support
+
+The backend automatically detects the platform and selects the appropriate implementation:
+
+- **Unix**: Uses ANSI escape sequences, termios, and select()
+- **Windows**: Uses VT100 sequences via Windows Terminal / ConEmu with Win32 Console API fallback

runtui-0.1.0/docs/backend/base.md

@@ -0,0 +1,161 @@
+# base.py - Backend Interface
+
+Abstract backend interface for terminal I/O.
+
+---
+
+## Class: `Backend`
+
+Abstract interface for terminal backends.
+
+### Abstract Methods
+
+#### `init`
+```python
+@abstractmethod
+def init(self) -> None
+```
+Enter raw mode, alternate screen, and enable mouse tracking.
+
+#### `shutdown`
+```python
+@abstractmethod
+def shutdown(self) -> None
+```
+Restore terminal to original state.
+
+#### `get_size`
+```python
+@abstractmethod
+def get_size(self) -> tuple[int, int]
+```
+Get the terminal size.
+
+**Returns:** `tuple[int, int]` - (columns, rows)
+
+#### `read_input`
+```python
+@abstractmethod
+def read_input(self) -> bytes
+```
+Read available raw bytes from terminal input (non-blocking).
+
+**Returns:** `bytes` - Raw input bytes, or empty bytes if nothing available
+
+#### `decode_input`
+```python
+@abstractmethod
+def decode_input(self, raw: bytes) -> list[Event]
+```
+Parse raw bytes into Event objects.
+
+**Parameters:**
+- `raw` (`bytes`): Raw input bytes
+
+**Returns:** `list[Event]` - Decoded events
+
+#### `write`
+```python
+@abstractmethod
+def write(self, data: str) -> None
+```
+Write string data (including escape sequences) to terminal.
+
+**Parameters:**
+- `data` (`str`): Data to write
+
+#### `flush`
+```python
+@abstractmethod
+def flush(self) -> None
+```
+Flush output buffer to terminal.
+
+#### `set_cursor_position`
+```python
+@abstractmethod
+def set_cursor_position(self, x: int, y: int) -> None
+```
+Move cursor to position (x, y) where (0, 0) is top-left.
+
+**Parameters:**
+- `x` (`int`): Column position
+- `y` (`int`): Row position
+
+#### `set_cursor_visible`
+```python
+@abstractmethod
+def set_cursor_visible(self, visible: bool) -> None
+```
+Show or hide the hardware cursor.
+
+**Parameters:**
+- `visible` (`bool`): True to show, False to hide
+
+#### `color_support`
+```python
+@abstractmethod
+def color_support(self) -> ColorDepth
+```
+Detect the terminal's color depth capability.
+
+**Returns:** `ColorDepth` - The detected color depth
+
+### PTY Methods
+
+#### `register_pty_fd`
+```python
+def register_pty_fd(self, fd: int, callback: Callable[[bytes], None]) -> None
+```
+Register a PTY master fd to be polled alongside stdin.
+
+**Parameters:**
+- `fd` (`int`): PTY master file descriptor
+- `callback` (`Callable[[bytes], None]`): Callback for received data
+
+#### `unregister_pty_fd`
+```python
+def unregister_pty_fd(self, fd: int) -> None
+```
+Remove a previously registered PTY fd.
+
+**Parameters:**
+- `fd` (`int`): PTY master file descriptor
+
+### Terminal Escape Helpers
+
+#### `enter_alternate_screen`
+```python
+def enter_alternate_screen(self) -> None
+```
+Switch to the alternate screen buffer.
+
+#### `leave_alternate_screen`
+```python
+def leave_alternate_screen(self) -> None
+```
+Return to the main screen buffer.
+
+#### `enable_mouse`
+```python
+def enable_mouse(self) -> None
+```
+Enable SGR any-event mouse tracking.
+
+#### `disable_mouse`
+```python
+def disable_mouse(self) -> None
+```
+Disable mouse tracking.
+
+#### `clear_screen`
+```python
+def clear_screen(self) -> None
+```
+Clear the screen.
+
+#### `reset_attributes`
+```python
+def reset_attributes(self) -> None
+```
+Reset all text attributes to default.

runtui-0.1.0/docs/backend/detect.md

@@ -0,0 +1,27 @@
+# backend/detect.md - Platform Detection
+
+Auto-detect platform and create appropriate backend.
+
+---
+
+## Functions
+
+### `create_backend`
+
+```python
+def create_backend() -> Backend
+```
+
+Create the appropriate backend for the current platform.
+
+**Returns:** `Backend` - A platform-appropriate backend instance
+
+### Platform Detection Logic
+
+| Platform | Backend |
+|----------|---------|
+| Linux | `UnixBackend` |
+| Darwin (macOS) | `UnixBackend` |
+| FreeBSD | `UnixBackend` |
+| Windows | `WindowsBackend` |
+| Other | `UnixBackend` (fallback) |