Crate matrix_gui

Expand description

§matrix-gui

An immediate-mode embedded GUI framework inspired by kolibri-embedded-gui, built on top of embedded-graphics. This framework removes automatic layout functionality and adopts a state ID-based approach with predefined rectangles as the layout framework.

§Features

Immediate-mode GUI: Simple and intuitive API with minimal boilerplate
Zero-allocation design: Except for control state values, all data resides on the stack, suitable for resource-constrained systems
Region-based layout: Flexible free-form layout with predefined rectangular regions, providing layout design tools (Matrix GUI Layout)
Feature-based modularity: Enable only the features you need to minimize binary size
no_std compatible: Works seamlessly in bare-metal environments
Integer-based animations: Lightweight animation system without floating-point operations
Custom widgets: Easy to create custom widgets by referencing built-in widgets
Mixed font display: Uses the multi-mono-font library, and CJK font generation can use the PCtoLCD2022 tool

§Built-in Widgets

§Static Widgets

Background - Background clearing
Label - Text labels
PlainText - Multi-line text
StaticImage - Static images
StaticLine - Static lines
Bar - Progress bars
ListBox - List boxes

§Interactive Widgets (requires `interaction` feature)

Button - Buttons
Checkbox - Checkboxes
RadioButton - Radio buttons
Slider - Sliders
MessageBox - Message dialogs (requires popup feature)

§Screenshots

§Basic Example

Basic Example

A comprehensive example demonstrating various widgets including buttons, sliders, checkboxes, radio buttons, labels, and static images.

Plain Text

Multi-line text display widget with support for different fonts and styles.

§Message Box

Message Box

Modal dialog widget for displaying messages and user interactions.

§Grid Layout

Grid Layout

Compile-time grid layout example showing organized widget placement in a grid structure.

§Getting Started

§Installation

Add this to your Cargo.toml:

[dependencies]
matrix-gui = "0.1.0"

§Basic Example

use matrix_gui::prelude::*;
use embedded_graphics::pixelcolor::Rgb565;

// Define regions using macro
matrix_gui::free_form_region!(
    RegionId,
    (TITLE, 100, 6, 143, 24),
    (BUTTON, 20, 85, 61, 24),
    (LABEL, 19, 34, 130, 20),
);

fn main() {
    // Create display and UI context
    let mut display = SimulatorDisplay::<Rgb565>::new(Size::new(320, 240));
    let smartstates = RenderState::new_array::<REGIONID_COUNT>();
    let widget_states = WidgetStates::new(&smartstates);
    let style = rgb565_light_style();

    let mut ui = Ui::new_fullscreen(&mut display, &widget_states, &style);

    // Add widgets
    ui.add(Label::new(&Region::TITLE, "Hello World"));
    ui.add(Button::new(&Region::BUTTON, "Click Me"));

    // Handle interactions
    ui.interact(Interaction::Pressed(Point::new(100, 100)));
}

§Features

This library uses Cargo features to enable optional functionality. By default, no features are enabled, allowing you to choose exactly what you need.

§Feature Overview

Feature	Description	Dependencies
`interaction`	User interaction support (touch/mouse)	-
`focus`	Keyboard focus management	`interaction`
`animation`	Lightweight animation system	-
`popup`	Modal dialog support	-
`framebuffer`	Off-screen rendering support	-
`fill-rect`	Fast rectangle filling with hardware acceleration	-
`debug-color`	Debug color visualization	-
`log`	Logging support	`log` crate
`part`	Core feature bundle	`log`, `focus`, `debug-color`, `interaction`, `framebuffer`
`all`	Enable all features	`part`, `fill-rect`, `popup`
`anim`	Animation feature bundle	`animation`, `part`

§Feature Details

§`interaction`

Enables user interaction support including touch/mouse input and interactive widgets.

Enables:

Interaction enum (Pressed, Drag, Release, Click)
Interactive widgets (Button, Checkbox, RadioButton, Slider)
Region collision detection
Event handling

§`focus`

Enables keyboard focus management for navigation and keyboard input.

Dependencies: interaction

Enables:

FocusState focus state management
FocusTracker focus tracking
Focused enum (No, Yes, Trigger)
Keyboard navigation support

§`animation`

Enables a lightweight animation system using integer-only math.

Enables:

Anim animation definition
Easing functions (Linear, EaseIn, EaseOut, EaseInOut)
AnimManager animation manager
Fixed-point arithmetic (no floating-point operations)

§`popup`

Enables modal dialog support.

Enables:

Modal widget
MessageBox widget
Modal state management

§`framebuffer`

Enables off-screen rendering support for double buffering and complex widget caching.

Enables:

WidgetFramebuf framebuffer widget
Off-screen rendering capabilities
Buffer management

§`fill-rect`

Enables direct fast rectangle filling.

Enables:

fill_with_color() color filling
fill_with_buffer() buffer filling

§`debug-color`

Enables debug color visualization for development and layout verification.

Enables:

Region boundary drawing
Debug information display
Development helper tools

§Layout Tools

The project provides rectangle layout tools for designing your UI layouts. Check the releases page for layout tools and utilities.

§Examples

basic-example - Comprehensive example with various widgets
anim-demo - Animation system demonstration
anim-by-ui - UI-driven animation
fill-rect-fb - Framebuffer with fill-rect optimization
list-box - List box widget example
msg-box - Message box example
plain-text - Plain text widget
grid-layout - Grid layout example
const-grid-layout - Compile-time grid layout

Run examples with:

cargo run --features part --example basic-example
cargo run --features anim --example anim-by-ui
cargo run --features popup,part --example msg-box

§License

This project is licensed under the MIT License - see the LICENSE-MIT file for details.

§Acknowledgments

Inspired by kolibri-embedded-gui
Built on top of embedded-graphics
Uses multi-mono-font for font rendering

§Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

§Support

For issues, questions, or suggestions, please open an issue on GitHub.

Modules§

animation: Animation subsystem for the matrix_gui framework.
fill_rect
helper: Helper utilities for the matrix_gui framework.
i18n: Internationalization (i18n) module for matrix_gui.
prelude: Matrix GUI Prelude
region: Region and layout management module for the matrix_gui framework.
style
ui: User Interface (UI) module for the matrix_gui framework.
ui_font
widget_state
widgets

Macros§

free_form_region: Creates a free-form region definition with multiple regions.
grid_layout_column_major: Creates a column-major grid layout with region IDs starting from 0.
grid_layout_column_major_with_start: Creates a column-major grid layout with region IDs starting from a specified value.
grid_layout_const_var: Creates constant variables for a grid layout.
grid_layout_row_major: Creates a row-major grid layout with region IDs starting from 0.
grid_layout_row_major_with_start: Creates a row-major grid layout with region IDs starting from a specified value.
i18n_string: Macro to define an internationalized string constant.
i18n_toggle_type: Macro to define a toggle type with internationalized string representations.
region_id: Creates a region ID enum starting from 0.
region_id_with_start: Creates a region ID enum with a specified starting value.
rgb565: Macro to create Rgb565 colors from 24-bit RGB values, eg. rgb565!(0xRRGGBB)
set_impl_fill_rect

Crate matrix_gui

Crate matrix_gui Copy item path

§matrix-gui

§Features

§Built-in Widgets

§Static Widgets

§Interactive Widgets (requires interaction feature)

§Screenshots

§Basic Example

§Plain Text Widget

§Message Box

§Grid Layout

§Getting Started

§Installation

§Basic Example

§Features

§Feature Overview

§Feature Details

§interaction

§focus

§animation

§popup

§framebuffer

§fill-rect

§debug-color

§Layout Tools

§Examples

§License

§Acknowledgments

§Contributing

§Support

Modules§

Macros§

Crate matrix_gui

§Interactive Widgets (requires `interaction` feature)

§`interaction`

§`focus`

§`animation`

§`popup`

§`framebuffer`

§`fill-rect`

§`debug-color`