Crate easy_imgui

Source
Expand description

Crate for easy integration of the Dear ImGui library.

This crate is a bind to the Dear ImGui library only. There is also a matching rendering library, easy-imgui-renderer, that renders the UI using OpenGl, and a matching window-integrated library, easy-imgui-window, that enables to build a full desktop application in just a few lines.

If you don’t know where to start, then start with the latter. Take a look at the examples. The simplest easy-imgui program would be something like this:

§A note about labels and ids.

In Dear ImGui, many controls take a string argument as both a label and an identifier. You can use ## or a ### as a separator between the label and the idenfifier if you want to make them apart.

In easy_imgui, since version 0.8, this is represented by the LblId type, not by a plain string.

If you want to keep on using the same type just write lbl("foo"), lbl("foo##bar") or "foo".into() and it will behave the same as before. But if you want to use them separately, you can write lbl_id("Label", "id") and it will join the two strings for you, separated by ###. This is particularly nice if you pretend to translate the UI: the labels change, but the ids should remain constant.

Some functions only take an id, no label. Those will take an argument of type Id, that you can construct with the function id, that will prepend the ### or raw_id to use the string as-is. Like before, you can also write "id".into() to behave as previous versions of this crate.

use easy_imgui_window::{
    easy_imgui as imgui,
    MainWindow,
    MainWindowWithRenderer,
    Application, AppHandler, Args, EventResult,
    winit,
};
use winit::{
    event_loop::{EventLoop, ActiveEventLoop},
    event::WindowEvent,
};

// The App type, this will do the actual app. stuff.
struct App;

// This trait handles the UI building.
impl imgui::UiBuilder for App {
    // There are other function in this trait, but this is the only one
    // mandatory and the most important: it build the UI.
    fn do_ui(&mut self, ui: &imgui::Ui<Self>) {
        ui.show_demo_window(None);
    }
}

// This trait handles the application & event loop stuff.
impl Application for App {
    // The user event type, `()` if not needed.
    type UserEvent = ();
    // Custom data type, `()` if not needed.
    type Data = ();

    // Create the app object.
    fn new(_: Args<()>) -> App {
        App
    }
    // Handle one window event.
    // There are a few other functions for other types of events.
    fn window_event(&mut self, args: Args<()>, _event: WindowEvent, res: EventResult) {
        if res.window_closed {
            args.event_loop.exit();
        }
    }
}

fn main() {
    // Create a `winit` event loop.
    let event_loop = EventLoop::new().unwrap();
    // Create an application handler.
    let mut main = AppHandler::<App>::default();
    // Optionally set up the window attributes.
    main.attributes().title = String::from("Example");
    // Run the loop
    event_loop.run_app(&mut main);
}

§Alternatives

This crate is similar to imgui-rs, and it is inpired by it, but with a few key differences:

  • It doesn’t use any C++-to-C api generator, as rust-bindgen is able to import simple C++ libraries directly.
  • It is lower level, there are fewer high-level abstractions over the ImGui API. This means that:
    • This API is less Rusty than imgui-rs’s.
    • If you know how to use Dear ImGui, then you know how to use easy-imgui.
    • It is far easier to upgrade to new Dear ImGui versions.

§Features

These are the available features for this crate:

  • freetype: Uses an external freetype font loader for Dear ImGui, instead of the embedded stb_truetype library.
  • docking: Uses the docking branch of Dear ImGui. Note that this is considered somewhat experimental.

§Usage

It is easier to use one of the higher level crates [easy-imgui-window] or [easy-imgui-renderer]. But if you intend to render the UI yourself, then you can use this directly.

These are the main pieces of this crate:

  • Context: It represents the ImGui context. In DearImgui this is a global variable. Here it is a thread-local variable. Still, since it is implicit in most API calls, most uses of this type are unsafe. If you use [easy-imgui-window] or [easy-imgui-renderer] you will rarely need to touch this type directly.
  • Ui: A frame that is being built. Most ImGui functions are members of Ui.
  • UiBuilder: A trait that your application implements do build your user interface.

If you want to use this library directly, just create a Context, set up its properties, and when you want to render a frame do Context::set_current and then CurrentContext::do_frame.

If you use one of the helper crates then you will just implement UiBuilder and get a Ui for free.

§Conventions

This crate follows a series of naming conventions to make the API more predictable, particularly with the Ui member functions:

  • A Pushable is any value that can be made active by a push function and inactive by a corresponding pop function. Examples are styles, colors, fonts…
  • A Hashable is any value that can be used to build an ImGui hash id. Ideally there should be one of these everywhere, but the Dear ImGui API it not totally othogonal here…
  • A function without special prefix or suffix does the same thing as its Dear ImGui counterpart. For example Ui::button calls ImGui_Button.
  • A function name that contains the with word takes a function that is called immediately. It corresponds to a pair of *Begin and *End functions in Dear ImGui. The function is called between these two functions. The value returned will be that of the function.
    • If the function is called based on some condition, such as with ImGui_BeginChild, then there will be another function with prefix with_always_ that takes a function with a bool argument opened: bool, that can be used if you need the function to be called even if the condition is not met.
  • A function name that ends as _config will create a builder object (with the must_use annotation). This object will have a few properties to be set and a build or a with function to create the actual UI element.
  • Most builder object have a push_for_begin function, that will set up the pushable to be used only for the begin part of the UI. This is useful for example to set up the style for a window but not for its contents.

When a function takes a value of type String this crate will usually take a generic impl IntoCStr. This is an optimization that allows you to pass either a String, a &str, a CString or a &CStr, avoiding an extra allocation if it is not really necessary. If you pass a constant string and have a recent Rust compiler you can pass a literal CStr with the new syntax c"hello".

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

  • Hashable
    Represents any type that can be converted to a Dear ImGui hash id.
  • IntoCStr
    Represents any type that can be converted into something that can be deref’ed to a &CStr.
  • MultiSelectStorage
    How the multi-select data will be stored.
  • Pushable
    Any value that can be applied with a push function and unapplied with a pop function.
  • UiBuilder
    The main trait that the user must implement to create a UI.

Functions§

  • id
    Uses the given string as an ImGui id.
  • im_to_v2
    Helper function to create a Vector2.
  • im_vec2
    Helper function to create a ImVec2.
  • lbl
    Uses the given string directly as an ImGui parameter that contains a label plus an id.
  • lbl_id
    Uses the first string as label, the second one as id.
  • raw_id
    Uses the given string as an ImGui id, without prepending ###.
  • to_v2
    Helper function to create a Vector2.
  • v2_to_im
    Helper function to create a ImVec2.
  • vec2
    Helper function to create a Vector2.

Type Aliases§