Crate easy_imgui

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§

pub use cgmath;
pub use easy_imgui_sys;
pub use image;
pub use mint;

Modules§

style

Structs§

ArrowButton
BackendFlags
Button
ButtonFlags
Checkbox
Child
ChildFlags
CollapsingHeader
Color: A color is stored as a [r, g, b, a], each value between 0.0 and 1.0.
ColorEdit3
ColorEdit4
ColorEditFlags
ColorPicker3
ColorPicker4
Combo
ComboFlags
ConfigFlags
Context: The main ImGui context.
CurrentContext
CustomRectIndex: Identifier for a registered custom rectangle. Only the values obtained from the latest call to UiBuilder::build_custom_atlas are actually valid.
DragDropAcceptFlags
DragDropPayload: The payload of a drag&drop operation.
DragDropPayloadGetter: Helpar class to get the drag&drop payload.
DragDropPayloadSetter: Helper token class that allows to set the drag&drop payload, once.
DragDropSourceFlags
DragFloat
DragFloat2
DragFloat3
DragFloat4
DragInt
DragInt2
DragInt3
DragInt4
DrawFlags
FocusedFlags
FontAtlas
FontAtlasMut
FontAtlasPtr
FontGlyph
FontId: Identifier of a registered font. Only the values obtained from the latest call to UiBuilder::build_custom_atlas are actually valid.
FontInfo: A font to be fed to the ImGui atlas.
HoveredFlags
Id: A string that works as a widget identifier.
Image
ImageButton
ImageWithBg
Indent
InputFlags
InputFloat
InputFloat2
InputFloat3
InputFloat4
InputInt
InputInt2
InputInt3
InputInt4
InputOsString
InputText
InputTextFlags
InputTextHint
InputTextMultiline
InvisibleButton
ItemFlags
ItemId
ItemWidth
KeyChord: This is an ImGuiKey plus several ImGuiMods.
KeyMod
LblId: A string that works as both a label and identifier.
ListBox
ListClipper
Menu
MenuItem
MultiSelect
MultiSelectFlags
Popup
PopupContextItem
PopupContextVoid
PopupContextWindow
PopupFlags
PopupModal
ProgressBar
RadioButton
Selectable
SelectableFlags
SelectionBasicStorage: Simple multi-selection storage facility.
SelectionBasicStorageIter
SelectionBasicStorageWithCallback
SelectionExternalStorage: MultiSelectStorage that forwards the selection data to another place.
SelectionRequest
SizeCallbackData
SliderAngle
SliderFlags
SliderFloat
SliderFloat2
SliderFloat3
SliderFloat4
SliderInt
SliderInt2
SliderInt3
SliderInt4
SmallButton
TabBar
TabBarFlags
TabItem
TabItemFlags
TableColumnFlags
TableColumnSortSpec: Return type for Ui::table_get_sort_specs.
TableConfig
TableFlags
TableRowFlags
TextWrapPos
TextureId
TreeNode
TreeNodeFlags
Ui: Ui represents an ImGui frame that is being built.
Viewport
ViewportFlags
Window
WindowDrawList
WindowFlags

Enums§

ColorId
Cond
Dir
DragDropPayloadCond: This is a sub-set of Cond, only for drag&drop payloads.
FloatFormat: How to convert a float value to a string.
Key
MouseButton
MouseCursor
SelectionRequestType
SortDirection
StyleValue
StyleVar
TableBgTarget

Constants§

PAYLOAD_TYPE_COLOR_3F
PAYLOAD_TYPE_COLOR_4F

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§

ImGuiID
ImGuiSelectionUserData
Style
StyleColor
StyleColorF
Vector2: A type alias of the cgmath::Vector2<f32>.

Crate easy_imguiCopy item path