diff --git a/CHANGELOG.markdown b/CHANGELOG.markdown index 2d722f9..00be28a 100644 --- a/CHANGELOG.markdown +++ b/CHANGELOG.markdown @@ -24,9 +24,11 @@ - Added `add_polyline` method to `DrawListMut`, which binds to Dear ImGui's `AddPolyline` and `AddConvexPolyFilled` -- BREAKING: The following structs have had their `new` method changed and deprecated; they now also take `ui` in their `new`, but you should create them on the `Ui` struct instead. These each now have a simple and a `_config` version: - - `MenuItem` should be made with `ui.menu_item` and `ui.menu_item_config`. - - `DragDropSource` and `DragDropTarget` should be made with `ui.drag_drop_source_config` and `ui.drag_drop_target`. Both of these methods, and the DragDrop API in general, are likely to change. +- BREAKING: The following structs have had their `new` method changed and deprecated; they now also take `ui` in their `new`, but you should create them on the `Ui` struct instead. + - `Window` should be made with `ui.window` - e.g `ui.window("My Window").build(|| { ui.text("Contents") });` + - `ChildWindow` should be made with `ui.child_window` + - `MenuItem` should be made with `ui.menu_item` or `ui.menu_item_config`. + - `DragDropSource` and `DragDropTarget` should be made with `ui.drag_drop_source_config` or `ui.drag_drop_target`. Both of these methods, and the DragDrop API in general, are likely to change. - Added `docking` feature which builds against the upstream docking branch. Only basic API is exposed currently, just enough to enable the docking `imgui_context.io_mut().config_flags |= imgui::ConfigFlags::DOCKING_ENABLE;` - API for programtically docking windows and so on will be added later. diff --git a/README.markdown b/README.markdown index 4cbc5bb..9b3eece 100644 --- a/README.markdown +++ b/README.markdown @@ -37,7 +37,7 @@ ui.window("Hello world") Additionally, the following are no longer maintained, but might work still: - imgui-gfx-renderer: Renderer implementation that uses the `gfx` crate (_not - the new gfx-hal crate_) + the new gfx-hal crate_). This can be found at [imgui-rs/imgui-gfx-renderer](https://github.com/imgui-rs/imgui-gfx-renderer) ## Features @@ -58,6 +58,8 @@ The MSRV for `imgui-rs` and all of the backend crates is **1.54**. We update our Almost every application that uses imgui-rs needs two additional components in addition to the main `imgui` crate: a backend platform, and a renderer. +**imgui-rs is not tied to any particular renderer or platform.** + The backend platform is responsible for integrating imgui-rs with the operating system and its window management. Its responsibilities include the following: @@ -74,26 +76,34 @@ responsibilities include the following: - Handling of DPI factors and scissor rects - Texture management +We provide the following renderers as an official source (ie, they will always be up to date and working): `imgui-glow-renderer` and `imgui-glium-renderer`. + +Additionally, we provide the following backends as an official source (ie, they will always be up to date and working): `imgui-winit-support` and `imgui-sdl2-support`. + The most tested platform/renderer combination is `imgui-glium-renderer` + -`glium` + `imgui-winit-support` + `winit`, but this is not the only possible -combination. There's also `imgui-glow-renderer`, which will increasingly replace -`glium`, and you can find additional 3rd party crates that provide a wider -support for more libraries (e.g. raw OpenGL, SDL2). You can also write your own -support code if you have a more advanced use case, because **imgui-rs is not tied to any specific graphics / OS API**. + `glium` + `imgui-winit-support` + `winit`, but this is not the only possible + combination. There's also `imgui-glow-renderer`, which will increasingly replace +`glium`. + +Additionally, there are other libraries which provide other kind sof renderers, which may be out of date with `imgui-rs` releases, but might work well for your use case: + + 1. [`imgui-wgpu`](https://github.com/Yatekii/imgui-wgpu-rs) + 2. [`imgui-d3d12-renderer`](https://github.com/curldivergence/imgui-d3d12-renderer) + 3. [`imgui-dx11-renderer`](https://github.com/veykril/imgui-dx11-renderer) + +You can also write your own support code if you have a more advanced use case, because **imgui-rs is not tied to any specific graphics / OS API**. ## Compiling and running the demos ```bash git clone https://github.com/imgui-rs/imgui-rs cd imgui-rs -git submodule update --init --recursive ``` -Main examples are located in the `imgui-examples` directory. +Main examples are located in the `imgui-examples` directory. These can be run like so: ```bash # At the reposity root -cd imgui-examples cargo test cargo run --example hello_world @@ -101,14 +111,13 @@ cargo run --example test_window cargo run --example test_window_impl ``` -Examples for the gfx backend are under the imgui-gfx-examples directory. +Examples for the Glow renderer are under the `imgui-glow-renderer/examples/` directory. +These can be run the same way as any other examples: ```bash -cd imgui-gfx-examples cargo test -cargo run --example gfx_hello_world -cargo run --example gfx_test_window +cargo run --example glow_01_basic ``` Note to Windows users: You will need to use the _MSVC ABI_ version of the Rust diff --git a/docs/upgrading-imgui.md b/docs/upgrading-imgui.md index 85aebbe..c707a1e 100644 --- a/docs/upgrading-imgui.md +++ b/docs/upgrading-imgui.md @@ -5,6 +5,7 @@ This document covers how to upgrade imgui-rs to a new version of the upstream C+ The process is much the same to build imgui-rs for a tagged release (as shown) as it is for any arbitrary revision (such as one on a different branch) ## Summary + In short, there are a few steps: 1. Update copy of imgui itself @@ -17,9 +18,9 @@ In short, there are a few steps: 1. Update the copies of `imgui` in `imgui-sys/third-party/imgui-*/imgui/` from the appropriate branches on [the upstream repo](https://github.com/ocornut/imgui) Each branch should generally be from roughly the same point in time. Generally just after each imgui release the `docking` branch is updated, so it's usually easy to find an equivalent commit in both. - + We trim some of the "unrequired" parts of imgui, such as it's `.github` directory, the `backends` and `docs`. We are mainly just interested in the main `.cpp` and `.h` files, as well as `misc/freetype/` support files. - + Note this step could benefit from some automation (maybe `cargo xtask update-imgui 1.99`) 2. Ensure `luajit` is installed, as this is required by cimgui's generator. @@ -69,7 +70,7 @@ In short, there are a few steps: ``` This requires bindgen to be installed (`cargo install bindgen` should do it) - + Be sure to check `bindgen --version` versus the previously used version which is recoded in the first line of `imgui-sys/src/bindings.rs` - if you use a different version, you may get slightly different bindings which could also cause an update to be more work than it would otherwise be with matching bindgen versions 6. Run `cargo build` and fix any errors caused by changes upstream (see next section) diff --git a/imgui-examples/examples/text_input.rs b/imgui-examples/examples/text_input.rs index c052de2..c755ed2 100644 --- a/imgui-examples/examples/text_input.rs +++ b/imgui-examples/examples/text_input.rs @@ -5,6 +5,7 @@ mod support; fn main() { let system = support::init(file!()); let mut stable_str = String::new(); + let mut callback_str = String::new(); system.main_loop(move |_, ui| { if let Some(_window) = ui @@ -22,6 +23,25 @@ fn main() { if ui.is_item_deactivated_after_edit() { dbg!(&per_frame_buf); } + + struct CB; + impl imgui::InputTextCallbackHandler for CB { + fn on_history( + &mut self, + _dir: imgui::HistoryDirection, + _data: imgui::TextCallbackData, + ) { + } + } + let changed = ui + .input_text("input callback", &mut callback_str) + .callback(InputTextCallback::HISTORY, CB) + .enter_returns_true(true) + .build(); + + if changed { + println!("{:?}", callback_str); + } } }); } diff --git a/imgui-glow-renderer/examples/01_basic.rs b/imgui-glow-renderer/examples/glow_01_basic.rs similarity index 100% rename from imgui-glow-renderer/examples/01_basic.rs rename to imgui-glow-renderer/examples/glow_01_basic.rs diff --git a/imgui-glow-renderer/examples/02_triangle.rs b/imgui-glow-renderer/examples/glow_02_triangle.rs similarity index 100% rename from imgui-glow-renderer/examples/02_triangle.rs rename to imgui-glow-renderer/examples/glow_02_triangle.rs diff --git a/imgui-glow-renderer/examples/03_triangle_gles.rs b/imgui-glow-renderer/examples/glow_03_triangle_gles.rs similarity index 100% rename from imgui-glow-renderer/examples/03_triangle_gles.rs rename to imgui-glow-renderer/examples/glow_03_triangle_gles.rs diff --git a/imgui-glow-renderer/examples/04_custom_textures.rs b/imgui-glow-renderer/examples/glow_04_custom_textures.rs similarity index 100% rename from imgui-glow-renderer/examples/04_custom_textures.rs rename to imgui-glow-renderer/examples/glow_04_custom_textures.rs diff --git a/imgui/src/lib.rs b/imgui/src/lib.rs index 11bd33d..08576fc 100644 --- a/imgui/src/lib.rs +++ b/imgui/src/lib.rs @@ -430,6 +430,7 @@ impl Ui { /// }; /// ``` pub fn window>(&self, name: Label) -> Window<'_, '_, Label> { + #[allow(deprecated)] Window::new(self, name) } @@ -438,6 +439,7 @@ impl Ui { /// Use child windows to begin into a self-contained independent scrolling/clipping /// regions within a host window. Child windows can embed their own child. pub fn child_window>(&self, name: Label) -> ChildWindow<'_> { + #[allow(deprecated)] ChildWindow::new(self, name) } diff --git a/imgui/src/window/child_window.rs b/imgui/src/window/child_window.rs index 1fc36bf..61384cb 100644 --- a/imgui/src/window/child_window.rs +++ b/imgui/src/window/child_window.rs @@ -22,6 +22,7 @@ pub struct ChildWindow<'ui> { impl<'ui> ChildWindow<'ui> { /// Creates a new child window builder with the str. #[doc(alias = "BeginChildID")] + #[deprecated(since = "0.9.0", note = "use ui.child_window(...) instead")] pub fn new(ui: &'ui Ui, name: impl AsRef) -> Self { let id = ui.new_id_str(name); Self::new_id(ui, id) diff --git a/imgui/src/window/content_region.rs b/imgui/src/window/content_region.rs index e9bef82..eecdedb 100644 --- a/imgui/src/window/content_region.rs +++ b/imgui/src/window/content_region.rs @@ -37,6 +37,7 @@ impl Ui { } #[doc(alias = "GetContentRegionWidth")] #[deprecated( + since = "0.9.0", note = "Removed in Dear ImGui 1.85, 'not very useful in practice' and can be done with window_content_region_min/_max" )] pub fn window_content_region_width(&self) -> f32 { diff --git a/imgui/src/window/mod.rs b/imgui/src/window/mod.rs index 90712e8..587c58a 100644 --- a/imgui/src/window/mod.rs +++ b/imgui/src/window/mod.rs @@ -184,6 +184,7 @@ pub struct Window<'ui, 'a, Label> { impl<'ui, 'a, Label: AsRef> Window<'ui, 'a, Label> { /// Typically created via [`Ui::window`] + #[deprecated(since = "0.9.0", note = "use ui.window(...) instead")] pub fn new(ui: &'ui Ui, name: Label) -> Self { Window { ui,