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(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 minimal 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(). They 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.

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
node_library
thread_future
thread_future_2

Structs§

Animation
AsyncButton
BoundingBox: A bounding box.
Circle: Parameters for drawing a circle
CircleArc: Parameters for drawing an arc
CirclePie: Parameters for drawing a pie slice
CircleRing: Parameters for drawing a ring (hollow circle)
Click: A struct describing a click event on a GUI node.
ClipRect: A clip rect
Color
ColorBrush: RGBA color value for text rendering.
ComponentKey
DashedBoxOutline: Parameters for drawing a dashed box outline (composed of segments and corner arcs)
DashedHexagonOutline: Parameters for drawing a dashed hexagon outline (composed of segments)
Drag: A struct describing a drag event on a GUI node.
DrawContext: A context for custom drawing.
DrawTransform: A simple 2D transform with uniform scale and offset
FontWeight: Visual weight class of a font, typically on a scale from 1.0 to 1000.0.
Gradient: Gradient definition for shapes
Grid: Parameters for drawing a grid
GridElement: How many cells of a grid the node occupies.
GridFlow: Controls in which direction grid children are placed.
Hexagon: Parameters for drawing a hexagon
HorizontalTabsState
Hover: A struct describing a hover event on a GUI node.
ImageOptions: Texture sampling options: border insets for 9-slice scaling and per-axis tiling modes.
Interact: The node’s interact behavior.
KeruElementRange
Layout: The node’s layout, size and position.
LoadedImage: A loaded image stored in the atlas.
NineSliceMargins: Pixel insets from each edge of a source image that define the 9 slice regions. Each value is a distance in source image pixels from the respective edge.
Node: A struct describing the params of a GUI node.
NodeKey: An unique key that identifies a GUI node.
NodeText
Observer: A wrapper that keeps track of changes to a value.
QuadraticBezier: Parameters for drawing a quadratic bezier curve from p0 to p2, with p1 as a control point.
Reactive: A struct referring to a reactive block created with Ui::reactive().
Rect: The node’s visual appearance.
Rectangle: Parameters for drawing a box/rectangle
RenderInfo: The data needed for rendering a node with custom code.
ReorderStack
RoundedCorners: Bitflags specifying which corners of a rectangle should be rounded.
Scroll: A struct describing a scroll event on a GUI node.
Segment: Parameters for drawing a line segment
Sense
Shadow
Slider
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.
TextStyleFlags
TransformView
TransformViewState
Triangle: Parameters for drawing a triangle
Ui: The central struct of the library, representing the whole GUI state.
UiKeyScope: A struct referring to a key scope created with Ui::key_scope() or Ui::named_key_scope().
UiNode
UiNodeChildrenIter
UiParent: A struct referring to a node that was added on the tree.
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.
ChildrenCanHide
ChildrenLayout: Determines how the children of the node are laid out in its space.
ColorFill: Fill style for shapes - solid color or gradient
Direction
EnterAnimation
ExitAnimation
FontStyle: Visual style or “slope” of a font.
GradientType: Gradient type for shapes
GridType: Grid type for the grid primitive
Image: Data for an image to be displayed
LineHeight: The height that this text takes up. The default is MetricsRelative(1.0), which is the given font’s preferred line height.
MainAxisCellSize: Specifies how cells are sized along the main axis of a grid layout.
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
TileMode: How a non-corner region of a bordered texture is filled along one axis.
VerticalTextAlignment

Constants§

DEFAULT_CORNER_RADIUS
NO_ANIMATION
Z_STEP

Traits§

Component: Trait for a reusable Ui component.
SimpleComponent: Trait for a reusable Ui component.

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§

SharedTextStyle: A shareable text style.
TextStyleProperty: An individual text style property,
XyRect: A two-dimensional rectangle.

Attribute Macros§

component_key
node_key: A macro that creates a unique NodeKey.

Crate keru

Crate keru Copy item path

§Code Example

§Window Loop

§Building the GUI

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate keru