Skip to main content

Crate rungui

Crate rungui 

Source
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

  1. Create the App once, on the main thread.
  2. Create widgets with Widget::new(parent, ..). Parents are windows or containers (VBox, HBox, Grid, GroupBox, Tabs/Page, Splitter). Containers lay out their children; tune with Widget::set_expand and friends. A Splitter takes exactly two children (its panes) and lets the user drag the boundary between them.
  3. Attach closures with on_click, on_change, … Handles are Copy (and Send), so just move them into closures.
  4. win.show() then app.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::post and App::quit may 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, FileDialog and prompt block until answered. Any window can be a modal dialog with Window::run_modal; Enter in a TextInput (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 mock is a headless in-memory backend for tests; --features emulate-mac builds the Cocoa backend on Linux against GNUstep.

Structs§

A11yProps
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 Calendar methods). A handle to a Calendar; Copy, and inert once the widget is destroyed.
CheckBox
A handle to a CheckBox; Copy, and inert once the widget is destroyed.
CheckMenuItem
A handle to a CheckMenuItem; Copy, and inert once the widget is destroyed.
Column
One column of a table. width is in logical pixels (initial width; the user may resize).
ComboBox
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).
FileDialog
Builder for open/save/folder dialogs.
Grid
Grid with cols auto-flow columns (virtual). A handle to a Grid; Copy, and inert once the widget is destroyed.
GroupBox
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.
ImageData
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.
MenuItem
A handle to a MenuItem; Copy, and inert once the widget is destroyed.
MenuSeparator
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 a Page; Copy, and inert once the widget is destroyed.
PopupMenu
Top-level context menu; build it with MenuItem::new(&popup, ..) etc. A handle to a PopupMenu; Copy, and inert once the widget is destroyed.
ProgressBar
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.
RadioButton
A handle to a RadioButton; Copy, and inert once the widget is destroyed.
RadioGroup
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 Splitter methods; virtual: the panes and the sash are native, the splitter itself is not). A handle to a Splitter; Copy, and inert once the widget is destroyed.
Table
Multi-column table of strings (see Table methods). A handle to a Table; Copy, and inert once the widget is destroyed.
Tabs
A handle to a Tabs; Copy, and inert once the widget is destroyed.
TextArea
A handle to a TextArea; Copy, and inert once the widget is destroyed.
TextInput
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 Tree methods). A handle to a Tree; Copy, and inert once the widget is destroyed.
TreeNodeId
Handle to a node of a crate::Tree. Globally unique, never reused; 0 is 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.
WidgetId
Symbolic, never-reused handle to a widget in the registry. 0 is the “dead” id. Plain u64 inside: 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 a Window; Copy, and inert once the widget is destroyed.

Enums§

A11yRole
What a widget is, for assistive technology. Only roles that every backend can express are offered; each widget kind has a default (a Button is a Button) and crate::Widget::set_a11y_role overrides 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.
ColumnAlign
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 as App::new do.
MessageKind
Which icon a message box shows.
NativeHandle
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: Horizontal puts the panes side by side (left | right, mirrored under RTL) with a vertical sash between them; Vertical stacks 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 * 4 far 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::LimitExceeded and 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 Prompt for buttons and password fields): the text on OK or Enter, None on 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.

Type Aliases§

Result
std::result::Result with this crate’s Error.