Crate imgui_ext

A crate to quickly build imgui GUIs using a #[derive] macro.

Supported annotations

Annotations map to a subset of imgui types and methods:

Annotation	Mapped Imgui Types
slider(...)	SliderFloat, SliderFloat2, SliderFloat3, SliderFloat4, SliderInt, SliderInt2, SliderInt3, SliderInt4
drag(...)	DragFloat, DragFloat2, DragFloat3, DragFloat4, DragInt, DragInt2, DragInt3, DragInt4
input(...)	InputFloat, InputFloat2, InputFloat3, InputFloat4, InputInt, InputInt2, InputInt3, InputInt4
text(...)	InputText, InputTextMultiline
progress(...)	ProgressBar
image(...)	Image
color(...)	ColorButton, ColorPicker, ColorEdit
button(...)	Ui::button, Ui::small_button
checkbox(...)	Ui::checkbox
separator(...)	Ui::separator
new_line(...)	Ui::new_line
display(...)	Ui::label_text
bullet(...)	Ui::bullet_text, Ui::bullet
nested(...)

Basic usage

use imgui_ext::ImGuiExt;

// Make your type derive ImGuiExt and place annotations on the fields you want
// to include in the ui
#[derive(ImGuiExt)]
struct Example {
    #[imgui(slider(min = 0.0, max = 4.0))]
    x: f32,
    #[imgui(input(step = 2))]
    y: i32,
    #[imgui(drag(label = "Drag 2D"))]
    drag_2d: [f32; 2],

    #[imgui(
        checkbox(label = "Turbo mode"),
        display(label = "Is turbo enabled?"),
    )]
    turbo: bool,

    // not every field has to be annotated
    _not_in_ui: Vec<u8>
}

Input events

In immediate mode UI, generally you respond to user inputs (button presses, value changes, etc...) at the same time that you render the UI.

With imgui-ext, you have to first render the UI, and then check for these events:

use imgui_ext::prelude::*;
use imgui_ext::Events;

#[derive(ImGuiExt)]
struct Example {
    #[imgui(checkbox(label = "Checkbox"))]
    check: bool,
}

// init imgui (ui)...

// All events are stored as booleans in the returned type.
let events: Events<Example> = ui.imgui_ext(&mut example);

if events.check() {
    // Checkbox value has changes.
    // Do something...
}

In the above example, the checkbox event is mapped to the method check() of the type returned by the call to ui.imgui_ext(...). The name of the method is the same as the field. You can override this value by defining the catch parameter in the annotation:

use imgui_ext::prelude::*;
use imgui_ext::Events;

#[derive(ImGuiExt)]
struct Example {
    #[imgui(checkbox(label = "Checkbox", catch = "checkbox_event"))]
    check: bool,
}

// init imgui (ui)...

let events: Events<Example> = ui.imgui_ext(&mut example);

if events.checkbox_event() {
    // Do something...
}

Nice compiler errors

UI correctness is checked at compile time. If you mistype an annotation, the compiler will point you directly to the issue:

#[derive(ImGuiExt)]
struct Example {
    #[imgui(slider(min = 0.0))]
    foo: f32,
}

error: Parameter `max` missing.
  --> example/src/main.rs:10:13
   |
10 |     #[imgui(slider(min = 0.0))]
   |             ^^^^^^

Contributions

Feedback, suggestions, and contributions, are very much welcome!

Please file an issue or open a PR to germangb/imgui-ext if you wish to do so.

Re-exports

pub use imgui_ext_derive::ImGuiExt;

Modules

bullet	bullet(...) docs.
button	button(...) docs.
checkbox	checkbox(...) docs.
color	color(...) docs.
display	display(...) docs.
drag	drag(...) docs.
image	image(...) docs.
input	input(...) docs.
layout	Support for some (basic) layout annotations.
nested	nested(...) docs (used to build nested UIs).
prelude
progress	progress(...) docs.
slider	slider(...) docs.
text	text(...) docs.

Traits

ImGuiExt	Trait implemented by the derive macro.
UiExt	Extension trait for imgui Ui.

Functions

imgui_ext

Render imgui UI and collect all the events

Type Definitions

Events

Alias for the ImGuiExt::Events associated type.