CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

# Build entire project
go build ./...

# Run tests
go test ./...

# Run a single test
go test -run TestName ./path/to/package

# Cross-platform builds (supported targets)
GOOS=darwin GOARCH=amd64 go build ./...   # macOS
GOOS=windows GOARCH=amd64 go build ./...  # Windows
GOOS=android GOARCH=arm64 go build ./...  # Android
GOOS=js GOARCH=wasm go build ./...        # WebAssembly

# Run example applications
go run ./cmd/hello
go run ./cmd/clipboard
go run ./cmd/iconchooser

Architecture Overview

Prevara (formerly "gel" - Gio Elements) is a widget toolkit built on top of Gio. It provides a fluent API for building GUIs with method chaining.

Core Components

Window & Theme (window.go, theme.go): Entry points for applications. Window embeds both Theme (styling) and app.Window (platform integration). Create windows via NewWindowP9(quit) for default theme or NewWindow(theme) for custom themes.

App Framework (app.go): Multi-page application scaffold with title bar, sidebar, status bar, and page navigation. Create with window.App(size, activePage, breakpoint).

Fluent Widget Pattern: All widgets follow a builder pattern where configuration methods return *Widget for chaining, and Fn is the final method that returns l.Widget (Gio's layout function type). Example:

w.Flex().Vertical().SpaceEvenly().
    Rigid(w.H1("Title").Color("Primary").Fn).
    Flexed(1, bodyWidget).
    Fn

Widget Pool (pools.go, pooltypes.go): Object pooling for stateful widgets (Bool, List, Clickable, Editor, IncDec, Checkable). Access via window.WidgetPool.GetXxx(). Call pool.Reset() at frame start to reclaim widgets.

Layout Widgets

Flex / VFlex: Horizontal/vertical flex layouts with Rigid/Flexed children
Stack: Z-axis stacking with alignment
Inset: Padding/margins
Direction: Directional alignment wrapper
Fill: Background fills with alignment

Input Widgets

Clickable: Click/press handling
Bool: Boolean state widget
Editor: Text input
Checkable / Checkbox: Toggle controls
Slider / IntSlider: Value sliders
IncDec: Increment/decrement buttons

Display Widgets

Label: Text display (with H1-H6, Body1/2, Caption, etc. presets)
Icon / IconButton: Icon rendering
Button / ButtonLayout: Clickable buttons
ProgressBar / Indefinite: Progress indicators
List / WrapList: Scrollable lists

Supporting Packages

pkg/log: Colorized structured logging. Initialize with log.GetLogPrinterSet() returning F, E, W, I, D, T level printers
pkg/qu: Channel utilities for quit signals (qu.T() creates quit channel, qu.C is the channel type)
pkg/interrupt: Signal handling with cross-platform restart support
pkg/opts: Configuration option types (binary, text, integer, float, duration, list)
fonts/p9fonts: Default Plan9-style font collection
clipboard: Platform-specific clipboard operations (X11 on Linux)

Logging Convention

Each package has a log.go file that initializes package-level loggers:

var F, E, W, I, D, T = log.GetLogPrinterSet(log.AddLoggerSubsystem(version.PathBase))

Use D.Ln() for debug, I.Ln() for info, E.Chk(err) for error checking, etc.

Color System

Colors are referenced by name strings (e.g., "Primary", "DocBg", "DocText", "PanelBg"). The theme maintains light/dark variants toggled via theme.Dark.Flip().

3.5 KiB Raw Permalink Blame History