Update binding API to Dear ImGui v1.76

Author: SpaiR

imgui-binding/src/main/java/imgui/ImFontGlyph.java

@@ -1,5 +1,9 @@
 package imgui;
 
+/**
+ * Hold rendering data for one glyph.
+ * (Note: some language parsers may fail to convert the 31+1 bitfield members, in this case maybe drop store a single u32 or we can rework this)
+ */
 public final class ImFontGlyph implements ImDestroyable {
     final long ptr;
 
@@ -48,15 +52,29 @@ public void destroy() {
     /**
      * 0x0000..0xFFFF
      */
-    public native short getCodepoint(); /*
-        return (short)IM_FONT_GLYPH->Codepoint;
+    public native int getCodepoint(); /*
+        return (unsigned int)IM_FONT_GLYPH->Codepoint;
     */
 
     /**
      * 0x0000..0xFFFF
      */
-    public native void setCodepoint(short codepoint); /*
-        IM_FONT_GLYPH->Codepoint = (ImWchar)codepoint;
+    public native void setCodepoint(int codepoint); /*
+        IM_FONT_GLYPH->Codepoint = (unsigned int)codepoint;
+    */
+
+    /**
+     * Flag to allow early out when rendering
+     */
+    public native int getVisible(); /*
+        return (unsigned int)IM_FONT_GLYPH->Visible;
+    */
+
+    /**
+     * Flag to allow early out when rendering
+     */
+    public native void setVisible(int visible); /*
+        IM_FONT_GLYPH->Visible = (unsigned int)visible;
     */
 
     /**

imgui-binding/src/main/java/imgui/ImGui.java

@@ -147,7 +147,7 @@ public static ImGuiIO getIO() {
     }
 
     /**
-     * Access the Style structure (colors, sizes). Always use PushStyleCol(), PushStyleVar() to modify style mid-frame.
+     * Access the Style structure (colors, sizes). Always use PushStyleCol(), PushStyleVar() to modify style mid-frame!
      */
     public static ImGuiStyle getStyle() {
         if (style == null) {
@@ -168,17 +168,17 @@ public static ImGuiStyle getStyle() {
     */
 
     /**
-     * Ends the Dear ImGui frame. automatically called by Render(), you likely don't need to call that yourself directly.
-     * If you don't need to render data (skipping rendering) you may call EndFrame() but you'll have wasted CPU already!
-     * If you don't need to render, better to not create any imgui windows and not call NewFrame() at all!
+     * Ends the Dear ImGui frame. automatically called by Render(). If you don't need to render data (skipping rendering) you may call EndFrame() without
+     * Render()... but you'll have wasted CPU already! If you don't need to render, better to not create any windows and not call NewFrame() at all!
      */
     public static native void endFrame(); /*
         ImGui::EndFrame();
     */
 
     /**
      * Ends the Dear ImGui frame, finalize the draw data.
-     * You can get call GetDrawData() to obtain it and run your rendering function.
+     * You can get call GetDrawData() to obtain it and run your rendering function (up to v1.60, this used to call io.RenderDrawListsFn().
+     * Nowadays, we allow and prefer calling your render function yourself.)
      */
     public static native void render(); /*
         ImGui::Render();
@@ -232,13 +232,17 @@ public static void showAboutWindow(ImBool pOpen) {
     */
 
     /**
-     * Create Metrics/Debug window.
+     * Create Debug/Metrics window.
      * Display Dear ImGui internals: draw commands (with individual draw calls and vertices), window list, basic internal state, etc.
      */
     public static native void showMetricsWindow(); /*
         ImGui::ShowMetricsWindow();
     */
 
+    /**
+     * Create Debug/Metrics window.
+     * Display Dear ImGui internals: draw commands (with individual draw calls and vertices), window list, basic internal state, etc.
+     */
     public static void showMetricsWindow(ImBool pOpen) {
         nShowMetricsWindow(pOpen.data);
     }
@@ -945,7 +949,7 @@ public static ImFont getFont() {
     // Parameters stacks (current window)
 
     /**
-     * Set width of items for common large "item+label" widgets. {@code > 0.0f}: width in pixels,
+     * Push width of items for common large "item+label" widgets. {@code > 0.0f}: width in pixels,
      * {@code <0.0f} align xx pixels to the right of window (so -1.0f always align width to the right side). 0.0f = default to ~2/3 of windows width,
      */
     public static native void pushItemWidth(float itemWidth); /*
@@ -972,16 +976,16 @@ public static ImFont getFont() {
     */
 
     /**
-     * Word-wrapping for Text*() commands. {@code < 0.0f}: no wrapping; 0.0f: wrap to end of window (or column); {@code > 0.0f}: wrap at 'wrap_posX'
-     * position in window local space
+     * Push Word-wrapping positions for Text*() commands. {@code < 0.0f}: no wrapping; 0.0f: wrap to end of window (or column); {@code > 0.0f}: wrap at
+     * 'wrap_posX' position in window local space
      */
     public static native void pushTextWrapPos(); /*
         ImGui::PushTextWrapPos();
     */
 
     /**
-     * Word-wrapping for Text*() commands. {@code < 0.0f}: no wrapping; 0.0f: wrap to end of window (or column); {@code > 0.0f}: wrap at 'wrap_posX'
-     * position in window local space
+     * Push Word-wrapping positions for Text*() commands. {@code < 0.0f}: no wrapping; 0.0f: wrap to end of window (or column); {@code > 0.0f}: wrap at
+     * 'wrap_posX' position in window local space
      */
     public static native void pushTextWrapPos(float wrapLocalPosX); /*
         ImGui::PushTextWrapPos(wrapLocalPosX);
@@ -1018,6 +1022,9 @@ public static ImFont getFont() {
     // - By "cursor" we mean the current output position.
     // - The typical widget behavior is to output themselves at the current cursor position, then move the cursor one line down.
     // - You can call SameLine() between widgets to undo the last carriage return and output at the right of the preceeding widget.
+    // - Attention! We currently have inconsistencies between window-local and absolute positions we will aim to fix with future API:
+    //    Window-local coordinates:   SameLine(), GetCursorPos(), SetCursorPos(), GetCursorStartPos(), GetContentRegionMax(), GetWindowContentRegion*(), PushTextWrapPos()
+    //    Absolute coordinate:        GetCursorScreenPos(), SetCursorScreenPos(), all ImDrawList:: functions.
 
     /**
      * Separator, generally horizontal. inside a menu bar or in horizontal layout mode, this becomes a vertical separator.
@@ -3568,7 +3575,8 @@ public static void listBox(String label, ImInt currentItem, String[] items, int
 
     // Widgets: Menus
     // - Use BeginMenuBar() on a window ImGuiWindowFlags_MenuBar to append to its menu bar.
-    // - Use BeginMainMenuBar() to create a menu bar at the top of the screen.
+    // - Use BeginMainMenuBar() to create a menu bar at the top of the screen and append to it.
+    // - Use BeginMenu() to create a menu. You can call BeginMenu() multiple time with the same identifier to append more items to it.
 
     /**
      * Append to menu-bar of current window (requires ImGuiWindowFlags_MenuBar flag set on parent window).
@@ -3881,7 +3889,7 @@ public static boolean beginPopupModal(String name, ImBool pOpen, int imGuiWindow
     // - You can also use SameLine(posX) to mimic simplified columns.
     // - The columns API is work-in-progress and rather lacking (columns are arguably the worst part of dear imgui at the moment!)
     // - There is a maximum of 64 columns.
-    // - Currently working on new 'Tables' api which will replace columns (see GitHub #2957)
+    // - Currently working on new 'Tables' api which will replace columns around Q2 2020 (see GitHub #2957).
 
     public static native void columns(); /*
         ImGui::Columns();
@@ -4108,7 +4116,7 @@ public static boolean beginTabItem(String label, ImBool pOpen, int imGuiTabBarFl
     */
 
     // Drag and Drop
-    // [BETA API] API may evolve!
+    // - [BETA API] API may evolve!
 
     /**
      * Call when the current item is active. If this return true, you can call SetDragDropPayload() + EndDragDropSource()
@@ -4427,26 +4435,6 @@ public static ImDrawList getForegroundDrawList() {
 
     // TODO SetStateStorage, GetStateStorage
 
-    public static native void calcTextSize(ImVec2 dstImVec2, String text); /*
-        ImVec2 src = ImGui::CalcTextSize(text);
-        Jni::ImVec2Cpy(env, src, dstImVec2);
-    */
-
-    public static native void calcTextSize(ImVec2 dstImVec2, String text, String textEnd); /*
-        ImVec2 src = ImGui::CalcTextSize(text, textEnd);
-        Jni::ImVec2Cpy(env, src, dstImVec2);
-    */
-
-    public static native void calcTextSize(ImVec2 dstImVec2, String text, String textEnd, boolean hideTextAfterDoubleHas); /*
-        ImVec2 src = ImGui::CalcTextSize(text, textEnd, hideTextAfterDoubleHas);
-        Jni::ImVec2Cpy(env, src, dstImVec2);
-    */
-
-    public static native void calcTextSize(ImVec2 dstImVec2, String text, String textEnd, boolean hideTextAfterDoubleHas, float wrapWidth); /*
-        ImVec2 src = ImGui::CalcTextSize(text, textEnd, hideTextAfterDoubleHas, wrapWidth);
-        Jni::ImVec2Cpy(env, src, dstImVec2);
-    */
-
     /**
      * Calculate coarse clipping for large list of evenly sized items. Prefer using the ImGuiListClipper higher-level helper if you can.
      */
@@ -4475,6 +4463,28 @@ public static ImDrawList getForegroundDrawList() {
         ImGui::EndChildFrame();
     */
 
+    // Text Utilities
+
+    public static native void calcTextSize(ImVec2 dstImVec2, String text); /*
+        ImVec2 src = ImGui::CalcTextSize(text);
+        Jni::ImVec2Cpy(env, src, dstImVec2);
+    */
+
+    public static native void calcTextSize(ImVec2 dstImVec2, String text, String textEnd); /*
+        ImVec2 src = ImGui::CalcTextSize(text, textEnd);
+        Jni::ImVec2Cpy(env, src, dstImVec2);
+    */
+
+    public static native void calcTextSize(ImVec2 dstImVec2, String text, String textEnd, boolean hideTextAfterDoubleHas); /*
+        ImVec2 src = ImGui::CalcTextSize(text, textEnd, hideTextAfterDoubleHas);
+        Jni::ImVec2Cpy(env, src, dstImVec2);
+    */
+
+    public static native void calcTextSize(ImVec2 dstImVec2, String text, String textEnd, boolean hideTextAfterDoubleHas, float wrapWidth); /*
+        ImVec2 src = ImGui::CalcTextSize(text, textEnd, hideTextAfterDoubleHas, wrapWidth);
+        Jni::ImVec2Cpy(env, src, dstImVec2);
+    */
+
     // Color Utilities
 
     public static native void colorConvertU32ToFloat4(long in, ImVec4 dstImVec4); /*
@@ -4722,7 +4732,8 @@ public static ImDrawList getForegroundDrawList() {
         ImGui::CaptureMouseFromApp(wantCaptureMouseValue);
     */
 
-    // Clipboard Utilities (also see the LogToClipboard() function to capture or output text data to the clipboard)
+    // Clipboard Utilities
+    // - Also see the LogToClipboard() function to capture GUI into clipboard, or easily output text data to the clipboard.
 
     public static native String getClipboardText(); /*
         return env->NewStringUTF(ImGui::GetClipboardText());

imgui-binding/src/main/java/imgui/ImGuiIO.java

@@ -649,66 +649,70 @@ void setClipboardTextStub(void* userData, const char* text) {
     */
 
     //------------------------------------------------------------------
-    // Output - Retrieve after calling NewFrame()
+    // Output - Updated by NewFrame() or EndFrame()/Render()
+    // (when reading from the io.WantCaptureMouse, io.WantCaptureKeyboard flags to dispatch your inputs, it is
+    //  generally easier and more correct to use their state BEFORE calling NewFrame(). See FAQ for details!)
     //------------------------------------------------------------------
 
     /**
-     * When io.WantCaptureMouse is true, imgui will use the mouse inputs, do not dispatch them to your main game/application (in both cases, always pass on mouse inputs to imgui).
+     * Set when Dear ImGui will use mouse inputs, in this case do not dispatch them to your main game/application
+     * (either way, always pass on mouse inputs to imgui).
      * (e.g. unclicked mouse is hovering over an imgui window, widget is active, mouse was clicked over an imgui window, etc.).
      */
     public native boolean getWantCaptureMouse(); /*
         return ImGui::GetIO().WantCaptureMouse;
     */
 
     /**
-     * When io.WantCaptureMouse is true, imgui will use the mouse inputs, do not dispatch them to your main game/application (in both cases, always pass on mouse inputs to imgui).
+     * Set when Dear ImGui will use mouse inputs, in this case do not dispatch them to your main game/application
+     * (either way, always pass on mouse inputs to imgui).
      * (e.g. unclicked mouse is hovering over an imgui window, widget is active, mouse was clicked over an imgui window, etc.).
      */
     public native void setWantCaptureMouse(boolean wantCaptureMouse); /*
         ImGui::GetIO().WantCaptureMouse = wantCaptureMouse;
     */
 
     /**
-     * When io.WantCaptureKeyboard is true, imgui will use the keyboard inputs, do not dispatch them to your main game/application (in both cases, always pass keyboard inputs to imgui).
-     * (e.g. InputText active, or an imgui window is focused and navigation is enabled, etc.).
+     * Set when Dear ImGui will use keyboard inputs, in this case do not dispatch them to your main game/application
+     * (either way, always pass keyboard inputs to imgui). (e.g. InputText active, or an imgui window is focused and navigation is enabled, etc.).
      */
     public native boolean getWantCaptureKeyboard(); /*
         return ImGui::GetIO().WantCaptureKeyboard;
     */
 
     /**
-     * When io.WantCaptureKeyboard is true, imgui will use the keyboard inputs, do not dispatch them to your main game/application (in both cases, always pass keyboard inputs to imgui).
-     * (e.g. InputText active, or an imgui window is focused and navigation is enabled, etc.).
+     * Set when Dear ImGui will use keyboard inputs, in this case do not dispatch them to your main game/application
+     * (either way, always pass keyboard inputs to imgui). (e.g. InputText active, or an imgui window is focused and navigation is enabled, etc.).
      */
     public native void setWantCaptureKeyboard(boolean wantCaptureKeyboard); /*
         ImGui::GetIO().WantCaptureKeyboard = wantCaptureKeyboard;
     */
 
     /**
-     * Mobile/console: when io.WantTextInput is true, you may display an on-screen keyboard.
-     * This is set by ImGui when it wants textual keyboard input to happen (e.g. when a InputText widget is active).
+     * Mobile/console: when set, you may display an on-screen keyboard.
+     * This is set by Dear ImGui when it wants textual keyboard input to happen (e.g. when a InputText widget is active).
      */
     public native boolean getWantTextInput(); /*
         return ImGui::GetIO().WantTextInput;
     */
 
     /**
-     * Mobile/console: when io.WantTextInput is true, you may display an on-screen keyboard.
-     * This is set by ImGui when it wants textual keyboard input to happen (e.g. when a InputText widget is active).
+     * Mobile/console: when set, you may display an on-screen keyboard.
+     * This is set by Dear ImGui when it wants textual keyboard input to happen (e.g. when a InputText widget is active).
      */
     public native void setWantTextInput(boolean wantTextInput); /*
         ImGui::GetIO().WantTextInput = wantTextInput;
     */
 
     /**
-     * MousePos has been altered, back-end should reposition mouse on next frame. Set only when ImGuiConfigFlags_NavEnableSetMousePos flag is enabled.
+     * MousePos has been altered, back-end should reposition mouse on next frame. Rarely used! Set only when ImGuiConfigFlags_NavEnableSetMousePos flag is enabled.
      */
     public native boolean getWantSetMousePos(); /*
         return ImGui::GetIO().WantSetMousePos;
     */
 
     /**
-     * MousePos has been altered, back-end should reposition mouse on next frame. Set only when ImGuiConfigFlags_NavEnableSetMousePos flag is enabled.
+     * MousePos has been altered, back-end should reposition mouse on next frame. Rarely used! Set only when ImGuiConfigFlags_NavEnableSetMousePos flag is enabled.
      */
     public native void setWantSetMousePos(boolean wantSetMousePos); /*
         ImGui::GetIO().WantSetMousePos = wantSetMousePos;
@@ -717,7 +721,7 @@ void setClipboardTextStub(void* userData, const char* text) {
     /**
      * When manual .ini load/save is active (io.IniFilename == NULL),
      * this will be set to notify your application that you can call SaveIniSettingsToMemory() and save yourself.
-     * IMPORTANT: You need to clear io.WantSaveIniSettings yourself.
+     * Important: clear io.WantSaveIniSettings yourself after saving!
      */
     public native boolean getWantSaveIniSettings(); /*
         return ImGui::GetIO().WantSaveIniSettings;
@@ -726,49 +730,53 @@ void setClipboardTextStub(void* userData, const char* text) {
     /**
      * When manual .ini load/save is active (io.IniFilename == NULL),
      * this will be set to notify your application that you can call SaveIniSettingsToMemory() and save yourself.
-     * IMPORTANT: You need to clear io.WantSaveIniSettings yourself.
+     * Important: clear io.WantSaveIniSettings yourself after saving!
      */
     public native void setWantSaveIniSettings(boolean wantSaveIniSettings); /*
         ImGui::GetIO().WantSaveIniSettings = wantSaveIniSettings;
     */
 
     /**
-     * Directional navigation is currently allowed (will handle ImGuiKey_NavXXX events) = a window is focused and it doesn't use the ImGuiWindowFlags_NoNavInputs flag.
+     * Keyboard/Gamepad navigation is currently allowed (will handle ImGuiKey_NavXXX events) = a window is focused
+     * and it doesn't use the ImGuiWindowFlags_NoNavInputs flag.
      */
     public native boolean getNavActive(); /*
         return ImGui::GetIO().NavActive;
     */
 
     /**
-     * Directional navigation is currently allowed (will handle ImGuiKey_NavXXX events) = a window is focused and it doesn't use the ImGuiWindowFlags_NoNavInputs flag.
+     * Keyboard/Gamepad navigation is currently allowed (will handle ImGuiKey_NavXXX events) = a window is focused
+     * and it doesn't use the ImGuiWindowFlags_NoNavInputs flag.
      */
     public native void setNavActive(boolean navActive); /*
         ImGui::GetIO().NavActive = navActive;
     */
 
     /**
-     * Directional navigation is visible and allowed (will handle ImGuiKey_NavXXX events).
+     * Keyboard/Gamepad navigation is visible and allowed (will handle ImGuiKey_NavXXX events).
      */
     public native boolean getNavVisible(); /*
         return ImGui::GetIO().NavVisible;
     */
 
     /**
-     * Directional navigation is visible and allowed (will handle ImGuiKey_NavXXX events).
+     * Keyboard/Gamepad navigation is visible and allowed (will handle ImGuiKey_NavXXX events).
      */
     public native void setNavVisible(boolean navVisible); /*
         ImGui::GetIO().NavVisible = navVisible;
     */
 
     /**
-     * Application framerate estimation, in frame per second. Solely for convenience. Rolling average estimation based on IO.DeltaTime over 120 frames
+     * Application framerate estimate, in frame per second. Solely for convenience. Rolling average estimation based on io.DeltaTime over 120 frames.
+     * Solely for convenience. Rolling average estimation based on IO.DeltaTime over 120 frames
      */
     public native float getFramerate(); /*
         return ImGui::GetIO().Framerate;
     */
 
     /**
-     * Application framerate estimation, in frame per second. Solely for convenience. Rolling average estimation based on IO.DeltaTime over 120 frames
+     * Application framerate estimate, in frame per second. Solely for convenience. Rolling average estimation based on io.DeltaTime over 120 frames.
+     * Solely for convenience. Rolling average estimation based on IO.DeltaTime over 120 frames
      */
     public native void setFramerate(float framerate); /*
         ImGui::GetIO().Framerate = framerate;
@@ -868,6 +876,13 @@ void setClipboardTextStub(void* userData, const char* text) {
         ImGui::GetIO().AddInputCharacter((unsigned int)c);
     */
 
+    /**
+     * Queue new character input from an UTF-16 character, it can be a surrogate
+     */
+    public native void addInputCharacterUTF16(short c); /*
+        ImGui::GetIO().AddInputCharacterUTF16((ImWchar16)c);
+    */
+
     /**
      * Queue new characters input from an UTF-8 string.
      */