4 releases (2 breaking)

0.4.2	Jul 9, 2024
0.4.1	Apr 2, 2024
0.3.0	Nov 9, 2023
0.2.0	Oct 30, 2023

#1453 in Procedural macros

549 downloads per month
Used in egui_struct

MIT license

62KB
958 lines

EguiStruct

EguiStruct is a rust derive macro that creates egui UI's from arbitrary structs and enums. This is useful for generating data bindings that can be modified and displayed in an egui ui.

Crate idea is similar to crates egui-probe, enum2egui, egui_inspect and egui-controls, but there are some important differences:

EguiStruct vs similar crates

	EguiStruct	egui-probe	enum2egui	egui_inspect	egui-controls
egui version	0.26 (0.21-0.28) ****	0.27/0.28	0.23/0.24.1/0.26	0.20	N/A
Layout*	Grid	Grid	Group/nested	Nested	Grid
i18n support	✅ (rust-i18n**)	❌	❌	❌	❌
Field description	✅ on hover hint (from attribute)	❌	❌	❌	✅ third column (from doc comment)
Rename field/variant	✅	✅	✅/❌ (enum only)	❌	❌
Mass name case conversion	✅	✅	❌	❌	❌
Callback on-change	✅	❌	❌	❌	❌
Reset button	✅	❌	❌	❌	❌
Skip field	✅	✅	✅	✅	❌

Numerics & strings support	✅	✅	✅	✅	✅
Vec support	✅/❌ (does not support adding/removing elements)	✅ std, smallvec1/2	✅	✅	❌
Other support	✅ bool, Option, [T;N]	✅ bool, Option, [T;N], some of egui types	✅ bool, Option	✅ bool, [T;N]	❌
HashMap/Set support	✅ std, indexmap	✅ std, hashbrown	✅ std, hashbrown	❌	❌
Map field/override impl	✅	✅	❌	✅	❌
Struct derive	✅	✅	✅	✅	✅
Enum derive	✅	✅	✅	❌	❌
Custom types in derive	✅	✅	✅	✅	❌

Configuration numerics	✅ Slider(min,max), Slider(min,max,step), DragValue(min,max), DragValue, List	✅ DragValue(min,max), DragValue	❌	✅ Slider(min,max), DragValue	❌
Configuration string	✅ multi/singleline, List	✅ multi/singleline	❌	✅ multi/singleline	❌
Configuration user types	✅	❌	❌	❌	❌
Configuration others	❌	✅ Color32, bool, Enum(combobox or inline buttons), sets/vecs/maps	❌	❌	❌
List/Combobox wrapper	✅ ***	❌	❌	❌	❌

* Everything is put inside scroll&grid layout (with collapsable rows)

Gui is less chaotic,
all values are aligned,
Gui is comact in width

** integrated/with i18n in mind (with rust-i18n crate (or if using extractor modified rust-i18n))

*** Wrap T: Clone + ToString + PartialEq type into Combobox<T> and pass through config attribute iterator with all possible values → field will be shown as combobox

**** See section Usage >> egui version (EguiStruct supports all versions of egui through features; other crates support only "newest" one, support for other is by using legacy version)

Usage

Basic description

Add egui_struct to your Cargo.toml:

egui_struct = "0.4"

Add derive macro EguiStruct to struct you want to show (and all nested types):

#[derive(EguiStruct)]
pub struct TupleStruct(u8, u32, String, SubData);

then to show data, you only need to call show_top(..) on top level struct:

egui::CentralPanel::default().show(ctx, |ui| {
  data.show_top(ui, RichText::new("Data").heading(), None);
});

Detailed description

See docs.

Example

See ./demo

obraz

egui version

egui_struct 0.4 by default depends on egui 0.26. To use other versions of egui use correct feature in Cargo.toml, eg. to make it work with egui 0.28:

egui_struct = { version = "0.4", default-features = false, features = [ "egui28" ] }

OR use [patch] section.

Default egui version feature will be updated to newest egui on semver minor release(0.5).

TODO

elegant error/invalid input handling & helpful messages (macro)
- add bounds
tests
code cleanup & simplify
support adding/removing elements for Vec&Hashmap's
(requires specialization) EguiStructEq/EguiStructClone default impl

Dependencies

~1–1.5MB
~29K SLoC