Termux:GUI Rust Bindings

A Rust library for building Android GUI applications using Termux:GUI. This project provides idiomatic Rust bindings for the Termux:GUI plugin, making it easy to create native Android interfaces from the Termux terminal environment.

Features

✅ Complete Termux:GUI Protocol Implementation - Full support for the low-level communication protocol
✅ Rich Widget Library - 12+ UI components (Button, TextView, EditText, WebView, etc.)
✅ Advanced Layouts - 7 layout types including Linear, Grid, Frame, Tab, and Scroll layouts
✅ WebView Integration - Full web content support with JavaScript execution
✅ Type Safety - Leverages Rust's type system for compile-time correctness
✅ Memory Safety - Zero-cost abstractions with guaranteed memory safety
✅ Comprehensive Examples - 21 working examples covering all components
✅ International Ready - 100% English documentation, ready for worldwide use

Quick Start

Installation

Add this library to your Rust project:

cargo add termux-gui

Or add it manually to your Cargo.toml:

[dependencies]
termux-gui = "0.3.0"

Prerequisites

1. Install Termux on your Android device
2. Install the Termux:GUI plugin from F-Droid
3. Install Rust in Termux:

pkg install rust

Building from Source

cd termux-gui-rust-demo
cargo build --release

Running Examples

Run any of the v2 examples (which use the new library API):

# Button demo
cargo run --example button_demo_v2

# Input fields demo
cargo run --example input_demo_v2

# Complex layout demo
cargo run --example grid_layout_demo_v2

# WebView demo
cargo run --example webview_demo_v2

Or run the pre-built binaries:

./target/release/examples/button_demo_v2

Available Widgets

Basic Widgets

• Button - Clickable buttons with text and styling
• TextView - Display static or dynamic text
• EditText - Single-line and multi-line text input
• Checkbox - Toggle checkboxes with state management
• Switch - Toggle switches
• RadioButton/RadioGroup - Mutually exclusive option selection
• Spinner - Dropdown selection lists
• ToggleButton - Two-state toggle buttons

Display Widgets

• ImageView - Display images from files or base64 data
• ProgressBar - Show progress (determinate or indeterminate)
• Space - Flexible spacing for layouts
• WebView - Embed web content with full JavaScript support

Container Widgets

• LinearLayout - Vertical or horizontal linear layouts
• GridLayout - Grid-based layouts
• FrameLayout - Stack-based layouts
• HorizontalScrollView - Horizontal scrolling container
• NestedScrollView - Vertical scrolling container
• SwipeRefreshLayout - Pull-to-refresh pattern
• TabLayout - Tabbed interface

Example: Simple Button App

use termux_gui::{Activity, Result};

fn main() -> Result<()> {
    // Create a full-screen activity
    let mut activity = Activity::new(false)?;
    
    // Create vertical layout
    let layout = activity.create_linear_layout(None)?;
    
    // Add a button
    let button = activity.create_button("Click Me!", Some(layout.id()))?;
    
    // Button will generate click events
    // Handle them in your event loop
    
    Ok(())
}

For complete working examples, see the examples/ directory.

Library Structure

src/
├── lib.rs                 # Public API and exports
├── error.rs               # Error types
├── connection.rs          # Socket communication
├── activity.rs            # Activity management
├── view.rs                # Base view operations
└── components/            # UI components (19 files)
    ├── button.rs
    ├── text_view.rs
    ├── edit_text.rs
    ├── checkbox.rs
    ├── switch.rs
    ├── radio.rs
    ├── spinner.rs
    ├── layout.rs          # All layout types
    ├── image_view.rs
    ├── progress_bar.rs
    ├── toggle_button.rs
    ├── space.rs
    └── web_view.rs

Core Architecture

Communication Protocol

The library implements the Termux:GUI protocol using:

• Dual Socket Architecture - Separate channels for commands and events
• Binary Protocol - 4-byte big-endian length prefix + JSON payload
• Abstract Unix Domain Sockets - Uses Linux abstract namespace for zero-filesystem-impact communication
• Async Event Handling - Non-blocking event loop with thread-based handling

Type Safety

Rust's type system ensures:

• Widget IDs are properly typed and cannot be confused
• Event handlers are type-safe
• Resource cleanup is automatic via RAII
• No null pointer exceptions or data races

Documentation

Each widget has comprehensive examples in the examples/ directory. The examples demonstrate:

• Basic usage
• Event handling
• Layout composition
• State management
• Common patterns and best practices

Development

Running with Debug Output

# Enable debug logging
RUST_LOG=debug cargo run --example button_demo_v2

Testing Individual Components

# Test a specific example
cargo build --release --example checkbox_demo_v2
./target/release/examples/checkbox_demo_v2

Known Limitations

• SwipeRefreshLayout Event Handling: Due to Termux:GUI plugin limitations, complex nested layouts inside SwipeRefreshLayout may cause connection drops. Keep layouts simple when using SwipeRefreshLayout.
• ScrollView Interaction: Nested ScrollViews require careful layout management to ensure proper touch event propagation.

Comparison with Python Bindings

Roadmap

• Complete widget library (12+ components)
• All layout types (7 layouts)
• WebView with JavaScript support
• Comprehensive documentation
• International ready (English)
• Published to crates.io
• Add more layout types (ConstraintLayout)
• Implement gesture recognizers
• Add animation support
• Create async/await API variant

What's New in 0.3.0

• ✨ Complete WebView implementation with JavaScript support
• ✨ All components fully documented in English
• ✨ Clean library structure (src/ contains only library code)
• ✨ 21 comprehensive examples
• ✨ Internationalization complete
• 🐛 Fixed layout viewport filling
• 📚 Enhanced documentation with usage guidelines

Resources

• Termux:GUI Official Repository
• Python Bindings
• Termux:GUI Protocol Documentation
• Project Structure
• WebView Documentation

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Version: 0.3.0
Status: Production Ready
Last Updated: 2024-10-05