Crate matrix_gui 

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: Lightweight, customizable, and low-footprint
• 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
• ScrollArea - Scrollable areas with drag interaction
• Choice - Popup selector (requires popup feature)
• MessageBox - Message dialogs (requires popup feature)

Screenshots

Basic Example

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

Plain Text Widget

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

Message Box

Modal dialog widget for displaying messages and user interactions.

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"

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

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
• choice-demo - Dropdown choice selector with modal popup
• scrollarea - Scrollable area with drag, wheel and keyboard scrolling
• 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
cargo run --features popup,part --example choice-demo
cargo run --features part --example scrollarea

Documents

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