dymokomi/luce-ui
A UI framework written in Luce Base, consumed through ordinary Base structs or Luce objects. Controls implement Widget; an Application owns the native event loop, layout, input routing and presentation.
A library written in luce-base. Latest release 0.19.6.
Install#
luc add dymokomi/luce-uiDocumentation#
luce-ui
A UI framework written in Luce Base, consumed through ordinary Base structs or Luce objects. Controls implement Widget; an Application owns the native event loop, layout, input routing and presentation. The package uses standard gpu and window: Metal on ARM64 macOS and Vulkan on Windows x64. Linux supports the portable tests and font backend; native window presentation is still pending.
A Luce application uses public imports and normal construction:
from luce_ui.ui import Application, Button, Text, VStack
pub func main(arguments: list[str]) -> int!:
let button = Button("Continue")
let content = VStack([Text("Hello Luce"), button], padding = 24.0)
let app = Application(content, title = "Hello")
app.run()
return 0
Declare [dependencies] luce_ui = "../luce-ui" in the consumer's luce.toml. The separate luce-demos project connects a button to a counter and runs the UI. No application loop, generated Base sources or platform framework declarations are needed in a consumer.
When an application crashes, it does not just disappear: luce-ui starts it again to show the crash report in a window of its own, with Copy, Reopen and Quit, and app.on_crash(callback) gives it a chance to save its work first. See "Crash reports and the crash window" in API.md.
Read API.md for ownership, callbacks, custom widgets and layout; DESIGN.md describes the framework contracts.
Build the sibling luce-base and luce repositories (main; `python3 ../luce-base/tools/checkout_main.py . ../luce` checks out what is missing). Then run:
luc test
That runs every module's test blocks and four test programs: tests/ownership (a Base consumer) and tests/controls (Luce custom widgets) everywhere, and on a macOS desktop tests/pixels (Metal pixels, clipping, resize and expired viewport references) and tests/crash_relaunch (a program that traps is started again to show its crash window) and tests/crash_quiet (with LUCE_CRASH_WINDOW=0, a trap in the run loop or on a worker thread ends the process and starts nothing); without a desktop those are skipped. Test binaries and compiler scratch files are temporary. A specifically requested consumer binary can be built with python3 tools/build.py ENTRY -o OUTPUT.
This is an early framework with native antialiased fonts, multiline editing, lists, menus, toolbars, bordered panes, resizable splits, code folding, shared actions and inherited themes. Paragraph shaping, accessibility, general scrolling containers and a broad widget catalog remain future work. MIT or Apache-2.0, at your option.
Windows x64
Build sibling luce-base and luce checkouts with python tools/build_windows.py in each compiler repository. Run luc test in this repository. For real windows and rendering, install the Vulkan SDK and start a fresh terminal with VULKAN_SDK set. The sibling luce-demos UI and sphere applications exercise Win32/Vulkan presentation. CPU tests run in hosted Windows CI; GPU smoke tests require an interactive desktop and Vulkan hardware.
Typography is shared explicitly: let font = Font(), then Button("Save", font = font) and TextEditor(source, font = font). Font loads an installed monospace family (family = "Menlo", for example); omitting the family selects Menlo on macOS, Consolas on Windows, and the fontconfig monospace family on Linux. All text controls use the same 12-point default (ui.default_font_size). Font metrics also drive editor hit testing, caret positions and line spacing; leading is one third of the font size. Stacks use an 8-point gap (ui.default_spacing), and dialogs use that gap with 12-point padding (ui.default_padding). Buttons, fields, menus, tab bars and section headings size themselves from the font. Explicit font sizes and layout spacing remain logical points.
The UI owns a bounded cache of grayscale text runs. Standard fonts owns native font resources; standard gpu uploads coverage and draws it through the selected Metal or Vulkan backend. Rendering follows the window backing scale instead of stretching a low-resolution font. Linux font loading needs Cairo/FreeType and an installed monospace font (libcairo2-dev fonts-dejavu-core on Debian/Ubuntu). Linux window/GPU presentation remains a separate, unimplemented backend.
This first font API loads installed families, not arbitrary font files. Text is laid out on the editor's scalar grid; paragraph shaping, bidi, grapheme-aware editing, color emoji, and a font picker remain future work. Windows substitutes a replacement glyph for supplementary-plane scalars in this initial GDI adapter.
Compact application composition
Toolbar([Menu("File", [save]), Spacer(), Button(action = save)]) presents the same Action through two controls. Register it with Application.set_actions for window shortcuts. Shortcut(Key.s, primary = true) uses Ctrl or Command; matching repeated key-down events do not invoke an action repeatedly.
Application(content, theme = Theme()) supplies inherited semantic colors and metrics. Theme(control_lines = 2.0) gives controls more vertical room. The default is one font line with one character cell of horizontal inset. A subtree can use layout().set_theme(...), then inherit_theme() to return to its parent's theme. Typography remains explicit: pass one shared Font through your view components.
To follow the system's light or dark setting (what CSS calls prefers-color-scheme), read app.appearance() (Appearance.light or .dark, also before run) and pick a theme, then connect app.on_appearance(callback): the loop calls it with the new value when the user switches, and the callback can call set_theme. Release or disconnect the connection to stop. The default Theme() is dark; a light palette is the application's to define.
See composition contracts, the API, and text change/highlight contracts. The separate luced editor composes named Luce views from these Base controls; its entry point contains no geometry or signal wiring.
SplitView(Pane(sidebar), SplitView(Pane(editor), Pane(output), axis=Axis.vertical)) builds a bordered workspace with draggable dividers. Children supply minimum and maximum sizes, and splits can nest. Generic TextEditor.set_folds accepts ranges from a language service; Luce syntax knowledge stays in luced. See the pane API and folding contracts.
Context menus decorate any widget: ContextMenu(content, actions, font=font). CommandPalette(actions, font=font) supplies command search, and TextPrompt supplies file-name entry or confirmation. Both mount as popup children and reuse the framework's focus restoration, text input and window clipping. Panes use Theme.active_border to indicate descendant focus; Theme.gutter styles the folding margin independently. See the popup API.
Layout tracks hover independently of focus and capture, exposing is_hovered, contains_pointer and local pointer_position to every widget. Menus switch between sibling titles during an open session. Panes, controls, list rows and editor gutters use inherited hover colors. Popup shadows are sharp translucent rectangles with configurable offset and opacity. See the hover API.
Pane headers join directly to their frames:
let files = ListView([ListItem("src", icon = IconKind.folder)], font = font)
let header = PaneHeader("FILES", icon = IconKind.folder_open, detail = "project", font = font)
let sidebar = Pane(files, header = header)
The header shares the border's normal, hover and focus colors, with a vector icon and 1.5 character cells of leading inset. Theme.header_inset_cells adjusts this spacing. Reusable Icon widgets, pane icons and list symbols use the same vector shapes through standard gpu; they scale with the shared font. Portable tests cover header layout, resizing, font changes and icon-bearing lists. Native Metal readback verifies frame colors and icon pixels.
DStack supplies a dynamic workspace of tabbed panels:
let files = Panel("FILES", explorer, icon = IconKind.folder, closable = false)
let source = Panel("main.luc", editor, icon = IconKind.code)
let workspace = DStack([files, source], font = font)
workspace.move(source, files, DockPosition.right)
Every group has a trailing + menu listing the application's panels (set_catalog) and Split Right/Down. Applications make a picked panel in response to on_add; set_close_handler can refuse closing an unsaved document. Header dragging moves tabs: dropped on a tab strip they stack, on a pane's edge they split it, and anywhere else they float in their own window over the panes. A floating window moves by its title, resizes by its border, closes by its ×, and docks again when its title is let go over a tab strip or pane edge or pressed twice. float(panel) floats a docked panel or adds a new one floating. The source detaches visually while dragging: neighbors expand and a floating caption follows the pointer. Drop previews use that expanded layout and respect minimum sizes. Escape restores the original layout. Nested dividers resize live, and empty branches collapse. Text, actions, pane headers and dividers select semantic system cursors through the standard window API. Panels retain their content, focus targets and identity across these operations. See the dynamic workspace API and design.
Dependencies#
| Package | Version |
|---|---|
| dymokomi/luce-3d | newest |
| dymokomi/luce-clipboard | newest |
| dymokomi/luce-color | newest |
| dymokomi/luce-dialogs | newest |
| dymokomi/luce-fonts | newest |
| dymokomi/luce-gpu | newest |
| dymokomi/luce-std | newest |
| dymokomi/luce-svg | newest |
| dymokomi/luce-window | newest |
Versions#
0.19.6
Browse source · pack · commit 20fb23a5895b
SHA-256 c1a82d76e785a6d74a44b4f557e5db74ea4a77a349f2ab77c87c16b56ee32f7b
luce-ui 0.19.6: batch release
0.19.5
Browse source · pack · commit e6e4608e7ff6
SHA-256 2e9cee98726fb25a0a699b7e64e4e2a44a82e0684b988c3c6ee850e422e51155
luce-ui 0.19.5: batch release
0.19.4
Browse source · pack · commit bce45ca71cc3
SHA-256 0346b8efda4150da3801ede594cc31f97130eb9c4e4fe51525650b9e86775bd3
luce-ui 0.19.4: batch release
0.19.3
Browse source · pack · commit 54ca447a88ce
SHA-256 233ddd188beb2d41d917ea13c46bd4d9a55f663b8d9b4888585f8e43ef6c079b
luce-ui 0.19.3: batch release
0.19.2
Browse source · pack · commit 691060a0483d
SHA-256 4e5c9460080ae65610a31b22f61091f08c69b179bb6412481282cd380bd279f6
luce-ui 0.19.2: batch release
0.19.1
Browse source · pack · commit 28a99ee9c974
SHA-256 869909f5d6943cc4d544b402e2e8deb02e59354b14052dd41431336dc918f35c
luce-ui 0.19.1: batch release
0.19.0
Browse source · pack · commit b2f18c277058
SHA-256 ec4ca8957f09337eba374a3789e58c5b19f22390287f1f44129aa7a288457227
crash window and Application.on_crash handles; choose_folder; ThumbnailGrid; Histogram; CurveEditor.set_points; ParameterPanel gradients and swatches; collections.Buffer; dependencies name no version