v0.8.0

v0.8.0

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.

imgui-rs important 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++.

  • The most likely breaking changes users will see is 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.

Backends

• 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.

  • Removed automatically adding default features for 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.

Contributors

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:

• @thomcc for handling the majority of the backend's setup and keeping this project's ffi in order
• @dbr for not only doing the rest of the backend's setup, but also consistently PRing to fix thorny API problems
• @jmaargh for contributing the imgui-glow-renderer and being so deeply pleasant to code review
• @cfrantz for multiple contributions including fixing the ComboxBox and providing the basis for the tables-api
• @repi for pushing us to change how our winit-support works
• @dzil123 for making that winit support more comprehensible
• @toyboot4e for a truly heroic amount of Doc Alias commenting. Now you can search on docs.rs by C++ function names for the corresponding rust code
• @lwiklendt for adding input text hinting
• @AngelOfSol for allowing build methods to return a value. Additionally, thank you for contributing a PR for the input text callbacks
• @Jake-Shadle for fixing text input deletions, which let to fixing the input widgets (I hope) completely.
• @atouchet for fixing our readme
• @haenno for fixing up our example code
• @hpwxf for fixing some of our GFX examples
• and last but also latest, thank you to @davidpdrsn and @vojd, and really all of Embark Studios, for somehow both working at the same company and contributing nearly two identical PRs at the same time this morning. It made me chuckle.

If you have any issues with this release (and it's a big one), please file an issue!

• sanbox-irl (Jonathan Spira)

Full changelog

• Removed ImStr and ImString from the API. Currently im_str! is deprecated and will be removed in 0.9.0. To change your code:

  • If you were just wrapping a string literal, like im_str!("button"), just use "button". (Help: the regex im_str!\("((?:(?=(\\?))\2.)*?)"\), replacing matches with "$1", can get the majority of these quickly.);
  • If you were formatting, like &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++.

  • The most likely breaking changes users will see is 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:

  1. The tables API is marked as "beta" meaning that it may change with fewer stability promises. This is unlikely and it seems fairly settled.
  2. There are a few cases where the tables API will segfault by dereferencing a 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.

  • REMOVED .callback_name() methods in favor of one method: .callback(FLAGS, CallbackStruct).
  • Wrapped callback kinds into their own enums, InputTextCallback and InputTextCallbackMultiline.
  • Created a trait, InputTextCallbackHandler.
  • To see how to create an InputText callback, see examples/text_callback.rs.
  • Finally, please note that editing an &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.

  • Removed automatically adding default features for 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.

  • To update without changing behavior, use the range T::MIN and T::MAX for the given numerical type (such as i8::MIN and i8::MAX).
  • Using .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

  • The methods are add_image, add_image_quad, and add_image_rounded. The imgui-examples/examples/custom_textures.rs has been updated to show their usage.
  • Additionally the 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 equivalent
  • Finally, we have relaxed the limits around having multiple draw lists such that you can have multiple mutable draw lists of different kinds (ie, a foreground and a background at the same time.).
  • Thank you to @dbr for implementing these changes.

• 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)

  • The new methods on 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
  • For example 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 backend

• BREAKING: 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.

  • The most likely breaking changes users will see is that they will need to add semicolons after calling build, because these function no longer return ().
  • Thank you to @AngelOfSol for implementing this here.

• 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.

  • BREAKING: Some parts of the font atlas code now use char (or u32) instead of u16 to reflect this.
    • Note: u32 is used over char in some situations, such as when surrogates are allowed
  • BREAKING (sorta): Dear Imgui now will use 32 bits for character data internally. This impacts the ABI, including sizes of structs and such, and can break some low level or advanced use cases:
    • If you're linking against extensions or plugins to Dear Imgui not written in Rust, you need to ensure it is built using -DIMGUI_USE_WCHAR32.
      • However, if the DEP_IMGUI_DEFINE_ vars are used properly, this is non-breaking.
    • If you're using 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.
      • If you're using DEP_IMGUI_DEFINE_s for this already, then no change is needed.
    • If you're using .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.