gartk

gartk-core

Core types used throughout gartk. These are platform-independent abstractions that can be shared across different backends.

use gartk_core::{
    Color, ColorError,
    Point, Size, Rect, Edges,
    InputEvent, Key, KeyEvent, Modifiers,
    MouseButton, MouseEvent, ScrollEvent,
    Theme, ThemeBuilder,
};

Color

RGBA color with components in 0.0-1.0 range. Supports parsing from multiple formats and color space conversions.

Parsing

// Various parsing methods
let c1 = Color::from_hex("#ff6600")?;
let c2 = Color::from_hex("#f60")?;      // Short form
let c3 = Color::from_hex("#ff660080")?; // With alpha
let c4 = Color::from_rgb_str("rgb(255, 102, 0)")?;
let c5 = Color::from_rgb_str("rgba(255, 102, 0, 0.5)")?;
let c6 = Color::from_name("red")?;

// Auto-detect format
let c7 = Color::parse("#ff6600")?;
let c8 = Color::parse("rgb(255, 0, 0)")?;
let c9 = Color::parse("blue")?;

HSV Conversion

Convert between RGB and HSV color spaces for intuitive color manipulation:

// RGB to HSV
let color = Color::from_hex("#ff6600")?;
let (hue, sat, val) = color.to_hsv();
// hue: 0-360, sat: 0-1, val: 0-1

// HSV to RGB
let orange = Color::from_hsv(30.0, 1.0, 1.0);
let orange_alpha = Color::from_hsva(30.0, 1.0, 1.0, 0.5);

// Modify individual components
let shifted = color.with_hue(180.0);    // Shift hue
let muted = color.with_saturation(0.5); // Reduce saturation
let darker = color.with_value(0.5);     // Reduce brightness

Manipulation

let base = Color::from_hex("#3498db")?;

// Adjust alpha
let translucent = base.with_alpha(0.5);

// Lighten/darken
let lighter = base.lighten(0.2); // 20% lighter
let darker = base.darken(0.2);   // 20% darker

// Convert for X11
let argb = base.to_argb_u32(); // For window background
let hex = base.to_hex();       // "#3498db"

Color Constants

Geometry Types

Point

2D point with i32 coordinates:

let p = Point::new(100, 200);
let origin = Point::ORIGIN; // (0, 0)

// Access
let x = p.x;
let y = p.y;

Size

2D size with u32 dimensions:

let s = Size::new(800, 600);

// Access
let w = s.width;
let h = s.height;

// Check if empty
if s.is_empty() { /* ... */ }

Rect

Rectangle with position and size:

let r = Rect::new(10, 20, 100, 50); // x, y, width, height
let r2 = Rect::from_size(Size::new(100, 50)); // At origin

// Bounds
let left = r.left();    // x
let top = r.top();      // y
let right = r.right();  // x + width
let bottom = r.bottom();// y + height

// Position and size
let pos = r.position(); // Point
let size = r.size();    // Size

// Hit testing
if r.contains_point(Point::new(50, 30)) {
    // Point is inside rectangle
}

// Intersection
if r.intersects(&other_rect) {
    let overlap = r.intersection(&other_rect);
}

Edges

Edge values for padding/margin:

let edges = Edges::new(10, 20, 10, 20); // top, right, bottom, left
let uniform = Edges::all(8);
let zero = Edges::ZERO;

// Access individual edges
let top = edges.top;
let horizontal = edges.left + edges.right;

Input Events

InputEvent

Platform-agnostic input event abstraction:

KeyEvent

match event {
    InputEvent::Key(e) if e.pressed => {
        match e.key {
            Key::Escape => quit(),
            Key::Return => submit(),
            Key::Char(c) => input.push(c),
            Key::Backspace => input.pop(),
            Key::Up => select_prev(),
            Key::Down => select_next(),
            _ => {}
        }

        // Check modifiers
        if e.modifiers.ctrl {
            // Ctrl+key
        }
    }
    _ => {}
}

MouseEvent

match event {
    InputEvent::MousePress(e) => {
        let pos = e.position;
        if let Some(MouseButton::Left) = e.button {
            handle_click(pos);
        }
    }
    InputEvent::MouseMove(e) => {
        update_hover(e.position);
    }
    _ => {}
}

ScrollEvent

match event {
    InputEvent::Scroll(e) => {
        // delta_y: -1 for up, 1 for down
        // delta_x: -1 for left, 1 for right
        scroll_offset += e.delta_y * 20; // 20px per scroll step
    }
    _ => {}
}

gartk-render

Cairo/Pango rendering layer providing surfaces, shape primitives, and text layout.

use gartk_render::{
    Surface, DoubleBufferedSurface,
    Renderer,
    TextRenderer, TextStyle, TextAlign,
    fill_rect, fill_rounded_rect, stroke_rect,
    fill_circle, line, set_color,
};

// Re-exports for direct Cairo access
use gartk_render::{cairo, pango, pangocairo};

Surface

Creation

// Create an image surface
let surface = Surface::new(800, 600)?;

// Get Cairo context for drawing
let ctx = surface.context()?;

// Clear with a color
surface.clear(Color::from_hex("#1e1e2e")?)?;

Resizing

// Handle window resize
match event {
    InputEvent::Resize { width, height } => {
        surface.resize(width, height)?;
    }
    _ => {}
}

Double Buffering

// For flicker-free rendering
use gartk_render::copy_surface_to_window;

// After drawing, copy to window
surface.flush();
copy_surface_to_window(&surface, &window)?;

Renderer

High-level renderer combining surface, shapes, and text:

Creation

// Basic renderer
let renderer = Renderer::new(800, 600)?;

// With theme (recommended)
let theme = Theme::dark();
let renderer = Renderer::with_theme(800, 600, theme)?;

// Clear with theme background
renderer.clear()?;

// Or specific color
renderer.clear_color(Color::BLACK)?;

Drawing Shapes

// Via Renderer
renderer.fill_rect(Rect::new(10, 10, 100, 50), Color::BLUE)?;
renderer.fill_rounded_rect(Rect::new(10, 70, 100, 50), 8.0, Color::GREEN)?;
renderer.stroke_rect(Rect::new(10, 130, 100, 50), Color::RED, 2.0)?;
renderer.fill_circle(160.0, 35.0, 20.0, Color::YELLOW)?;
renderer.line(10.0, 200.0, 110.0, 200.0, Color::WHITE, 2.0)?;

// Via shape functions with context
let ctx = renderer.context()?;
fill_rounded_rect(&ctx, Rect::new(0, 0, 100, 30), 4.0, Color::BLUE);
stroke_circle(&ctx, 50.0, 50.0, 25.0, Color::WHITE, 2.0);

Drawing Text

// Simple text with default style
renderer.text_default("Hello!", 10.0, 50.0, Color::WHITE)?;

// Custom style
let style = TextStyle::new()
    .font_family("JetBrains Mono")
    .font_size(16.0)
    .color(Color::from_hex("#cdd6f4")?)
    .bold(true);

renderer.text("Styled text", 10.0, 80.0, &style)?;

// Text in rectangle (with alignment)
let rect = Rect::new(10, 100, 200, 30);
let centered_style = style.align(TextAlign::Center);
renderer.text_in_rect("Centered", rect, &centered_style)?;

// Centered at point
renderer.text_centered("Center", Point::new(100, 150), &style)?;

// Measure text
let size = renderer.measure_text("Some text", &style)?;

Text Styling

let style = TextStyle::new()
    .font_family("sans-serif")  // Font family
    .font_size(14.0)            // Size in points
    .color(Color::WHITE)        // Text color
    .bold(true)                 // Bold weight
    .italic(true)               // Italic style
    .underline(true)            // Underline
    .strikethrough(true)        // Strikethrough
    .align(TextAlign::Left)     // Left, Center, Right
    .line_height(1.5);          // Line height multiplier

gartk-x11

X11 integration layer providing window management, event handling, and system integration.

use gartk_x11::{
    Connection,
    Window, WindowConfig, WindowType,
    EventLoop, EventLoopConfig,
    Monitor, detect_monitors, primary_monitor,
    CursorManager, CursorShape,
    ClipboardManager, ClipboardContent,
};

Connection

// Connect to default display
let conn = Connection::connect(None)?;

// Connect to specific display
let conn = Connection::connect(Some(":1"))?;

// Get screen info
let width = conn.screen_width();
let height = conn.screen_height();
let root = conn.root();
let depth = conn.default_depth();

// Check for ARGB visual (transparency)
if let Some(visual) = conn.find_argb_visual() {
    // Transparency supported
}

// Flush pending requests
conn.flush()?;

// Poll for events
while let Some(event) = conn.poll_event()? {
    // Handle event
}

Window

Configuration

// Builder pattern
let window = Window::create(
    conn.clone(),
    WindowConfig::new()
        .title("My App")
        .class("my-app")
        .size(800, 600)
        .position(100, 100)      // Or omit for centered
        .background(0xff1e1e2e) // ARGB
        .transparent(true)       // ARGB visual
        .border_width(0),
)?;

// Presets
let popup = WindowConfig::popup();  // override_redirect + PopupMenu
let dialog = WindowConfig::dialog(); // Dialog type

// Modal dialog
let dialog = Window::create(
    conn.clone(),
    WindowConfig::dialog()
        .title("Confirm")
        .size(300, 150)
        .parent_window(main_window.id())
        .modal(true),
)?;

Window Types

Window Methods

Event Loop

let config = EventLoopConfig {
    fps: 60,                    // Target frame rate
    continuous_redraw: false,   // Redraw only on expose
};

let mut event_loop = EventLoop::new(&window, config)?;

event_loop.run(|ev_loop, event| {
    match event {
        InputEvent::Expose => {
            ev_loop.request_redraw();
        }
        InputEvent::Idle => {
            if ev_loop.needs_redraw() {
                // Draw frame
                render()?;
                ev_loop.redraw_done();
            }
        }
        InputEvent::CloseRequested => {
            return Ok(false); // Exit loop
        }
        _ => {}
    }
    Ok(true) // Continue
})?;

Monitors

// Detect all monitors via XRandR
let monitors = detect_monitors(&conn)?;
for mon in &monitors {
    println!("{}: {}x{}+{}+{} {}",
        mon.name, mon.width, mon.height,
        mon.x, mon.y,
        if mon.primary { "(primary)" } else { "" }
    );
}

// Get primary monitor
let primary = primary_monitor(&conn)?;

// Find monitor at point
let mon = monitor_at_point(&conn, 500, 300)?;

// Find monitor at pointer
let mon = monitor_at_pointer(&conn)?;

Cursors

let cursor_mgr = CursorManager::new(&conn)?;

// Set cursor shape
cursor_mgr.set_cursor(&window, CursorShape::Arrow)?;
cursor_mgr.set_cursor(&window, CursorShape::IBeam)?;
cursor_mgr.set_cursor(&window, CursorShape::Crosshair)?;
cursor_mgr.set_cursor(&window, CursorShape::Hand)?;
cursor_mgr.set_cursor(&window, CursorShape::ResizeNS)?;
cursor_mgr.set_cursor(&window, CursorShape::ResizeEW)?;

Clipboard

let clipboard = ClipboardManager::new(&conn)?;

// Set clipboard content
clipboard.set_text("Hello clipboard")?;

// For file paths (drag-and-drop, file managers)
clipboard.set_uris(&["/path/to/file.txt"])?;