`1a7afd5`

Add documentation for gartk toolkit

docs/README.md - Overview, quick start, crate summary
docs/core.md - Color, Rect, Theme, InputEvent types
docs/x11.md - Connection, Window, Monitor, EventLoop, Cursor
docs/render.md - Surface, Renderer, TextStyle, shape functions

Authored by mfwolffe <wolffemf@dukes.jmu.edu> 3 months ago

SHA: 1a7afd55384c4c4f12493e757f1b5e9ac308fbaf
Parents: 65eb650
Tree: 596653c

4 changed files

Status	File	+
A	`docs/README.md`	70
A	`docs/core.md`	184
A	`docs/render.md`	236
A	`docs/x11.md`	196

docs/README.mdadded

 +# gartk Documentation
++
 +gartk is a shared X11/Cairo toolkit for the gardesk suite. It provides common functionality used by garlaunch, garbar, gardm-greeter, and other gar components.
++
 +## Crates
++
 +| Crate | Purpose |
 +|-------|---------|
 +| `gartk-core` | Fundamental types: Color, Rect, Theme, InputEvent |
 +| `gartk-x11` | X11 connection, window management, monitors, event loop |
 +| `gartk-render` | Cairo/Pango rendering: surfaces, shapes, text |
++
 +## Quick Start
++
 +```toml
 +[dependencies]
 +gartk-core = { path = "../gartk/gartk-core" }
 +gartk-x11 = { path = "../gartk/gartk-x11" }
 +gartk-render = { path = "../gartk/gartk-render" }
 +```
++
 +### Minimal Window
++
 +```rust
 +use gartk_core::Theme;
 +use gartk_x11::{Connection, Window, WindowConfig, EventLoop};
 +use gartk_render::Renderer;
++
 +fn main() -> anyhow::Result<()> {
 +    let conn = Connection::connect(None)?;
 +    let window = Window::create(
 +        conn.clone(),
 +        WindowConfig::default()
 +            .title("Example")
 +            .size(400, 300),
 +    )?;
++
 +    window.show()?;
 +    window.focus()?;
++
 +    let theme = Theme::dark();
 +    let renderer = Renderer::with_theme(400, 300, theme)?;
 +    renderer.clear()?;
 +    renderer.flush();
++
 +    let event_loop = EventLoop::new(conn, Default::default());
 +    event_loop.run(|event| {
 +        // Handle events
 +        Ok(true) // Return false to exit
 +    })?;
++
 +    Ok(())
 +}
 +```
++
 +## Documentation
++
 +- [gartk-core](core.md) - Types and theming
 +- [gartk-x11](x11.md) - X11 integration
 +- [gartk-render](render.md) - Cairo/Pango rendering
++
 +## Usage in gardesk
++
 +gartk is used by:
++
 +- **garlaunch**: Popup window, text rendering, keyboard input
 +- **garbar**: Status bar rendering (shares patterns, not yet migrated)
 +- **gardm-greeter**: Login UI (shares patterns, not yet migrated)
++
 +The toolkit extracts common patterns from these components. Future gar components can use gartk directly.

docs/core.mdadded

 +# gartk-core
++
 +Fundamental types used throughout gartk.
++
 +## Color
++
 +RGBA color representation with parsing utilities.
++
 +```rust
 +use gartk_core::Color;
++
 +// Constructors
 +let c = Color::new(255, 128, 64, 255);
 +let c = Color::from_rgb(255, 128, 64);
 +let c = Color::from_hex("#ff8040").unwrap();
 +let c = Color::from_hex("#ff804080").unwrap(); // with alpha
++
 +// Named colors
 +let c = Color::WHITE;
 +let c = Color::BLACK;
 +let c = Color::TRANSPARENT;
 +let c = Color::RED;
 +let c = Color::GRAY;
++
 +// Methods
 +let (r, g, b, a) = c.to_rgba();
 +let (r, g, b, a) = c.to_rgba_f64(); // 0.0-1.0 range
 +let hex = c.to_hex();
 +let lighter = c.lighten(0.1);
 +let darker = c.darken(0.1);
 +let faded = c.with_alpha(128);
 +```
++
 +## Geometry
++
 +### Point
++
 +```rust
 +use gartk_core::Point;
++
 +let p = Point::new(10, 20);
 +let p = Point::origin(); // (0, 0)
 +```
++
 +### Size
++
 +```rust
 +use gartk_core::Size;
++
 +let s = Size::new(800, 600);
 +let area = s.area();
 +let is_empty = s.is_empty();
 +```
++
 +### Rect
++
 +```rust
 +use gartk_core::Rect;
++
 +let r = Rect::new(10, 20, 100, 50); // x, y, width, height
 +let r = Rect::from_points(Point::new(10, 20), Point::new(110, 70));
++
 +// Properties
 +r.x; r.y; r.width; r.height;
 +r.left(); r.right(); r.top(); r.bottom();
 +r.center();
 +r.size();
 +r.origin();
++
 +// Operations
 +r.contains(Point::new(50, 40));
 +r.intersects(&other);
 +r.intersection(&other);
 +r.union(&other);
 +r.inset(5); // shrink by 5 on all sides
 +r.offset(10, 20); // move
 +```
++
 +### Edges
++
 +Padding/margin representation.
++
 +```rust
 +use gartk_core::Edges;
++
 +let e = Edges::all(10);
 +let e = Edges::symmetric(10, 5); // horizontal, vertical
 +let e = Edges::new(5, 10, 5, 10); // top, right, bottom, left
 +```
++
 +## InputEvent
++
 +Abstraction over X11 input events.
++
 +```rust
 +use gartk_core::{InputEvent, Key, Modifiers};
++
 +match event {
 +    InputEvent::Key(key_event) => {
 +        if key_event.pressed {
 +            match key_event.key {
 +                Key::Return => { /* enter pressed */ }
 +                Key::Escape => { /* escape pressed */ }
 +                Key::Char(c) => { /* character input */ }
 +                _ => {}
 +            }
 +        }
 +        // Check modifiers
 +        if key_event.modifiers.ctrl { /* ctrl held */ }
 +        if key_event.modifiers.shift { /* shift held */ }
 +    }
 +    InputEvent::Mouse(mouse_event) => {
 +        // mouse_event.x, mouse_event.y, mouse_event.button
 +    }
 +    InputEvent::Scroll(scroll_event) => {
 +        // scroll_event.delta_x, scroll_event.delta_y
 +    }
 +    InputEvent::FocusIn | InputEvent::FocusOut => {}
 +    InputEvent::Close => { /* window close requested */ }
 +}
 +```
++
 +### Key Enum
++
 +Common keys: `Escape`, `Return`, `Tab`, `Backspace`, `Delete`, `Left`, `Right`, `Up`, `Down`, `Home`, `End`, `PageUp`, `PageDown`, `Space`, `Char(char)`, `F1`-`F12`, `Unknown(u8)`.
++
 +## Theme
++
 +UI theming with presets.
++
 +```rust
 +use gartk_core::Theme;
++
 +// Presets
 +let theme = Theme::dark();
 +let theme = Theme::light();
 +let theme = Theme::high_contrast();
++
 +// Access properties
 +theme.background;
 +theme.foreground;
 +theme.border;
 +theme.border_width;
 +theme.border_radius;
 +theme.font_family;
 +theme.font_size;
 +theme.padding;
 +theme.item_padding;
 +theme.item_spacing;
++
 +// Input field colors
 +theme.input_background;
 +theme.input_foreground;
 +theme.input_border;
 +theme.input_placeholder;
 +theme.input_cursor;
++
 +// Item/list colors
 +theme.item_background;
 +theme.item_foreground;
 +theme.item_selected_background;
 +theme.item_selected_foreground;
 +theme.item_hover_background;
 +theme.item_hover_foreground;
 +theme.item_description;
 +```
++
 +### ThemeBuilder
++
 +```rust
 +use gartk_core::{Theme, ThemeBuilder, Color};
++
 +let theme = Theme::builder()
 +    .background(Color::from_hex("#1a1a1a").unwrap())
 +    .foreground(Color::WHITE)
 +    .font_size(16.0)
 +    .padding(16)
 +    .build();
++
 +// Or modify existing
 +let theme = ThemeBuilder::from(Theme::dark())
 +    .font_family("JetBrains Mono")
 +    .build();
 +```

docs/render.mdadded

 +# gartk-render
++
 +Cairo/Pango rendering with surface management.
++
 +## Surface
++
 +Cairo ImageSurface wrapper.
++
 +```rust
 +use gartk_render::Surface;
 +use gartk_core::Color;
++
 +let mut surface = Surface::new(800, 600)?;
++
 +// Clear
 +surface.clear(Color::BLACK)?;
++
 +// Access Cairo context
 +let ctx = surface.context()?;
 +// ... custom Cairo drawing ...
++
 +// Resize
 +surface.resize(1024, 768)?;
++
 +// Get raw pixel data (ARGB32 format)
 +let data: &[u8] = surface.data()?;
++
 +// Dimensions
 +surface.size(); // Size
 +surface.width();
 +surface.height();
++
 +// Flush pending operations
 +surface.flush();
++
 +// Access underlying Cairo surface
 +surface.cairo_surface();
 +```
++
 +### DoubleBufferedSurface
++
 +For flicker-free rendering (swap buffers pattern).
++
 +```rust
 +use gartk_render::DoubleBufferedSurface;
++
 +let mut db = DoubleBufferedSurface::new(800, 600)?;
++
 +// Draw to back buffer
 +let ctx = db.back_context()?;
 +// ... draw ...
++
 +// Swap buffers
 +db.swap();
++
 +// Access front buffer data
 +let data = db.front_data()?;
 +```
++
 +## Renderer
++
 +High-level rendering API combining shapes and text.
++
 +```rust
 +use gartk_render::Renderer;
 +use gartk_core::{Theme, Color, Rect, Point};
++
 +// Create with theme
 +let theme = Theme::dark();
 +let renderer = Renderer::with_theme(800, 600, theme)?;
++
 +// Or without theme
 +let renderer = Renderer::new(800, 600)?;
++
 +// Clear
 +renderer.clear()?;  // Uses theme background
 +renderer.clear_color(Color::RED)?;
++
 +// Resize
 +renderer.resize(1024, 768)?;
++
 +// After drawing, flush
 +renderer.flush();
++
 +// Access internals
 +renderer.surface();
 +renderer.theme();
 +renderer.size();
 +renderer.context()?;  // Cairo context for custom drawing
 +```
++
 +### Shapes
++
 +```rust
 +use gartk_core::{Rect, Color};
++
 +let rect = Rect::new(10, 10, 100, 50);
++
 +// Rectangles
 +renderer.fill_rect(rect, Color::BLUE)?;
 +renderer.stroke_rect(rect, Color::WHITE, 2.0)?;
++
 +// Rounded rectangles
 +renderer.fill_rounded_rect(rect, 8.0, Color::BLUE)?;
 +renderer.stroke_rounded_rect(rect, 8.0, Color::WHITE, 2.0)?;
++
 +// Circles
 +renderer.fill_circle(50.0, 50.0, 20.0, Color::RED)?;
++
 +// Lines
 +renderer.line(0.0, 0.0, 100.0, 100.0, Color::WHITE, 1.0)?;
 +```
++
 +### Text
++
 +```rust
 +use gartk_render::TextStyle;
 +use gartk_core::Color;
++
 +let style = TextStyle::new()
 +    .font_family("sans-serif")
 +    .font_size(14.0)
 +    .color(Color::WHITE);
++
 +// Draw text at position
 +renderer.text("Hello", 10.0, 20.0, &style)?;
++
 +// Draw with theme defaults
 +renderer.text_default("Hello", 10.0, 20.0, Color::WHITE)?;
++
 +// Draw in rectangle (auto-centers vertically)
 +renderer.text_in_rect("Hello", rect, &style)?;
++
 +// Draw centered at point
 +renderer.text_centered("Hello", Point::new(100, 100), &style)?;
++
 +// Measure text
 +let size = renderer.measure_text("Hello", &style)?;
 +```
++
 +## TextStyle
++
 +Text rendering configuration.
++
 +```rust
 +use gartk_render::{TextStyle, TextAlign};
 +use gartk_core::Color;
++
 +let style = TextStyle::new()
 +    .font_family("JetBrains Mono")
 +    .font_size(12.0)
 +    .color(Color::WHITE)
 +    .align(TextAlign::Left)    // Left, Center, Right
 +    .ellipsize(true)           // Add "..." when truncated
 +    .wrap(true)                // Word wrap
 +    .max_width(200);           // Width constraint (required for ellipsize/wrap)
 +```
++
 +## TextRenderer
++
 +Lower-level Pango text rendering (used internally by Renderer).
++
 +```rust
 +use gartk_render::TextRenderer;
++
 +let text_renderer = TextRenderer::new();
++
 +// Or with default style
 +let text_renderer = TextRenderer::with_style(style);
++
 +// Measure
 +let size = text_renderer.measure(&ctx, "Hello", &style);
++
 +// Draw
 +text_renderer.draw(&ctx, "Hello", 10.0, 20.0, &style);
 +text_renderer.draw_in_rect(&ctx, "Hello", rect, &style);
 +text_renderer.draw_centered(&ctx, "Hello", center_point, &style);
 +```
++
 +## Low-Level Shape Functions
++
 +Direct Cairo drawing (requires Cairo context).
++
 +```rust
 +use gartk_render::{fill_rect, stroke_rect, fill_rounded_rect, rounded_rect_path};
 +use gartk_render::{fill_circle, stroke_circle, circle_path};
 +use gartk_render::{line, hline, vline, set_color};
++
 +let ctx = surface.context()?;
++
 +// Color
 +set_color(&ctx, Color::RED);
++
 +// Paths (for custom operations)
 +rect_path(&ctx, rect);
 +rounded_rect_path(&ctx, rect, radius);
 +circle_path(&ctx, cx, cy, radius);
++
 +// Fill/stroke
 +fill_rect(&ctx, rect, color);
 +stroke_rect(&ctx, rect, color, line_width);
 +fill_rounded_rect(&ctx, rect, radius, color);
 +stroke_rounded_rect(&ctx, rect, radius, color, line_width);
 +fill_circle(&ctx, cx, cy, radius, color);
 +stroke_circle(&ctx, cx, cy, radius, color, line_width);
++
 +// Lines
 +line(&ctx, x1, y1, x2, y2, color, line_width);
 +hline(&ctx, x1, x2, y, color, line_width);
 +vline(&ctx, x, y1, y2, color, line_width);
 +```
++
 +## Font Parsing
++
 +Parse font specification strings.
++
 +```rust
 +use gartk_render::parse_font_spec;
++
 +// Pango-style
 +let (family, size) = parse_font_spec("Sans 12")?;
 +let (family, size) = parse_font_spec("JetBrains Mono 11")?;
++
 +// Polybar-style
 +let (family, size) = parse_font_spec("Monospace:size=14")?;
 +```
++
 +## Re-exports
++
 +For direct access to underlying libraries:
++
 +```rust
 +use gartk_render::cairo;
 +use gartk_render::pango;
 +use gartk_render::pangocairo;
 +```

docs/x11.mdadded

 +# gartk-x11
++
 +X11 integration using x11rb with RustConnection.
++
 +## Connection
++
 +Wrapper around x11rb connection with atom caching.
++
 +```rust
 +use gartk_x11::Connection;
++
 +let conn = Connection::connect(None)?; // Use $DISPLAY
 +let conn = Connection::connect(Some(":1"))?; // Specific display
++
 +// Access underlying connection
 +conn.inner(); // &RustConnection
 +conn.screen_num();
 +conn.default_screen(); // &Screen
++
 +// Utilities
 +conn.generate_id()?;
 +conn.flush()?;
 +conn.sync()?;
++
 +// Atoms (cached)
 +conn.atoms(); // &Atoms
 +```
++
 +### Atoms
++
 +Pre-interned X11 atoms for EWMH, ICCCM, and common properties.
++
 +```rust
 +let atoms = conn.atoms();
++
 +// Window types
 +atoms.NET_WM_WINDOW_TYPE;
 +atoms.NET_WM_WINDOW_TYPE_NORMAL;
 +atoms.NET_WM_WINDOW_TYPE_DIALOG;
 +atoms.NET_WM_WINDOW_TYPE_DOCK;
 +atoms.NET_WM_WINDOW_TYPE_POPUP_MENU;
++
 +// State
 +atoms.NET_WM_STATE;
 +atoms.NET_WM_STATE_ABOVE;
 +atoms.NET_WM_STATE_FULLSCREEN;
 +atoms.NET_WM_STATE_STICKY;
++
 +// Properties
 +atoms.NET_WM_NAME;
 +atoms.NET_WM_PID;
 +atoms.WM_NAME;
 +atoms.WM_CLASS;
 +atoms.WM_PROTOCOLS;
 +atoms.WM_DELETE_WINDOW;
++
 +// Selections
 +atoms.CLIPBOARD;
 +atoms.PRIMARY;
 +atoms.UTF8_STRING;
 +```
++
 +## Window
++
 +X11 window creation and management.
++
 +```rust
 +use gartk_x11::{Window, WindowConfig, WindowType};
++
 +let window = Window::create(
 +    conn.clone(),
 +    WindowConfig::default()
 +        .title("My Window")
 +        .class("myapp")
 +        .position(100, 100)
 +        .size(800, 600)
 +        .window_type(WindowType::Normal)
 +        .transparent(false)
 +        .override_redirect(false),
 +)?;
++
 +// Presets
 +WindowConfig::popup();    // override_redirect, above, skip taskbar
 +WindowConfig::dock();     // dock type, struts
 +WindowConfig::fullscreen();
 +```
++
 +### Window Methods
++
 +```rust
 +// Visibility
 +window.show()?;
 +window.hide()?;
++
 +// Focus and input
 +window.focus()?;
 +window.grab_keyboard()?;
 +window.ungrab_keyboard()?;
++
 +// Properties
 +window.set_title("New Title")?;
 +window.id(); // XWindow
 +window.size(); // Size
 +window.depth(); // u8
++
 +// Connection access
 +window.connection(); // &Connection
 +```
++
 +### WindowType
++
 +`Normal`, `Dialog`, `Utility`, `Toolbar`, `Dock`, `Desktop`, `Splash`, `Popup`, `Dropdown`, `Tooltip`, `Notification`, `Combo`, `Dnd`.
++
 +## Monitor
++
 +RandR multi-monitor detection.
++
 +```rust
 +use gartk_x11::{detect_monitors, primary_monitor, monitor_at_point};
 +use gartk_core::Point;
++
 +// Get all monitors
 +let monitors = detect_monitors(&conn)?;
++
 +// Primary monitor
 +let primary = primary_monitor(&conn)?;
++
 +// Monitor at specific point
 +let monitor = monitor_at_point(&conn, Point::new(100, 100))?;
++
 +// Monitor properties
 +monitor.name;       // String ("eDP-1", "HDMI-1", etc.)
 +monitor.rect;       // Rect (position and size)
 +monitor.is_primary; // bool
 +```
++
 +## EventLoop
++
 +Blocking event loop with frame limiting.
++
 +```rust
 +use gartk_x11::{EventLoop, EventLoopConfig};
 +use gartk_core::InputEvent;
++
 +let config = EventLoopConfig {
 +    target_fps: 60,
 +};
++
 +let event_loop = EventLoop::new(conn, config);
++
 +event_loop.run(|event: InputEvent| {
 +    match event {
 +        InputEvent::Key(key_event) => { /* ... */ }
 +        InputEvent::Close => return Ok(false), // Exit loop
 +        _ => {}
 +    }
 +    Ok(true) // Continue running
 +})?;
 +```
++
 +## Keyboard
++
 +Keycode translation (evdev-based).
++
 +```rust
 +use gartk_x11::{key_from_keycode, key_event_from_x11, modifiers_from_x11};
 +use gartk_core::Key;
++
 +// Low-level
 +let key = key_from_keycode(keycode);
++
 +// From X11 event
 +let key_event = key_event_from_x11(&x11_key_event, pressed);
 +let modifiers = modifiers_from_x11(state);
 +```
++
 +## Cursor
++
 +Cursor shape management.
++
 +```rust
 +use gartk_x11::{CursorManager, CursorShape};
++
 +let mut cursor_mgr = CursorManager::new(conn.clone())?;
++
 +// Set cursor for window
 +cursor_mgr.set_cursor(window.id(), CursorShape::Default)?;
 +cursor_mgr.set_cursor(window.id(), CursorShape::Pointer)?;
 +cursor_mgr.set_cursor(window.id(), CursorShape::Text)?;
 +cursor_mgr.set_cursor(window.id(), CursorShape::Wait)?;
 +cursor_mgr.set_cursor(window.id(), CursorShape::Move)?;
 +```
++
 +### CursorShape
++
 +`Default`, `Pointer`, `Text`, `Wait`, `Crosshair`, `Move`, `NotAllowed`, `ResizeNS`, `ResizeEW`, `ResizeNESW`, `ResizeNWSE`, `Grab`, `Grabbing`.