DOCSEARCHbyAlgolia
Submit Docs

gogpu/ui Documentation

repository·main·Indexed 18 days ago

https://github.com/gogpu/ui

An enterprise-grade, zero-CGO GUI toolkit for Go designed for high-performance applications like IDEs and design tools. It features WebGPU hardware-accelerated rendering (supporting Vulkan, DX12, Metal, GLES, and Software backends), a reactive 'Signals' state management model, and a layout engine combining Flexbox and Grid. The toolkit includes a comprehensive set of interactive widgets, support for multiple design systems (Material 3, Fluent, Cupertino), built-in accessibility (ARIA roles), and offscreen rendering capabilities.

Tokens
29.8K
Snippets
65
Records
104
Agent score
64%

What's inside gogpu/ui

  1. Overview of gogpu/ui features

    main

    gogpu/ui is an enterprise-grade GUI toolkit for Go designed for high-performance applications like IDEs, design tools, and CAD software.

    Key technical features include:

    • Zero CGO: Pure Go implementation.
    • WebGPU Rendering: Supports Vulkan, DX12, Metal, GLES, and Software backends.
    • Reactive State: Uses a 'Signals' model (push-pull, zero glitch).
    • Layout Engine: Combines Flexbox and Grid with per-widget caching.
    • Accessibility: Built-in support for 35+ ARIA roles.
    • Design Systems: Supports M3 (Material Design 3), DevTools, Fluent, and Cupertino.

  2. Overview of gogpu/ui packages and capabilities

    main

    The gogpu/ui project is a comprehensive UI framework organized into several developmental phases. Developers can leverage packages ranging from core geometry and event handling to high-level interactive widgets and specialized themes.

    Core Capabilities

    • Core (Phase 0): Provides fundamental building blocks like geometry (Point, Size, Rect), event (Mouse, Key, Wheel, Focus), and the widget lifecycle (mount/unmount).
    • MVP (Phase 1): Introduces reactive state (signals), accessibility (a11y), and basic primitives (Box, Text, Image).
    • Extensibility (Phase 1.5): Offers a public layout API, registry for third-party widgets, and a theme system.
    • Interactive Widgets (Phase 2): Includes a Component Development Kit (cdk) and standard UI controls like button, checkbox, radio, textfield, slider, dialog, and dropdown.
    • Advanced Widgets (Phase 3 & 4): Features complex components such as scrollview, listview (virtualized), gridview, tabview, animation engines, treeview, datatable, and docking systems.

    Specialized Features

    • Theming: Supports material3 (Material Design 3), fluent (Microsoft), and cupertino (Apple HIG).
    • Headless Rendering: The offscreen package allows for CPU-only *image.RGBA output without requiring a GPU or windowing system.
    • Testing: The uitest package provides MockCanvas, MockContext, and event factories for widget testing.

  3. Overview of gogpu/ui extension points

    main

    gogpu/ui is designed to be extensible through four primary mechanisms. All extensions typically use the init() auto-registration pattern, allowing them to be integrated into a project simply by importing the package with a blank identifier (_).

    ExtensionPackagePurpose
    Widgetsregistry/Custom UI components
    Themestheme/Visual styling
    Layoutslayout/Custom positioning algorithms
    Pluginsplugin/Bundles widgets, themes, and layouts together

  4. Core design principles and constraints

    main

    When building with gogpu/ui, keep the following architectural constraints in mind:

    • No Webview: The toolkit uses native GPU rendering, not HTML/CSS/JS.
    • No CGO: The project is pure Go and compiles on any platform supported by Go.
    • No Runtime Code Generation: All types are resolved at compile time.
    • No Global State: The toolkit is instance-based (e.g., Scheduler, FocusManager, App).
    • No Implicit Side Effects: Components follow an explicit lifecycle (Mount/Unmount).
    • No Backend Abstraction in ui: Rendering always flows from gg to wgpu (ADR-009).

  5. How to extend functionality via Interface Extension

    main

    To add optional capabilities to existing components (like widgets) without breaking existing implementations, use Interface Extension.

    Define a new interface that embeds the core interface. Users can then use type assertions to check if a component supports the new capability. This prevents the need to add new required methods to the base interface, which would break all existing implementations.

    // v0.1.0 — Core interface
type Widget interface {
    Layout(ctx *LayoutContext) Size
    Paint(ctx *PaintContext)
}

// v0.3.0 — Extended capability (NO breaking change)
type Focusable interface {
    Widget
    Focus()
    Blur()
}

// Usage via type assertion:
if f, ok := widget.(Focusable); ok {
    f.Focus()
}

  6. Handle user input with the Event system

    main

    Events are dispatched from the root widget down through the tree. A widget's Event method returns true to consume the event and stop further propagation. There is no explicit capture/bubble phase; widgets are responsible for checking bounds and delegating to children.

    Supported Event Types:

    • TypeMouse: MouseEvent (includes MousePress, MouseRelease, MouseMove, MouseEnter, MouseLeave, MouseDrag, MouseDoubleClick).
    • TypeKey: KeyEvent (includes KeyPress, KeyRelease, KeyRepeat).
    • TypeFocus: FocusEvent (FocusGained, FocusLost).
    • TypeWheel: WheelEvent (scroll deltas).

    Modifiers: Use the Modifiers type to check for keys like ModShift, ModCtrl, ModAlt, and ModSuper via methods like Has(), IsShift(), or IsCtrl().

    type Event interface {
    Type() Type
    Time() time.Time
    Handled() bool
    SetHandled()
    Modifiers() Modifiers
}

  7. Implement the Painter interface for custom button styling

    main

    The button uses a Painter interface to separate behavior from visual rendering. To create a custom design system, implement the Painter interface to define how the button is drawn on a widget.Canvas based on its current PaintState.

    Painter Interface:

    type Painter interface {
    PaintButton(canvas widget.Canvas, state PaintState)
}

    If no painter is provided to button.New, the widget defaults to DefaultPainter (a minimal gray style).

    // Example implementation in a theme
type ButtonPainter struct {
    Theme *Theme
}

func (p ButtonPainter) PaintButton(canvas widget.Canvas, state PaintState) {
    // Custom drawing logic here
}

  8. Use internal and experimental packages for stability

    main

    The project manages API stability through package boundaries:

    • Public API: Located in standard packages (e.g., github.com/gogpu/ui/widgets). These are intended to be stable.
    • Internal Packages: Located under internal/ (e.g., github.com/gogpu/ui/internal/render). These contain implementation details that can change freely; users are not permitted to import them.
    • Experimental Packages: Located under experimental/ (e.g., github.com/gogpu/ui/experimental/docking). These contain unstable features where the user accepts the risk of breaking changes.

  9. Understand the gogpu/ui Render Pipeline

    main

    gogpu/ui uses a retained-mode render pipeline inspired by Flutter, Chrome, and Qt6. The core mechanism relies on RepaintBoundary widgets, each of which owns an offscreen GPU texture.

    When a widget changes, only its specific boundary's texture is re-rendered, while all other parts of the UI are reused from the previous frame. This approach minimizes GPU work by avoiding full-screen redraws for local changes (e.g., hovering over a button or animating a small spinner).

  10. Understand the gogpu/ui 3-Layer Architecture

    main

    The gogpu/ui toolkit is organized into a three-layer hierarchy designed to separate behavior, styling, and low-level primitives. This structure allows developers to build complex user applications by composing high-level widgets while maintaining control over the underlying foundation.

    Layer 1: Foundation

    Provides the core building blocks for all UI elements. This includes:

    • widget/: Core types like Widget, WidgetBase, Context, and Canvas, along with lifecycle and focus management.
    • geometry/: Basic spatial types such as Point, Size, Rect, Constraints, and Insets.
    • Infrastructure: Essential services like layout (Flex, Stack, Grid), state (Signals, Binding), focus management, animation, a11y (accessibility), and dnd (drag and drop).

    Layer 2: Component Development Kit (CDK)

    The cdk/ package provides intermediate abstractions (e.g., Content[C]) that facilitate the creation of more complex components. It acts as a bridge between raw foundation primitives and high-level widgets.

    Layer 3: Widgets and Design Systems

    This layer is where the actual user interface is constructed:

    • Layer 3a: Generic Widgets: A collection of interactive components found in core/ (e.g., button, checkbox, dropdown, listview, datatable) and primitives/ (e.g., Box, Text, Image).
    • Layer 3b: Design Systems: Styling layers that define the visual language, such as theme/material3/, theme/cupertino/, theme/fluent/, and theme/devtools/.
    /* 
Architecture Overview:

Layer 3b: Design Systems (styling)
Layer 3a: Generic Widgets (behavior)
Layer 2: Component Development Kit (CDK)
Layer 1: Foundation (Widget, Event, Geometry, Infrastructure)
*/

  11. Understand the gogpu/ui architecture

    main

    The gogpu/ui project follows a layered architecture designed for high-performance, retained-mode rendering. It is built on a dependency inversion principle where the ui package depends on abstract interfaces (gpucontext) rather than concrete implementations like gogpu or wgpu.

    Core Layers

    • User Application Layer: Consumes themes (Material3, DevTools, Fluent, Cupertino) and Interactive Widgets.
    • Widget & Layout Layer: Provides primitives (Box, Text, Image), layout engines (Flex, Stack, Grid), and interactive widgets (Button, Checkbox, etc.).
    • Compositor & Desktop Layer: Handles layer tree composition (Offset, Picture, Opacity) and damage-aware blitting to minimize GPU work.
    • Graphics & State Layer: Uses gogpu/gg for 2D graphics and coregx/signals for reactive state management.

    Render Pipeline Features

    • O(1) frame skip: Uses a flat dirty boundary set to avoid tree walks when idle.
    • Layer Tree composition: Uses specialized layers (OffsetLayer, PictureLayer, etc.) for efficient composition.
    • Damage-aware blit: Only re-renders and updates dirty pixels using multi-rect scissor operations.
    • Unified draw queue: A backend-agnostic command dispatch system that works across Vulkan, DX12, Metal, GLES, Software, and WASM.

  12. Understand the gogpu/ui versioning and stability

    main

    The project follows a v0.x.x versioning strategy for active development. Breaking changes are expected and acceptable during this phase. The project aims to reach v1.0.0 (Production) in December 2026, which will only occur once the API has been stable for at least one year.

    Key Versioning Rules:

    • v0.x.x: Active development; breaking changes are OK.
    • v1.0.0: Target for production-ready, stable API.
    • v2.0.0: Avoided to prevent requiring /v2 import paths.

    When integrating, be aware that the current version is v0.1.50 (as of August 2026).