Merge branch 'master' into drawimage

.github/workflows/ci.yml

@@ -130,6 +130,7 @@ jobs:
             ${{ runner.os }}-target-test-${{ matrix.rust }}-${{ hashFiles('**/Cargo.toml') }}
             ${{ runner.os }}-target-test-${{ matrix.rust }}-
       - run: cargo test --workspace --all-targets
+      - run: cargo test --workspace --doc
       # - run: cargo test --manifest-path imgui-gfx-examples/Cargo.toml --no-default-features --features directx
       #   if: runner.os == 'Windows'
       - run: cargo test --manifest-path imgui-winit-support/Cargo.toml --no-default-features --features winit-19

CHANGELOG.markdown

@@ -2,9 +2,11 @@
 
 ## [Unreleased]
 
-- Removed legacy `ImGuiDragDropFlags` from `legacy.rs`, which were accidentally not cleared when they were remade in `drag_drop.rs` in v0.7.0.
+- 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 parameter. Otherwise, call `same_line_with_pos`.
 
-- The remaining flags in `imgui::legacy` have been updated to be consistent with other flags in the project.
+- 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`
@@ -13,6 +15,13 @@
     - 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
 
+- 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.
+
+- 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`.
+
+- Upgrade to [Dear ImGui v1.81](https://github.com/ocornut/imgui/releases/tag/v1.81)
+    - BREAKING: `imgui::ListBox::calculate_size(items_count: ..., height_in_items: ...)` has been removed as the function backing it has been marked as obsolete. The recommended approach is to calculate the size yourself and use `.size(...)` (or use the default auto-calculated size)
 
 ## [0.7.0] - 2021-02-04
 

docs/upgrading-imgui.md

@@ -0,0 +1,89 @@
+# Updating to new imgui versions
+
+This document covers how to upgrade imgui-rs to a new version of the upstream C++ library.
+
+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)
+
+
+## Step by step
+
+1. Ensure the submodules are populated (`git submodule init` and `git submodule update --recursive`)
+
+2. Check out the desired version of the `imgui-sys/third-party/imgui/` submodule
+
+    $ pwd
+    .../imgui-sys/third-party/imgui
+    $ git checkout v1.81
+    Previous HEAD position was 58075c44 Version 1.80
+    HEAD is now at 4df57136 Version 1.81
+
+3. Ensure `luajit` is installed, as this is required by cimgui's generator.
+
+    $ luajit --help
+
+4. Check out the `cimgui` project somewhere, as we use use the generator within this
+
+    $ git clone --recursive https://github.com/cimgui/cimgui.git /tmp/cimgui
+
+5. Ensure the `imgui` submodule within `cimgui` is pointing to the same revision as in `imgui-rs`
+
+    $ cd /tmp/cimgui/imgui
+    $ git checkout v1.81
+    HEAD is now at 4df57136 Version 1.81
+
+6. Back in `imgui-rs/imgui-sys/third-party/` - run the `update-cimgui-output.sh` helper script to execute cimgui's generator
+
+    $ pwd
+    .../imgui-sys/third-party
+    $ ./update-cimgui-output.sh /tmp/cimgui/
+    [...]
+    copyfile	./output/cimgui.h	../cimgui.h
+    copyfile	./output/cimgui.cpp	../cimgui.cpp
+    all done!!
+
+  This updates various files in the imgui-sys folder like `cimgui.cpp`, `definitions.json` and so on
+
+  With this step, we now have new C bindings to the desired verison of Dear ImGui.
+
+7. Back in the root of the imgui-rs repo, run `cargo xtask bindgen`
+
+    $ cargo xtask bindgen
+        Finished dev [unoptimized + debuginfo] target(s) in 0.04s
+         Running `target/debug/xtask bindgen`
+    Executing bindgen [output = .../imgui-rs/imgui-sys/src/bindings.rs]
+    Success [output = .../imgui-rs/imgui-sys/src/bindings.rs]
+    Executing bindgen [output = .../imgui-rs/imgui-sys/src/wasm_bindings.rs]
+    Success [output = .../imgui-rs/imgui-sys/src/wasm_bindings.rs]
+
+  This requires bindgen to be installed (`cargo install bindgen` should do it)
+
+  This step generates `imgui-sys/src/bindings.rs` which is used by `imgui/src/*`
+
+8. Run `cargo build` and fix any errors from upstream.
+
+9. Run the tests with `cargo test`.
+
+10. Try running one of the examples
+
+    cargo run --example test_window_impl
+
+
+## Common sources of problems
+
+### Function changes
+
+Check the upstream imgui release notes for the new versions, as they detail any breaking changes.
+
+If functions have been renamed, the required changes to the bindings are usually simple.
+
+If functions have been removed, the changes are usually also simple but the implications may require some thought. Note by default `cimgui` generator will exclude any obsolete API.
+
+If new function overloads are added - for example `imgui::Thing()` existed but `imgui::Thing(float)` was added - `bindings.rs` will previously have contained only `igThing`, but will now contain `igThingNil()` and `igThingFloat(...)`
+
+### Memory layout changes
+
+It is common for upstream to add/remove/reorder fields, so the bindings will compile but the memory layout will not match - which will (hopefully) result in the bindings causing a segfault. These are not tagged as breaking changes in the release notes.
+
+The `*_memory_layout` tests when running `cargo test` should catch these (if they are created for every relevant struct!)
+
+The fix for this is usually to compare the struct in (read-only) `imgui-sys/src/bindings.rs` compared to the relevant struct in `imgui/src/...` - the ordering and data-types must match, but the names do not (structs in `imgui/src/...` should use conventional Rust naming/casing)

imgui-examples/examples/draw_list.rs

@@ -10,7 +10,7 @@ fn draw_text_centered(
     text: &ImStr,
     color: [f32; 3],
 ) {
-    let text_size = ui.calc_text_size(text, false, 0.0);
+    let text_size = ui.calc_text_size(text);
     let cx = (rect[2] - text_size[0]) / 2.0;
     let cy = (rect[3] - text_size[1]) / 2.0;
     draw_list.add_text([rect[0] + cx, rect[1] + cy], color, text);
@@ -54,7 +54,7 @@ fn main() {
             .size([300.0, 110.0], Condition::FirstUseEver)
             .scroll_bar(false)
             .build(ui, || {
-                ui.button(im_str!("random button"), [0.0, 0.0]);
+                ui.button(im_str!("random button"));
                 let draw_list = ui.get_window_draw_list();
                 let o = ui.cursor_screen_pos();
                 let ws = ui.content_region_avail();

imgui-examples/examples/multiple_fonts.rs

@@ -27,9 +27,9 @@ fn main() {
                 ui.text("Hello, I'm Roboto Regular!");
                 let _dokdo = ui.push_font(dokdo);
                 ui.text("Hello, I'm Dokdo Regular!");
-                _dokdo.pop(&ui);
+                _dokdo.pop();
                 ui.text("Hello, I'm Roboto Regular again!");
-                _roboto.pop(&ui);
+                _roboto.pop();
                 ui.text("Hello, I'm the default font again!");
             });
     });