docs: Add comprehensive README.md
- Project overview and features - Quick start example - Full widget list (35 widgets) - Unique features documentation (Macros, Lego Panels, Table) - Theme system - Performance utilities - Build instructions - Comparison with DVUI/Dear ImGui 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
f219e14f9c
commit
5a751782ea
1 changed files with 227 additions and 0 deletions
227
README.md
Normal file
227
README.md
Normal file
|
|
@ -0,0 +1,227 @@
|
||||||
|
# zcatgui
|
||||||
|
|
||||||
|
**Immediate Mode GUI Library for Zig** - Software-rendered, cross-platform, SSH-compatible.
|
||||||
|
|
||||||
|
[](https://ziglang.org/)
|
||||||
|
[](LICENSE)
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **Immediate Mode** - Explicit state, no callbacks, no threading issues
|
||||||
|
- **Software Rendering** - Works everywhere, including over SSH (X11 forwarding)
|
||||||
|
- **Macro System** - Record and replay user actions (unique feature)
|
||||||
|
- **35 Widgets** - From basic (Button, Label) to advanced (Table, Tree, Charts)
|
||||||
|
- **5 Themes** - Dark, Light, High Contrast, Nord, Dracula
|
||||||
|
- **Accessibility** - ARIA-like roles and states for screen readers
|
||||||
|
- **Zero Runtime Dependencies** - Only SDL2 for windowing
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
```zig
|
||||||
|
const zcatgui = @import("zcatgui");
|
||||||
|
|
||||||
|
pub fn main() !void {
|
||||||
|
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
|
||||||
|
const allocator = gpa.allocator();
|
||||||
|
|
||||||
|
var ctx = try zcatgui.Context.init(allocator);
|
||||||
|
defer ctx.deinit();
|
||||||
|
|
||||||
|
while (ctx.running) {
|
||||||
|
ctx.beginFrame();
|
||||||
|
|
||||||
|
if (zcatgui.button(&ctx, "Click me!")) {
|
||||||
|
// Handle click
|
||||||
|
}
|
||||||
|
|
||||||
|
ctx.endFrame();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Widgets (35 total)
|
||||||
|
|
||||||
|
### Basic
|
||||||
|
- **Label** - Static text with alignment options
|
||||||
|
- **Button** - Primary, normal, danger variants
|
||||||
|
- **Checkbox** - Boolean toggle
|
||||||
|
- **RadioButton** - Mutually exclusive selection
|
||||||
|
|
||||||
|
### Input
|
||||||
|
- **TextInput** - Single-line text entry with cursor
|
||||||
|
- **TextArea** - Multi-line text editor
|
||||||
|
- **NumberInput** - Numeric input with validation
|
||||||
|
- **Slider** - Horizontal/vertical value slider
|
||||||
|
- **AutoComplete** - ComboBox with fuzzy matching
|
||||||
|
|
||||||
|
### Selection
|
||||||
|
- **Select** - Dropdown selection
|
||||||
|
- **List** - Scrollable selectable list
|
||||||
|
- **Tree** - Hierarchical tree view
|
||||||
|
|
||||||
|
### Data
|
||||||
|
- **Table** - Editable with sorting, validation, dirty tracking
|
||||||
|
- **LineChart** - Line graphs with multiple series
|
||||||
|
- **BarChart** - Bar graphs with grouping
|
||||||
|
- **PieChart** - Pie/donut charts with labels
|
||||||
|
- **Sparkline** - Compact inline charts
|
||||||
|
|
||||||
|
### Layout
|
||||||
|
- **Panel** - Container with title, collapsible
|
||||||
|
- **HSplit/VSplit** - Draggable split panels
|
||||||
|
- **Tabs** - Tab container with keyboard navigation
|
||||||
|
- **ScrollArea** - Scrollable content region
|
||||||
|
- **Modal** - Dialog boxes (alert, confirm, input)
|
||||||
|
|
||||||
|
### Feedback
|
||||||
|
- **Progress** - Bar, circle, spinner with animations
|
||||||
|
- **Tooltip** - Hover tooltips with smart positioning
|
||||||
|
- **Toast** - Non-blocking notifications
|
||||||
|
- **Badge** - Status labels with variants
|
||||||
|
|
||||||
|
### Navigation
|
||||||
|
- **Menu** - Dropdown menus with submenus
|
||||||
|
- **ContextMenu** - Right-click menus
|
||||||
|
|
||||||
|
### Special
|
||||||
|
- **Image** - Image display with scaling
|
||||||
|
- **Icon** - Icon rendering
|
||||||
|
- **ColorPicker** - Color selection
|
||||||
|
- **Calendar** - Date selection
|
||||||
|
- **RichText** - Styled text rendering
|
||||||
|
|
||||||
|
## Unique Features
|
||||||
|
|
||||||
|
### Macro System
|
||||||
|
|
||||||
|
Record user actions as keyboard events and replay them:
|
||||||
|
|
||||||
|
```zig
|
||||||
|
var recorder = zcatgui.MacroRecorder.init(allocator);
|
||||||
|
|
||||||
|
// Start recording
|
||||||
|
recorder.start();
|
||||||
|
|
||||||
|
// ... user interacts with UI ...
|
||||||
|
|
||||||
|
// Stop and save
|
||||||
|
const events = recorder.stop();
|
||||||
|
try recorder.save("my_macro.macro");
|
||||||
|
|
||||||
|
// Later, replay
|
||||||
|
var player = zcatgui.MacroPlayer.init();
|
||||||
|
player.play(events, ctx.injectEvent, 50); // 50ms delay between events
|
||||||
|
```
|
||||||
|
|
||||||
|
### Lego Panels Architecture
|
||||||
|
|
||||||
|
Build complex UIs from reusable autonomous panels:
|
||||||
|
|
||||||
|
```zig
|
||||||
|
const panels = zcatgui.panels;
|
||||||
|
|
||||||
|
var search_panel = panels.SearchFilterPanel.init(allocator, config);
|
||||||
|
var data_panel = panels.DataTablePanel.init(allocator, table_config);
|
||||||
|
|
||||||
|
// Panels communicate via DataManager
|
||||||
|
var manager = panels.DataManager.init(allocator);
|
||||||
|
manager.register("search", &search_panel);
|
||||||
|
manager.register("data", &data_panel);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Table with Dirty Tracking
|
||||||
|
|
||||||
|
Track changes for database sync:
|
||||||
|
|
||||||
|
```zig
|
||||||
|
var table_state = zcatgui.widgets.TableState.init();
|
||||||
|
|
||||||
|
// After user edits
|
||||||
|
if (table_state.isDirty()) {
|
||||||
|
const changes = table_state.getDirtyRows();
|
||||||
|
for (changes) |row_idx| {
|
||||||
|
// Sync to database
|
||||||
|
}
|
||||||
|
table_state.clearDirty();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Themes
|
||||||
|
|
||||||
|
```zig
|
||||||
|
const theme = zcatgui.Style.ThemeManager.init();
|
||||||
|
|
||||||
|
// Switch themes at runtime
|
||||||
|
theme.setTheme(.dark);
|
||||||
|
theme.setTheme(.light);
|
||||||
|
theme.setTheme(.high_contrast);
|
||||||
|
theme.setTheme(.nord);
|
||||||
|
theme.setTheme(.dracula);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Performance
|
||||||
|
|
||||||
|
- **FrameArena** - O(1) per-frame allocator with automatic reset
|
||||||
|
- **ObjectPool** - Reuse frequently allocated objects
|
||||||
|
- **Virtual Scrolling** - Handle millions of items efficiently
|
||||||
|
- **Dirty Rectangles** - Partial redraws for efficiency
|
||||||
|
|
||||||
|
## Building
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Build library
|
||||||
|
zig build
|
||||||
|
|
||||||
|
# Run tests
|
||||||
|
zig build test
|
||||||
|
|
||||||
|
# Build examples
|
||||||
|
zig build hello
|
||||||
|
zig build widgets-demo
|
||||||
|
zig build table-demo
|
||||||
|
```
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Zig 0.15.2
|
||||||
|
- SDL2 (for windowing)
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
zcatgui/
|
||||||
|
├── src/
|
||||||
|
│ ├── zcatgui.zig # Main entry point
|
||||||
|
│ ├── core/ # Context, Layout, Style, Input
|
||||||
|
│ ├── widgets/ # All 35 widgets
|
||||||
|
│ ├── render/ # Software renderer, fonts, effects
|
||||||
|
│ ├── backend/ # SDL2 backend
|
||||||
|
│ ├── macro/ # Macro recording/playback
|
||||||
|
│ ├── panels/ # Lego Panels architecture
|
||||||
|
│ └── utils/ # Performance utilities
|
||||||
|
├── examples/ # Demo applications
|
||||||
|
└── docs/ # Documentation
|
||||||
|
```
|
||||||
|
|
||||||
|
## Comparison
|
||||||
|
|
||||||
|
| Feature | zcatgui | DVUI | Dear ImGui |
|
||||||
|
|---------|:-------:|:----:|:----------:|
|
||||||
|
| Language | Zig | Zig | C++ |
|
||||||
|
| Rendering | Software | Software/GPU | GPU |
|
||||||
|
| SSH Compatible | Yes | Partial | No |
|
||||||
|
| Macro System | Yes | No | No |
|
||||||
|
| Table Dirty Tracking | Yes | No | No |
|
||||||
|
| Widgets | 35 | 33 | 30+ |
|
||||||
|
|
||||||
|
## Related Projects
|
||||||
|
|
||||||
|
- **zcatui** - TUI (Terminal UI) library for Zig (sister project)
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT License - See [LICENSE](LICENSE) for details.
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Issues and pull requests welcome at the project repository.
|
||||||
Loading…
Reference in a new issue