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 Node struct describing a button
let increase_button = BUTTON
    .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 values.
There are also “components”, like Slider. Components are added with Ui::add_component() and they are a way to wrap multiple nodes into a reusable structure. You can define custom components with the SimpleComponent and Component traits.
Ui has some convenience methods like Ui::label(). These work the same way as components, but with more natural syntax.
To check interactions on a node, use Node::key() to associate a NodeKey to a Node, then call methods like Ui::is_clicked() with the same NodeKey.
The Ui::reactive() function provides an experimental way to improve performance in complex GUIs with many independent components.

Re-exports§

pub use bumpalo;
pub use keru_draw::keru_text;

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.
key_events
mouse_events
thread_future
thread_future_2

Structs§

Animation
AsyncButton
BoundingBox: A bounding box.
Click: A struct describing a click event on a GUI node.
Color
ColorBrush: RGBA color value for text rendering.
ComponentKey
Drag: A struct describing a drag event on a GUI node.
FontWeight: Visual weight class of a font, typically on a scale from 1.0 to 1000.0.
FullNode: An extended version of Node that can hold text or other borrowed data.
Gradient: Gradient definition for shapes
HorizontalTabsState
Hover: A struct describing a hover event on a GUI node.
Interact: The node’s interact behavior.
KeruElementRange
Layout: The node’s layout, size and position.
Node: A struct describing the params of a GUI node.
NodeKey: An unique key that identifies 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.
ReorderStack
RoundedCorners: Bitflags specifying which corners of a rectangle should be rounded.
ScrollEvent: A struct describing a scroll event on a GUI node.
Sense
Slider
Stack: Options for stack container nodes.
StateTransition
StatefulTransformView
StatefulVerticalTabs
Stroke: The visual style of a stroke.
StyleHandle: Handle for a text style. Use with Text methods to apply styles to text.
Tab: A tab for Ui::vertical_tabs
TabContainer
TextOptions: Options for text nodes.
TransformView
TransformViewState
Ui: The central struct of the library, representing the whole GUI state.
UiNode
UiNodeChildrenIter
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().
UiWaker: A handle that can be used to wake up the Ui from another thread.
VerticalTabsState
Xy: A generic container for two-dimensional data.

Enums§

Anchor: Anchor point within a node for positioning.
Arrange: Options for the arrangement of child nodes within a stack node.
Axis: The X or Y axes.
Cap
ChildrenCanHide
ColorFill: Fill style for shapes - solid color or gradient
EnterAnimation
ExitAnimation
FontStyle: Visual style or “slope” of a font.
Image: Data for an image to be displayed
Join
LineHeight: The height that this text takes up. The default is MetricsRelative(1.0), which is the given font’s preferred line height.
NodeText
Pos: A node’s position relative to its parent.
RenderCommand: A single render command in the list provided by Ui::render_commands().
Shape: The node’s shape.
Size: A node’s size.
SlideDirection
SlideEdge

Constants§

BUTTON: Node for a button.
CONTAINER: Node for a container.
CUSTOM_RENDERED_PANEL: Node for a custom rendered node.
DEFAULT: Node for a default.
DEFAULT_CORNER_RADIUS
H_LINE: Node for a horizontal divider line.
H_SPACER: Node for a invisible spacer element that fills all the available space in the X direction.
H_STACK: Node for a horizontal stack.
ICON: Node for an icon element.
ICON_BUTTON: Node for an icon button.
ICON_DELETE
ICON_EDIT
ICON_LEFT
ICON_MINUS
ICON_PLUS
ICON_RIGHT
IMAGE: Node for an image.
IMAGE_BUTTON: Node for an icon button.
LABEL: Node for a label.
MARGIN: Node for a margin.
MULTILINE_LABEL: Node for a label containing a multi-line paragraph.
NO_ANIMATION
PANEL: Node for a panel.
SPACER: Node for a spacer element.
TEXT: Node for a text element.
TEXT_EDIT: Node for a multiline text edit box.
TEXT_EDIT_LINE: Node for a single line text edit box.
TEXT_PARAGRAPH: Node for a text element containing a multi-line paragraph.
V_SCROLL_STACK: Node for a vertically scrollable vertical stack.
V_SPACER: Node for a invisible spacer element that fills all the available space in the Y direction.
V_STACK: Node for a vertical stack.
Z_STEP

Statics§

ORIGINAL_DEFAULT_TEXT_STYLE: The original default text style that can be restored with Ctrl+0

Traits§

Component: Trait for a reusable Ui component.
SimpleComponent: A simpler version of Component for stateless components that don’t have nested children.

Functions§

is_in_skipped_reactive_block: Returns true if currently in a reactive block that is being skipped.
with_arena: Access keru’s thread-local bump arena for temporary allocations. Useful for small local allocations without passing an arena around, like formatting strings to show in the gui.
with_clipboard: Runs the given closure with mutable access to the thread-local Clipboard.

Type Aliases§

StateId
SubtreeKey
TextStyle: Text style.
XyRect: A two-dimensional rectangle.

Attribute Macros§

component_key
node_key: A macro that creates a unique NodeKey.
state_key

Crate keru

Crate keru Copy item path

§Code Example

§Window Loop

§Building the GUI

Re-exports§

Modules§

Structs§

Enums§

Constants§

Statics§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate keru