Crate keru

Expand description

Keru is an experimental graphical user interface library.

§Code Example

// Define a unique identity for the button
#[node_key] const INCREASE: NodeKey;
 
// Create a NodeParams struct describing a button
let increase_button = BUTTON
    .color(Color::RED)
    .text("Increase")
    .key(INCREASE);
 
// Place the nodes into the tree and define the layout
ui.v_stack().nest(|| {
    ui.add(increase_button);
    ui.label(&state.count.to_string());
});
 
// Change the state in response to events
if ui.is_clicked(INCREASE) {
    state.count += 1;
}
// `is_clicked()` can be also called as a chained method after `ui.add(increase_button)`.
// In that case, using a key wouldn't be necessary.

See the counter_small example in the repository for a full working version of this code.

§Window Loop

Keru is meant to be used as part of a regular winit/wgpu window loop managed by the library user, as shown in the window_loop example in the repository. However, it also includes a one-line window loop that can be used for quick experimentation.

Once you have a window loop, you can create a Ui struct and store it in your main program state.

§Building the GUI

Every frame, start a new GUI frame, rerun all your GUI building code, then finish the frame.

ui.begin_frame();
ui.v_stack().nest(|| {
    ui.label("Hello");
    ui.label("World");
});
ui.finish_frame();

The Ui struct retains the state of the whole GUI, so even if you do this on every frame, it doesn’t mean that the GUI is rerendering or doing a full relayout every time. The library can detect differences and apply only the minimal updates or partial relayouts needed.

In Keru, everything is a node. Whether you want a button, an image, a text element, a stack container, or anything else, the way is always to add() a node with the right NodeParams.
Ui has some convenience methods like Ui::label(). These are always equivalent to adding one or more nodes with specific NodeParams.
To check interactions on a node, use NodeParams::key() to associate a NodeKey to a NodeParams, then call methods like Ui::is_clicked() with the same NodeKey.
You can use the NodeKey::sibling() function to create keys dynamically at runtime. This is useful for dynamic GUIs where you can’t identify every node with a static NodeKey in the way the basic examples do it.
To create reusable “components”, you can just wrap the GUI building code in a function, like the builtin convenience functions like Ui::label() do. If the code uses unique NodeKeys, however, you’ll need to wrap it in a subtree.

This allows multiple calls to the same component function to reuse the same key multiple times without conflicts.
The Ui::reactive() function provides an experimental way to improve performance in complex GUIs with many independent components.

Modules§

basic_window_loop: Helper functions for winit and wgpu.
example_window_loop: A very simple way to start a winit/wgpu window loop and to draw a Keru GUI inside it.
winit_key_events
winit_mouse_events

Structs§

Color: A rgba color
FullNodeParams: An extended version of NodeParams that can hold text or other borrowed data.
Immut: A wrapper struct for a value that will never change during its lifetime.
Interact: The node’s interact behavior.
Layout: The node’s layout, size and position.
NodeKey: An unique key that identifies a GUI node.
NodeParams: A struct describing the params of a GUI node.
Observer: A wrapper that keeps track of changes to a value.
Reactive: A struct referring to a reactive block created with Ui::reactive().
Rect: The node’s visual appearance.
RenderInfo: The data needed for rendering a node with custom code.
RoundedCorners: A bitflag struct defining which corners of a rectangle are rounded
Stack: Options for stack container nodes.
Static: A wrapper struct for a 'static value that will never change during its lifetime.
Tab: A tab for Ui::vertical_tabs
TextOptions: Options for text nodes.
Ui: The central struct of the library, representing the whole GUI state.
UiParent: A struct referring to a node that was added on the tree.
UiSubtree: A struct referring to a subtree created with Ui::subtree() or Ui::named_subtree().
VertexColors: A node’s vertex colors.
Xy: A generic container for two-dimensional data.

Enums§

Arrange: Options for the arrangement of child nodes within a stack node.
Axis: The X or Y axes.
Len: A length on the screen, expressed either as pixels or as a fraction of a parent rectangle.
Position: A node’s position relative to its parent.
Shape: The node’s shape.
Size: A node’s size.

Constants§

BUTTON: NodeParams for a button.
CONTAINER: NodeParams for a container.
CUSTOM_RENDERED_PANEL: NodeParams for a custom rendered node.
DEFAULT: NodeParams for a default.
H_STACK: NodeParams for a horizontal stack.
ICON_BUTTON: NodeParams for an icon button.
IMAGE: NodeParams for an image.
IMAGE_BUTTON: NodeParams for an icon button.
LABEL: NodeParams for a label.
MARGIN: NodeParams for a margin.
MULTILINE_LABEL: NodeParams for a label containing a multi-line paragraph.
PANEL: NodeParams for a panel.
SPACER: NodeParams for a spacer element.
TEXT: NodeParams for a text element.
TEXT_EDIT: NodeParams for a text element.
TEXT_PARAGRAPH: NodeParams for a text element containing a multi-line paragraph.
V_SCROLL_STACK: NodeParams for a vertically scrollable vertical stack.
V_STACK: NodeParams for a vertical stack.

Traits§

MaybeObservedText

Functions§

is_in_skipped_reactive_block: Returns true if currently in a reactive block that is being skipped.

Type Aliases§

SubtreeKey
XyRect: A two-dimensional rectangle.

Attribute Macros§

node_key: A macro that creates an unique NodeKey.

Crate keruCopy item path