Rust bindings for Dear ImGui
Io::add_key_analog_event
for supporting analog key events such as gamepad sticks - PR #728
begin_popup_context_*
methods - PR #738
cc
by @SkiFire13 in https://github.com/imgui-rs/imgui-rs/pull/744
begin_popup_context_*
. by @rodrigorc in https://github.com/imgui-rs/imgui-rs/pull/738
Full Changelog: https://github.com/imgui-rs/imgui-rs/compare/v0.11.0...v0.12.0
OwnedDrawData
API for usage like multithreaded renderers - PR#721
copypasta
crate for clipboard handling, as it is more maintained - PR#715
Full Changelog: https://github.com/imgui-rs/imgui-rs/compare/v0.10.0...v0.11.0
Most notable change is the update from Dear ImGui 1.89.2 (previously was on v1.87). As it impacts the Rust bindings, the most significant change is the event based IO system, which is now used by the winit and sd2l support crates by default. As with the upstream change, this should be backwards compatible with old platform-support code (i.e no changes should be required), but updating to the new should be quite straight forward, might result in simpler code, and acts better at low frame rates (e.g when there are multiple mouse-clicks within one frame)
See the upstream changelogs for more details: 1.88, 1.89, 1.89.1, 1.89.2
The freetype feature should be easier to use on Windows by being able source freetype via vcpkg
(in addition to pkg-config
more typically used on Linux)
Finally, the examples have been rearranged to be more consistent, and hopefully easier to find. Mainly just all the crates now have an examples
folder (with the exception of the low-level imgui-sys
crate), and there is an example of how to use imgui-glium-renderer
which is consistent with imgui-glow-renderer
Thanks everyone for the PR's and the testing/feedback in the Issues section!
usize
and isize
by @Ararem in https://github.com/imgui-rs/imgui-rs/pull/693
Full Changelog: https://github.com/imgui-rs/imgui-rs/compare/v0.9.0...v0.10.0
Thanks everyone for your patience with this long overdue release!
There has been a good chunk of work done on imgui-rs since the last release. For a complete list, see the CHANGELOG.markdown
in the main repository
A few key changes:
Ui
The aim is to make the API more consistent and easier to discover functinality by having widgets be created consistently.
For example, previously a button was made by ui.button(...)
but a slider made by imgui::Slider::new(...).build(ui)
- meaning both appeared in different sections of the docs/auto-completion, so easy to miss. Now a slider is now made via ui.slider(...)
also
This means some commonly used widgets like Window
change - although a tiny bit tedious, it is hopefully a fairly stight-forward syntax change, which can be done with some search-and-replace (change imgui::Window::new(...)
to ui.window(...)
and remove the ui
argument from build)
This is still somewhat a work-in-progress (some items may still be created via separate builder structs), but the aim is to transition everything to Ui
The upstream docking branch is now available, enabled via the docking
feature. Higher-level, safe Rust bindings for this will come in a future release, for now these can be used via the imgui-sys
crate
Dear ImGui is now 1.86 - this isn't the latest release, but it was better to release now and get imgui-rs back to a more regular release cycle
Similarly there is updates to latest glium, winit
mint
equivalents by @sanbox-irl in https://github.com/imgui-rs/imgui-rs/pull/536
imgui-sdl2-support
crate. by @NightShade256 in https://github.com/imgui-rs/imgui-rs/pull/541
input_scalar
and allow setting float input precision by @EmbersArc in https://github.com/imgui-rs/imgui-rs/pull/544
winit
and glow
crates by @lovelymono in https://github.com/imgui-rs/imgui-rs/pull/676
Full Changelog: https://github.com/imgui-rs/imgui-rs/compare/v0.8.0...v0.9.0
Merry uh Boxing Day, here's another imgui-rs
patch.
docking
as a feature in imgui-rs
's features list to doc.rs
. This prevented our docs from building.Additionally, glow-renderer
ended up at 0.8.3 because someone messed up the intra-crate linking (i am someone)
Merry Christmas Eve, here's an imgui-rs
patch.
input_text
and input_text_multiline
. We are primarily releasing this patch to fix this issue.We'll see you all soon for v0.9.0, which will include a reworked main API (no more imgui::Window::new
) and the docking branch.
Welcome to the 0.8.0
update. This is one of the largest updates imgui-rs
has ever seen; it will generate errors in a 0.7
project, but hopefully it should be both quick to fix, and enjoyable to update.
Thank you to everyone who uses imgui-rs
, files issues, and spends their time and effort to PR new changes into the codebase. Because of all that effort, this is by far the best imgui-rs
has looked!
For more details, please see the full changelog below, which lists all of the (many) breaking changes.
ππ Removed ImStr and ImString from the API. ππ Currently im_str!
is deprecated and will be removed in 0.9.0.
Internally, this has been implemented using AsRef<str>
bounds across the codebase. I expect that this bound will change in such a manner to allow more expressions to be accepted. We then copy this str
into a buffer, appending a null byte, and give that to ImGui. In the nearer future, we will add a feature to instead use imgui's string_view
branch, which will allow us to avoid the internal buffer copy.
We have three new features in imgui
:
min-const-generics
is a default-feature
. Effectively, you can choose to ignore this feature to keep this crate valid on rustc 1.48
, but with the feature enabled, our MSRV is 1.54
. In 0.9.0
, this feature gate will be removed and we will commit to 1.54
and more common, minor, version bumps.freetype
enabled the Dear ImGui freetype
feature. See here for more info on its advantages.tables-api
enables the...tables api...which was introduced in Dear ImGui 1.80. I decided to place this behind a feature gate so that users know to opt into it. However, I would strongly encourage users to opt into it -- see here for more information on it.Most tokens through the repository (eg. WindowToken
, TabBarToken
, FontStackToken
, etc) now allow for permissive dropping -- i.e, you don't need to actually call the .end()
method on them anymore.
The best way to use these begin_x
functions is probably like so:
if let Some(_t) = ui.begin_popup("example") {
// your code here
}
As a minor note, if you just do if let Some(_)
or ui.begin_popup("example").is_some()
, you'll immediately drop the token, which of course, calls the corresponding end
function.
In the future, we may keep using closures, especially as we move onto Rust 2021.
We upgraded from v1.80 to Dear ImGui v1.84.2 See the Dear ImGui v1.84 release notes for more information on what has changed. Along with that, we have wrapped around begin_disabled
!
Most functions with C++ default parameters now have with_x
variants. This makes calling most functions simpler and more similar to the C++.
button
and same_line
now take one fewer parameter -- if you were calling button
with [0.0, 0.0]
, simply delete that -- otherwise, call button_with_size
. Similarly, for same_line
, if you were passing in 0.0.
simply delete that argument. Otherwise, call same_line_with_pos
.In addition to all the above, many other smaller, but important, changes were made this cycle. Please see the changelog as always.
Added an imgui-glow-renderer
which targets glow 0.10
. We haven't quite worked out some necessary kinks to get to 0.11
. (In fact, we will skip 0.11
entirely and be on glow 0.12
when that releases. Follow this branch here for more.)
Changed default version of Winit in imgui-winit-support
to winit 0.25
.
imgui-winit-support
with the exception of the current default winit feature/dep version. If you want to not have the default features of winit with 0.25, set default-features = false
and add winit-25
as a normal feature.Changed the version of glium
to 0.30
in imgui-glium-renderer
, as it now uses winit 0.25
.
Thank you to all of the contributors who have commented, made issues, and contributed code to imgui-rs
this cycle. The support of so many is what sustains this project. In no particular order, thank you to:
imgui-glow-renderer
and being so deeply pleasant to code reviewtables-api
winit-support
worksbuild
methods to return a value. Additionally, thank you for contributing a PR for the input text
callbacksIf you have any issues with this release (and it's a big one), please file an issue!
Removed ImStr and ImString from the API. Currently im_str!
is deprecated and will be removed in 0.9.0. To change your code:
im_str!("button")
, just use "button"
. (Help: the regex im_str!\("((?:(?=(\\?))\2.)*?)"\)
, replacing matches with "$1"
, can get the majority of these quickly.);&im_str!("My age is {}", 100)
, you can now just use format like format!("My age is {}, 100)
. Notice that due to the trait bounds, you can pass the string in directly too.BREAKING: Most tokens through the repository (eg. WindowToken
, TabBarToken
, FontStackToken
, etc) now allow for permissive dropping -- i.e, you don't need to actually call the .end()
method on them anymore. In exchange, these tokens have taken on a lifetime, which allows them to be safe. This could make some patterns impossible. Please file an issue if this causes a problem.
end()
no longer takes Ui
. This is a breaking change, but hopefully should be trivial (and perhaps nice) for users to fix. Simply delete the argument, or add a _
before the token's binding name and allow it to be dropped on its own. In our code, we tend to write these now like:if let Some(_t) = ui.begin_popup("example") {
// your code here
}
BREAKING: Created with_x
variants for most functions which previously took multiple parameters where some had default arguments in the C++. This makes calling most functions simpler and more similar to the C++.
button
and same_line
now take one fewer parameter -- if you were calling button
with [0.0, 0.0]
, simply delete that -- otherwise, call button_with_size
. Similarly, for same_line
, if you were passing in 0.0.
simply delete that argument. Otherwise, call same_line_with_pos
.ADDED: support for the tables
API which was added in dear imgui 1.80
. We currently have this feature gated behind tables-api
. You should feel safe to use this in stable production, but be aware of two things:
NULL
where it should instead ASSERT
and crash. This is simply annoying because you won't get a stacktrace. See here for more info on that.. If this is fixed upstream, we will issue a patch.ADDED: an imgui-glow-renderer
which targets glow 0.10
. Before release, this will be updated to target current 0.11
glow when further features are added. Thank you to @jmaargh for the work implementing this here!
UPGRADED: from v1.80 to Dear ImGui v1.84.2 See the Dear ImGui v1.84 release notes for more information. Thank you to @dbr for doing the work (twice actually) of upgrading the repository.
BREAKING: Reworked how callbacks on InputText
and InputTextMultiline
work.
.callback_name()
methods in favor of one method: .callback(FLAGS, CallbackStruct)
.InputTextCallback
and InputTextCallbackMultiline
.InputTextCallbackHandler
.examples/text_callback.rs
.&mut String
which contains \0
within it will produce surprising truncation within ImGui. If you need to edit such a string, please pre-process it.ADDED: begin_disable
and begin_enable
methods. These add (finally) support for disabling any widget. Thank you to @dbr for implementing this here.
BREAKING: MSRV is now 1.54. This is gives us access to min-const-generics, which we use in a few places, but will gradually use more. Because this is the first time we've bumped MSRV intentionally, we have added a new feature min-const-generics
, which is enabled by default. If you are pre-1.54, you can hang onto this update by disabling that feature. In our next update, this feature will be removed and we will commit to our MSRVs going forward. Thank you to @dbr for changing our CI infrastructure to support better MSRVs here.
BREAKING: Changed default version of Winit in imgui-winit-support
to winit 0.25
. Thank you to @repi for implementing this here.
imgui-winit-support
with the exception of the current default winit feature/dep version. If you want to not have the default features of winit with 0.25, set default-features = false
and add winit-25
as a normal feature. Thank you to @dzil123 for the work implementing this here!ADDED: Support for the freetype font rasterizer. Enabled by the non-default freetype
feature, e.g imgui = {version = "...", features=["freetype"]})
Thank you to @dbr for this work implementing this here.
ADDED: doc alias
support throughout the repository. You can now, inside the docs, search for imgui-rs
functions by their Dear ImGui
C++ names. For example, searching for InputText
will pull up Ui::input_text
. This was quite a lot of documentation and effort, so thank you to @toyboot4e for implementing this here.
ADDED: text hinting into InputText
. Thank you to @lwiklendt for implementing this here.
BREAKING: Reworked .range
calls on Slider
, VerticalSlider
, and Drag
to simply take two min and max values, and requires that they are provided in the constructor.
T::MIN
and T::MAX
for the given numerical type (such as i8::MIN
and i8::MAX
)..range
is still maintained for simplicity, but will likely be deprecated in 0.9 and removed in 0.10!DrawListMut
has new methods to draw images
add_image
, add_image_quad
, and add_image_rounded
. The imgui-examples/examples/custom_textures.rs
has been updated to show their usage.imgui::draw_list
module is now public, which contains the various draw list objects. While the add_*
methods are preferred, imgui::draw_list::Circle::new(&draw_list_mut, ...).build()
is equivalentforeground
and a background
at the same time.).ADDED: the ButtonFlags
which previously prevented invisible_button
from being usable. Thank you to @dbr for implementing this change here.
BREAKING: PopupModal
's new
was reworked so that it didn't take Ui
until build
was called. This is a breaking change if you were invoking it directly. Simply move your ui
call to build
or begin
.
BREAKING: Restored methods to access keyboard based on backend-defined keyboard map indexes. These allow access to most keys, not just those defined in the small subset of imgui::Keys
(note the available keys may be expanded in future by imgui PR #2625)
imgui::Ui
are is_key_index_down
, is_key_index_pressed
, is_key_index_pressed_no_repeat
, is_key_index_released
, is_key_index_released
ui.is_key_released(imgui::Key::A)
is same as ui.is_key_index_released(winit::events::VirtualKeyCode::A as i32)
when using the winit backendBREAKING: Modifies build
style methods to allow the provide closure to return a value. The build call will then return Some(value) if the closure is called, and None if it isn't.
build
, because these function no longer return ()
.BREAKING: Removed imgui::legacy
which contained the old style of flags. The remaining flags in imgui::legacy
have been updated to be consistent with other flags in the project.
imgui::legacy::ImGuiDragDropFlags
were accidentally not cleared when they were remade in drag_drop.rs
in v0.7.0.imgui::legacy::ImGuiInputTextFlags
is now imgui::input_widgets::InputTextFlags
imgui::legacy::ImGuiTreeNodeFlags
is now imgui::widget::tree::TreeNodeFlags
imgui::legacy::ImDrawListFlags
is now imgui::draw_list::DrawListFlags
Full (32-bit) unicode support is enabled in Dear Imgui (e.g. -DIMGUI_USE_WCHAR32
is enabled now). Previously UTF-16 was used internally.
char
(or u32
) instead of u16
to reflect this.
u32
is used over char
in some situations, such as when surrogates are allowed-DIMGUI_USE_WCHAR32
.
DEP_IMGUI_DEFINE_
vars are used properly, this is non-breaking.features="wasm"
to "link" against emscripten-compiled Dear Imgui, you need to ensure you use -DIMGUI_USE_WCHAR32
when compile the C and C++ code.
DEP_IMGUI_DEFINE_
s for this already, then no change is needed..cargo/config
to apply a build script override and link against a prebuilt Dear Imgui
(or something else along these lines), you need to ensure you link with a version that was built using -DIMGUI_USE_WCHAR32
.Upgrade to Dear ImGui v1.80. (Note that the new table functionality is not yet supported, however)
Ui::key_index()
is now called internally when needed, and the various is_key_foo
now take a Key
directly: https://github.com/imgui-rs/imgui-rs/pull/416
is_key_down
, is_key_pressed
, is_key_released
and key_pressed_amount
now take a Key
instead of u32
(breaking).key_index
is no longer public (breaking). If you need access to the key map, it can be accessed as ui.io().key_map[key]
(If you need to do this, file a bug, since I'm open to exposing this if there's actually a use case).winit
0.23/0.24 handling has been (hopefully) fixed: https://github.com/imgui-rs/imgui-rs/pull/420 (breaking, see also https://github.com/imgui-rs/imgui-rs/issues/412).
imgui-winit-support
's winit-23
feature no longer supports winit
version 0.24
(this caused an unintentional semver breakage in the imgui-winit-support
crate before, unfortunately).imgui-winit-support
has a new winit-24
feature for 0.24 support.imgui-winit-support
feature now enables winit-24
, and not winit-23
(by default it will always enable the latest).The imgui
crate no longer depends on gfx
or glium
directly: https://github.com/imgui-rs/imgui-rs/pull/420 (breaking, related to the previous change).
gfx
and glium
features are removed to reduce version compatibility issues going forward.
gfx
or glium
renderers without using the imgui-glium-renderer
or imgui-gfx-renderer
crates.imgui::DrawVert
, and replace calls to imgui::DrawList::vtx_buffer()
with imgui::DrawList::transmute_vtx_buffer::<MyDrawVert>()
. You can see imgui_glium_renderer::GliumDrawVert
and imgui_gfx_renderer::GfxDrawVert
types respectively for examples of this, if needed, but it should be straightforward enough if you're already implementing a renderer from scratch.gfx
or glium
in the core imgui
crate, which will ease maintenance and reduce unintentional breakage in the future.Non-window DrawList support has been fixed/improved: https://github.com/imgui-rs/imgui-rs/pull/414
WindowDrawList
has been renamed to DrawListMut
, to reflect that it may refer to other kinds of draw lists, and is mutable, unlike imgui::DrawList
(breaking).Ui::get_background_draw_list()
has been fixed when used outside of a window context, and now has an example.Ui::get_foreground_draw_list()
has been added, analogous to Ui::get_background_draw_list()
.Added drag drop support, with a safe and an unsafe variant: https://github.com/imgui-rs/imgui-rs/pull/428
DragDropSource
allows users to create a dragdrop payload which is either empty, of 'static + Copy
data,
or unsafe
, allowing for theoretically arbitrary payloads.DragDropTarget
allows users to accept any of the above payloads.ImColor
(which is a wrapper around u32
) has been renamed to ImColor32
in order to avoid confusion with the ImColor
type from the Dear ImGui C++ code (which is a wrapper around ImVec4
). In the future an ImColor
type which maps more closely to the C++ one will be added.
ImColor
, which are const fn
where possible.The im_str!
macro can now be used in const
contexts (when the format!
version is not used).
im_str!
now verifies that the parameter has no interior nuls at compile time. This can be avoided to get the old (truncating) behavior by forcing it to use the format!
-like version, e.g. im_str!("for_some_reason_this_should_be_truncated\0 there {}", "")
.
Many functions are now const fn
.
A large number of small functions are now #[inline]
, but many still aren't, so you probably will want to build with LTO for release builds if you use imgui
heavily.
The io.config_windows_memory_compact_timer
flag has been renamed to io.config_memory_compact_timer
. This follows the similar rename in the C++ ImGui, and was done because it no longer only applies to window memory usage.
The variants of ColorEditInputMode
and ColorEditDisplayMode
have been renamed to be CamelCase instead of upper case (e.g. ColorEditFooMode::RGB
=> ColorEditFooMode::Rgb
).
Ui::begin_tooltip
to support using tooltips with stack tokens instead
of closures