Expand description
§rungui
A small portable GUI toolkit that is a thin layer over the native toolkits: GTK3 on Linux,
Win32 on Windows, Cocoa on macOS. Each backend declares the platform’s C API by hand; there
are no binding crates. Text is UTF-8 in Rust and converted at the boundary (UTF-16 on Win32,
NSString on Cocoa). Accessibility names and roles are derived by the core and set on the native controls.
§Tutorial
- Create the
Apponce, on the main thread. - Create widgets with
Widget::new(parent, ..). Parents are windows or containers (VBox,HBox,Grid,GroupBox,Tabs/Page,Splitter). Containers lay out their children; tune withWidget::set_expandand friends. ASplittertakes exactly two children (its panes) and lets the user drag the boundary between them. - Attach closures with
on_click,on_change, … Handles areCopy(andSend), so justmovethem into closures. win.show()thenapp.run().
use rungui::*;
let app = App::new("hello").unwrap();
let win = Window::new("Hello");
let col = VBox::new(win);
let label = Label::new(col, "Hi");
Button::new(col, "Click").on_click(move || label.set_text("Clicked"));
win.show();
app.run();A two-pane layout, e.g. a file browser with a tree on the left and a fixed-pitch preview:
use rungui::*;
let app = App::new("panes").unwrap();
let win = Window::new("Panes");
win.set_size(640, 400);
win.set_min_size(320, 200);
let split = Splitter::new(win, Orientation::Horizontal);
let tree = Tree::new(split); // first child: left pane
let preview = TextArea::new(split); // second child: right pane
preview.set_monospace(true);
preview.set_wrap(false);
preview.set_read_only(true);
split.set_position(200); // width of the left pane in pixels
split.on_move(move |px| println!("left pane is now {px}px wide"));
tree.on_select(move |n| preview.set_text(&n.map(|n| tree.text(n)).unwrap_or_default()));
win.show();
app.run();§Things to know
- Handles never panic. A stale or destroyed handle is inert: setters do nothing, getters
return defaults. Creation errors are reported through
last_error. - Only
App::postandApp::quitmay be called from other threads. - Panics inside callbacks are caught and do not unwind into the toolkit.
- For anything the portable API lacks, get the native object with
widget.native_handle()and call the toolkit directly. - Dialogs:
message_box,FileDialogandpromptblock until answered. Any window can be a modal dialog withWindow::run_modal; Enter in aTextInput(TextInput::on_activate) and Escape in a window (Window::on_cancel) are reported to the app. - Optional features (accessibility overrides, sort indicators, popup menus) degrade to no-ops on a backend that lacks them rather than failing.
- Build modes: default is the native backend for the target;
--features mockis a headless in-memory backend for tests;--features emulate-macbuilds the Cocoa backend on Linux against GNUstep.
Structs§
- A11y
Props - Per-widget accessibility overrides (
None= derive from the widget). - App
- Application object. Create exactly one per process, on the main thread, before any widget.
- Button
- A handle to a
Button;Copy, and inert once the widget is destroyed. - Calendar
- Inline month calendar with one selected date (see
Calendarmethods). A handle to aCalendar;Copy, and inert once the widget is destroyed. - Check
Box - A handle to a
CheckBox;Copy, and inert once the widget is destroyed. - Check
Menu Item - A handle to a
CheckMenuItem;Copy, and inert once the widget is destroyed. - Column
- One column of a table.
widthis in logical pixels (initial width; the user may resize). - Combo
Box - A handle to a
ComboBox;Copy, and inert once the widget is destroyed. - Date
- A calendar date in the proleptic Gregorian calendar, years 1753 to 9999 (the range every native calendar control supports).
- File
Dialog - Builder for open/save/folder dialogs.
- Grid
- Grid with
colsauto-flow columns (virtual). A handle to aGrid;Copy, and inert once the widget is destroyed. - Group
Box - Titled frame container.
A handle to a
GroupBox;Copy, and inert once the widget is destroyed. - HBox
- Horizontal stack (virtual: no native widget).
A handle to a
HBox;Copy, and inert once the widget is destroyed. - Image
- A handle to a
Image;Copy, and inert once the widget is destroyed. - Image
Data - Straight (non-premultiplied) RGBA8 pixels, row-major,
rgba.len() == w*h*4. - Label
- A handle to a
Label;Copy, and inert once the widget is destroyed. - ListBox
- A handle to a
ListBox;Copy, and inert once the widget is destroyed. - Menu
- A handle to a
Menu;Copy, and inert once the widget is destroyed. - MenuBar
- A handle to a
MenuBar;Copy, and inert once the widget is destroyed. - Menu
Item - A handle to a
MenuItem;Copy, and inert once the widget is destroyed. - Menu
Separator - A handle to a
MenuSeparator;Copy, and inert once the widget is destroyed. - Page
- One tab of a
Tabs; a container like a window. A handle to aPage;Copy, and inert once the widget is destroyed. - Popup
Menu - Top-level context menu; build it with
MenuItem::new(&popup, ..)etc. A handle to aPopupMenu;Copy, and inert once the widget is destroyed. - Progress
Bar - A handle to a
ProgressBar;Copy, and inert once the widget is destroyed. - Prompt
- A modal dialog asking for one line of text. Built from ordinary widgets and run with
Window::run_modal, so it looks the same everywhere and needs no backend support of its own. - Radio
Button - A handle to a
RadioButton;Copy, and inert once the widget is destroyed. - Radio
Group - Identifies a set of mutually exclusive radio buttons (they may live anywhere in the window).
- Rect
- Rectangle in logical (DPI-independent) pixels; origin top-left, y grows downward.
- Size
- Width/height in logical pixels.
- Slider
- A handle to a
Slider;Copy, and inert once the widget is destroyed. - Spacer
- Flexible empty space (expand = 1 by default).
A handle to a
Spacer;Copy, and inert once the widget is destroyed. - SpinBox
- A handle to a
SpinBox;Copy, and inert once the widget is destroyed. - Splitter
- Two panes with a draggable sash between them (see
Splittermethods; virtual: the panes and the sash are native, the splitter itself is not). A handle to aSplitter;Copy, and inert once the widget is destroyed. - Table
- Multi-column table of strings (see
Tablemethods). A handle to aTable;Copy, and inert once the widget is destroyed. - Tabs
- A handle to a
Tabs;Copy, and inert once the widget is destroyed. - Text
Area - A handle to a
TextArea;Copy, and inert once the widget is destroyed. - Text
Input - A handle to a
TextInput;Copy, and inert once the widget is destroyed. - Timer
- A running timer; callbacks run on the main thread. Dropping the handle does NOT stop it.
- Tree
- Hierarchical tree of text nodes (see
Treemethods). A handle to aTree;Copy, and inert once the widget is destroyed. - Tree
Node Id - Handle to a node of a
crate::Tree. Globally unique, never reused;0is the dead id returned when an insertion failed. - VBox
- Vertical stack (virtual).
A handle to a
VBox;Copy, and inert once the widget is destroyed. - Widget
- Untyped handle with the operations every widget has.
- Widget
Id - Symbolic, never-reused handle to a widget in the registry.
0is the “dead” id. Plainu64inside:Copy,Send, safe to keep after the widget is destroyed (operations on stale ids are no-ops). - Window
- Top-level window. Children added with other widgets’
new(&window, ..). A handle to aWindow;Copy, and inert once the widget is destroyed.
Enums§
- A11y
Role - What a widget is, for assistive technology. Only roles that every backend can express are
offered; each widget kind has a default (a
Buttonis aButton) andcrate::Widget::set_a11y_roleoverrides it. - Align
- Cross-axis alignment of a child inside its stack/grid cell.
- Answer
- The button a message box was answered with.
- Buttons
- Which buttons a message box offers.
- Column
Align - Horizontal text alignment of a
Column. - Error
- Errors. Constructors never return these (they yield a dead handle and record the error,
see
crate::last_error); fallible entry points such asApp::newdo. - Message
Kind - Which icon a message box shows.
- Native
Handle - Raw native object, for users who want to write platform-specific code. The payload is the pointer value (GtkWidget*, HWND/HMENU, NSView*/NSWindow*/NSMenu*…).
- Orientation
- Direction of a
crate::Splitter:Horizontalputs the panes side by side (left | right, mirrored under RTL) with a vertical sash between them;Verticalstacks them (top / bottom).
Constants§
- MAX_
COLUMNS - Most columns a table keeps; backends index columns with 16 bits and nobody needs more.
- MAX_
IMAGE_ EDGE - Largest image edge accepted, in pixels. Keeps
w * h * 4far from overflow on every target and well inside what the toolkits can allocate. - MAX_
NESTING - Deepest allowed nesting of widgets (a window’s children are at depth 1). Layout, accessibility
and the toolkits recurse over the widget tree, so creating a widget below this depth fails with
Error::LimitExceededand returns a dead handle instead of risking a stack overflow.
Functions§
- last_
error - The most recent creation/timer error on this thread, if any (clears it).
- message_
box - Modal message box; returns which button was pressed.
- prompt
- Ask for one line of text in a modal dialog (see
Promptfor buttons and password fields): the text on OK or Enter,Noneon cancel. - set_
rtl_ layout - Mirror horizontal layout (HBox order, Grid columns, VBox cross-axis alignment) for right-to-left locales. Applies to every window of the calling (UI) thread and relayouts them. Default off.