Blinc Documentation

The Blinc Example Gallery provides a comprehensive suite of demos showcasing various subsystems. Use these as references for implementing specific features:

Core UI & Layout

• blinc_cn Components: A scrollable grid of all available blinc_cn components.
• Table Builder API: Declarative table creation via the TableBuilder API.
• Text Input Widgets: Ready-to-use text input and text area elements using the layout API.
• Scroll Container: Scroll widget with opt-in webkit-style behavior.
• Overlay System: Infrastructure for modals, dialogs, and popovers.
• Notch Menu Bar: macOS-style menu bar with notched dropdowns.

Graphics & Shaders

• @flow Shader System: Demonstrates the DAG-based shader system, including semantic step/chain/use patterns.
• Fluid Surface: Combines @flow GPU shaders with pointer-query CSS-driven interaction.
• Canvas Element: Custom GPU drawing using the canvas element.
• GPU Pass End-to-End: Demonstrates the DrawContext::run_gpu_pass pattern for custom GPU logic.
• Layer Effects: GPU-accelerated layer effects.
• 3D Mesh Rendering: Rendering glTF models (e.g., DamagedHelmet) using the SceneKit3D renderer.

Animation & Interaction

• Stateful API: Timeline-based animations and signal-bound modifiers.
• Sortable: Drag-based interactions using FSM-driven stateful containers.
• Keyframe Animation: Using the canvas element for keyframe-based motion.
• Pointer Query: CSS-driven continuous pointer query system.

Specialized Elements

• Rich Text Editor: Full editable editor with cursor, selection, and inline formatting.
• Markdown Editor: Split-view markdown editor.
• Code Element: Read-only code display and editable code editors.
• Video Player: video_player widget integrated with blinc_media::VideoPlayer.

For performance-heavy apps, use .lazy() to defer image decoding until the image intersects the viewport. This prevents unnecessary GPU uploads and decoding for off-screen content.

Loading Strategies:

• Eager (default): Load and decode immediately.
• Lazy: Defer load until visible.

Placeholder Types:

• None: Empty until bitmap arrives.
• Color(color): Solid color background via .placeholder_color(color).
• Brush(brush): Gradients or other brushes via .placeholder_brush(brush).
• Image(url): A low-res thumbnail or blur-hash via .placeholder_image(url). These are eagerly preloaded.
• Skeleton: An animated shimmer band via .skeleton().

Fade-in Behavior: Images fade in once the texture is ready. Use .fade_in(Duration) to set the duration, or .no_fade() to make the image pop in instantly.

use blinc_layout::prelude::*;
use std::time::Duration;

// Example: Skeleton shimmer with custom fade
img("photo.jpg")
    .lazy()
    .skeleton()
    .fade_in(Duration::from_millis(250))
    .w(300.0)
    .h(200.0)

QML provides a declarative approach focused on property bindings and state machines:

• Property Bindings: Declarative reactive connections that automatically update when dependencies change.
• Signal/Slot System: A pattern for first-class event handling.
• Built-in State Machine: Uses Harel's Statecharts (SCXML) for managing UI states.
• Transitions: Seamlessly integrates animations with state changes.
• Syntax: Uses a highly readable JSON-like object literal syntax.

Rectangle {
    id: root
    width: parent.width * 0.8  // Reactive binding
    height: calculateHeight()
    
    states: [
        State { name: "pressed"; PropertyChanges { target: root; color: "red" } },
        State { name: "released"; PropertyChanges { target: root; color: "blue" } }
    ]
    
    transitions: [
        Transition { from: "released"; to: "pressed"; NumberAnimation { property: "opacity" } }
    ]
}

The Blinc node editor is built on several core architectural principles that allow for extensible and type-safe graph editing:

• Metadata-driven Node Rendering: Nodes are not hardcoded. Instead, they render based on declarative NodeTemplates. To add a new node type to the editor, you simply define and provide a new template.
• Generic Port Compatibility: The editor is generic over the PortKind. Users implement the PortKind trait for their own custom port-type enums. Compatibility between ports (e.g., connecting an output to an input) is delegated to the implementation of PortKind::compatible_with.
• Theme-aware UI: The editor's chrome (background, header, borders, badges) is driven by ThemeState. Switching theme bundles automatically updates visual tokens such as squircle profiles, shadows, typography, and spacing.
• Canvas Interactions: The editor inherits pan, zoom, and selection capabilities from blinc_canvas_kit.
• Grouping: Nodes can be wrapped in groups, which support status badges in the header.

Blinc recommends a CSS-First approach for all styling and layout. This provides consistency, automatic handling of hover/focus/disabled states, and seamless theme integration via CSS variables.

Best Practices:

• Prefer CSS for layout, colors, and states (hover, active, etc.).
• Use Builder Methods (e.g., .bg(), .w()) only for truly dynamic runtime values computed from signals.
• Avoid direct builder calls when a CSS class or ID selector can achieve the same result.

Specificity Order (Low to High):

1. CSS stylesheets (ctx.add_css()) — Lowest priority
2. css! / style! macros (inline styles)
3. Builder methods (e.g., .bg()) — Highest priority, overrides CSS

// Example of the preferred pattern
let mut css_loaded = false;

WindowedApp::run(config, move |ctx| {
    if !css_loaded {
        ctx.add_css(r"#my-card { background: #1e293b; }");
        css_loaded = true;
    }
    build_ui(ctx)
});