1.87: The event-based IO release!

Reading the changelog is a good way to keep up to date with the things Dear ImGui has to offer, and maybe will give you ideas of some features that you've been ignoring until now!

Homepage: https://github.com/ocornut/imgui Release notes: https://github.com/ocornut/imgui/releases Wiki: https://github.com/ocornut/imgui/wiki for bindings, extensions, links, etc. FAQ: https://www.dearimgui.org/faq/ Issues: https://github.com/ocornut/imgui/issues

Did you know? We have a Wiki! It has sections such as this Useful Extensions Gallery! 👌

📢 Got visual glitches with custom/old backend when using CTRL+Tab or Modal Windows? See 1.86 release note.

📢 EDIT 2022/02/21: A regression in 1.87 prevents direct access to legacy io.KeysDown[] array in certains situations (see #4921, now fixed in latest). IsKeyDown() function was not affected.

Thank you!

Special thanks to @rokups for their continued work on stuff that are still not visible e.g. regression tests. Special thanks to @thedmd for their contribution to this verison. Special thanks to @PathogenDavid for their continued contributions and helping with github answers.

Ongoing work on Dear ImGui is currently financially supported by companies such as:

• Platinum sponsors: Blizzard
• Double-chocolate sponsors: Supercell, Ubisoft

Huge thank you to all past and present supporters!

Dear ImGui is funded by your contributions and needs them right now. If your company uses Dear ImGui, consider reaching out. See Sponsors page for details.

TL;DR;

This is a rather "boring" release in the sense that the refactor are not super exciting per se, but they are going to enable quite a few good things. Backends for all platforms have been updated. Most of the IO API hadn't changed this 1.0!

• Revamped the way for backend submit data to ImGuiIO. Now using functions e.g. io.AddKeyEvent(). The vast majority of changes are backward compatible but you are encouraged to update your backends now. See full recap > #4921.
• Added full range of ImGuiKey values, making it possible to access keys in a backend-agnostic way and make it easier to share code (e.g. for third-party libraries using Dear ImGui).
• Most platfom backends have been reworked to submit events.
• Backward compatible: 99% of old backends (custom or standard) and app code will still work (but consider updating!)
• Fixed SDL and GLFW backends to submit translated keys (not same as characters) to facilitate using shortcuts with ImGuiKey values.
• Trickling input queue improve usability on very low framerate (e.g. <15 FPS).
• Variety of other fixes (popups, ctrl+tab).

Breaking Changes

(Suggestion: once in a while, add #define IMGUI_DISABLE_OBSOLETE_FUNCTIONS in your imconfig.h file to make sure you are not using to-be-obsoleted symbols.)

• Removed support for pre-C++11 compilers. We'll stop supporting VS2010. (#4537)
• Reworked IO mouse input API: (#4921, #4858) [@thedmd, @ocornut]
  • Added io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddMouseWheelEvent() functions, obsoleting writing directly to io.MousePos, io.MouseDown[], io.MouseWheel, etc.
  • This enable input queue trickling to support low framerates. (#2787, #1992, #3383, #2525, #1320)
  • For all new calls to IO functions, the Dear ImGui context should be bound/current.
• Reworked IO keyboard input API: (#4921, #2625, #3724) [@thedmd, @ocornut]
  • Added io.AddKeyEvent() function, obsoleting writing directly to io.KeyMap[], io.KeysDown[] arrays.
  • For keyboard modifiers, you must call io.AddKeyEvent() with ImGuiKey_ModXXX values, obsoleting writing directly to io.KeyCtrl, io.KeyShift etc.
  • Added io.SetKeyEventNativeData() function (optional) to pass native and old legacy indices.
  • Added full range of key enums in ImGuiKey (e.g. ImGuiKey_F1).
  • Added GetKeyName() helper function.
  • Obsoleted GetKeyIndex(): it is now unnecessary and will now return the same value.
  • All keyboard related functions taking 'nt user_key_index now take ImGuiKey key: IsKeyDown(), IsKeyPressed(), IsKeyReleased(), GetKeyPressedAmount().
  • Added io.ConfigInputTrickleEventQueue (defaulting to true) to disable input queue trickling.
  • Backward compatibility:
    • All backends updated to use new functions.
    • Old backends populating those arrays should still work!
    • Calling e.g. IsKeyPressed(MY_NATIVE_KEY_XXX) will still work! (for a while)
    • Those legacy arrays will only be disabled if #define IMGUI_DISABLE_OBSOLETE_KEYIO'is set in your imconfig. In a few versions, IMGUI_DISABLE_OBSOLETE_FUNCTIONS will automatically enable IMGUI_DISABLE_OBSOLETE_KEYIO, so this will be moved into the regular obsolescence path.
    • BREAKING: (unlikely) If your custom backend used ImGuiKey as mock native indices (e.g. io.KeyMap[ImGuiKey_A] = ImGuiKey_A`` this is a use case that will now assert and be breaking for your old backend. **- Transition guide:** **- IsKeyPressed(MY_NATIVE_KEY_XXX) -> useIsKeyPressed(ImGuiKey_XXX)`
    • IsKeyPressed(GetKeyIndex(ImGuiKey_XXX)) -> use `IsKeyPressed(ImGuiKey_XXX)
    • Backend writing to io.KeyMap[],KeysDown[] -> backend should call io.AddKeyEvent(), if legacy indexing is desired, call io.SetKeyEventNativeData()**
    • Basically the trick we took advantage of is that we previously only supported native keycode from 0 to 511, so ImGuiKey values can still express a legacy native keycode, and new named keys are all >= 512.
  • This will enable a few things in the future:
    • Access to portable keys allows for backend-agnostic keyboard input code. Until now it was difficult to share code using keyboard across project because of this gap. (#2625, #3724)
    • Access to full key ranges will allow us to develop a proper keyboard shortcut system. (#456)
    • `io.SetKeyEventNativeData() include native keycode/scancode which may later be exposed. (#3141, #2959)
• Reworked IO nav/gamepad input API and unifying inputs sources: (#4921, #4858, #787)
  • Added full range of ImGuiKey_GamepadXXXX enums (e.g. ImGuiKey_GamepadDpadUp, ImGuiKey_GamepadR2) to use with io.AddKeyEvent(), io.AddKeyAnalogEvent().
  • Added io.AddKeyAnalogEvent() function, obsoleting writing directly to io.NavInputs[] arrays.
• Renamed ImGuiKey_KeyPadEnter to ImGuiKey_KeypadEnter to align with new symbols. Kept redirection enum. (#2625)
• Removed support for legacy arithmetic operators (+,+-,*,/) when inputing text into a slider/drag. (#4917, #3184) This doesn't break any API/code but a feature that was accessible by end-users (which seemingly no one used). (Instead you may implement custom expression evaluators to provide a better version of this).
• Backends: GLFW: backend now uses glfwSetCursorPosCallback().
  • If calling ImGui_ImplGlfw_InitXXX with install_callbacks=true: nothing to do. is already done for you.
  • If calling ImGui_ImplGlfw_InitXXX with install_callbacks=false: you WILL NEED to register the GLFW callback using glfwSetCursorPosCallback() and forward it to the backend function ImGui_ImplGlfw_CursorPosCallback().
• Backends: SDL: Added SDL_Renderer* parameter to ImGui_ImplSDL2_InitForSDLRenderer(), so backend can call SDL_GetRendererOutputSize() to obtain framebuffer size valid for hi-dpi. (#4927) [@Clownacy]
• Commented out redirecting functions/enums names that were marked obsolete in 1.69, 1.70, 1.71, 1.72 (March-July 2019)
  • ImGui::SetNextTreeNodeOpen() -> use ImGui::SetNextItemOpen()
  • ImGui::GetContentRegionAvailWidth() -> use ImGui::GetContentRegionAvail().x
  • ImGui::TreeAdvanceToLabelPos() -> use ImGui::SetCursorPosX(ImGui::GetCursorPosX() + ImGui::GetTreeNodeToLabelSpacing());`
  • ImFontAtlas::CustomRect -> use ImFontAtlasCustomRect
  • ImGuiColorEditFlags_RGB/HSV/HEX -> use ImGuiColorEditFlags_DisplayRGB/HSV/Hex
• Platform IME: Removed io.ImeSetInputScreenPosFn() in favor of more flexible io.SetPlatformImeDataFn() for IME support. Because this field was mostly only ever used by Dear ImGui internally, not by backends nor the vast majority of user code, this should only affect a very small fraction for users who are already very IME-aware.
• Platform IME: Obsoleted void* io.ImeWindowHandle in favor of writing to void* ImGuiViewport::PlatformHandleRaw. This removes an incompatibility between 'master' and 'multi-viewports' backends and toward enabling better support for IME. Updated backends accordingly. Because the old field is set by existing backends, we are keeping it (marked as obsolete).

Other Changes

• IO: Added event based input queue API, which now trickles events to support low framerates. Previously the most common issue case (button presses in low framerates) was handled by backend. This is now handled by core automatically for all kind of inputs. (#4858, #2787, #1992, #3383, #2525, #1320) [@thedmd, @ocornut]
  • New IO functions for keyboard/gamepad: io.AddKeyEvent(), io.AddKeyAnalogEvent().
  • New IO functions for mouse: io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddMouseWheelEvent().
• IO: Unified key enums allow using key functions on key mods and gamepad values.
• Fixed CTRL+Tab into an empty window causing artifacts on the highlight rectangle due to bad reordering on ImDrawCmd.
• Fixed a situation where CTRL+Tab or Modal can occasionally lead to the creation of ImDrawCmd with zero triangles, which would makes the draw operation of some backends assert (e.g. Metal with debugging). (#4857)
• Popups: Fixed a regression crash when a new window is created after a modal on the same frame. (#4920) [@rokups]
• Popups: Fixed an issue when reopening a same popup multiple times would offset them by 1 pixel on the right. (#4936)
• Tables, ImDrawListSplitter: Fixed erroneously stripping trailing ImDrawList::AddCallback() when submitted in last column or last channel and when there are no other drawing operation. (#4843, #4844) [@hoffstadt]
• Tables: Fixed positioning of Sort icon on right-most column with some settings (not resizable + no borders). (#4918).
• Nav: Fixed gamepad navigation in wrapping popups not wrapping all the way. (#4365)
• Sliders, Drags: Fixed text input of values with a leading sign, common when using a format enforcing sign. (#4917)
• Demo: draw a section of keyboard in "Inputs > Keyboard, Gamepad & Navigation state" to visualize keys. [@thedmd]
• Platform IME: changed io.ImeSetInputScreenPosFn() to io.SetPlatformImeDataFn() API, now taking a ImGuiPlatformImeData structure which we can more easily extend in the future.
• Platform IME: moved io.ImeWindowHandle to GetMainViewport()->PlatformHandleRaw.
• Platform IME: add ImGuiPlatformImeData::WantVisible, hide IME composition window when not used. (#2589) [@actboy168]
• Platform IME: add ImGuiPlatformImeData::InputLineHeight. (#3113) [@liuliu]
• Platform IME: [windows] call ImmSetCandidateWindow() to position candidate window.
• Backends: GLFW: Pass localized keys (matching keyboard layout). Fix e.g. CTRL+A, CTRL+Z, CTRL+Y shortcuts. We are now converting GLFW untranslated keycodes back to translated keycodes in order to match the behavior of other backend, and facilitate the use of GLFW with lettered-shortcuts API. (#456, #2625)
• Backends: GLFW: Submit keys and key mods using io.AddKeyEvent(). (#2625, #4921)
• Backends: GLFW: Submit mouse data using io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddMouseWheelEvent() functions. (#4921)
• Backends: GLFW: Retrieve mouse position using glfwSetCursorPosCallback() + fallback when focused but not hovered/captured.
• Backends: GLFW: Submit gamepad data using io.AddKeyEvent()/AddKeyAnalogEvent() functions, stopped writing to io.NavInputs[]. (#4921)
• Backends: GLFW: Added ImGui_ImplGlfw_InstallCallbacks()/ImGui_ImplGlfw_RestoreCallbacks() helpers to facilitate user installing callbacks after iniitializing backend. (#4981)
• Backends: Win32: Submit keys and key mods using io.AddKeyEvent(). (#2625, #4921)
• Backends: Win32: Retrieve mouse position using WM_MOUSEMOVE/WM_MOUSELEAVE + fallback when focused but not hovered/captured.
• Backends: Win32: Submit mouse data using io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddMouseWheelEvent() functions. (#4921)
• Backends: Win32: Maintain a MouseButtonsDown mask instead of using ImGui::IsAnyMouseDown() which will be obsoleted.
• Backends: Win32: Submit gamepad data using io.AddKeyEvent()/AddKeyAnalogEvent() functions, stopped writing to io.NavInputs[]. (#4921)
• Backends: SDL: Pass localized keys (matching keyboard layout). Fix e.g. CTRL+A, CTRL+Z, CTRL+Y shortcuts. (#456, #2625)
• Backends: SDL: Submit keys and key mods using io.AddKeyEvent(). (#2625, #4921)
• Backends: SDL: Retrieve mouse position using SDL_MOUSEMOTION/SDL_WINDOWEVENT_LEAVE + fallback when focused but not hovered/captured.
• Backends: SDL: Submit mouse data using io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddMouseWheelEvent() functions. (#4921)
• Backends: SDL: Maintain a MouseButtonsDown mask instead of using ImGui::IsAnyMouseDown() which will be obsoleted.
• Backends: SDL: Submit gamepad data using io.AddKeyEvent()/AddKeyAnalogEvent() functions, stopped writing to io.NavInputs[]. (#4921)
• Backends: Allegro5: Submit keys and key mods using `io.AddKeyEvent(). (#2625, #4921)
• Backends: Allegro5: Submit mouse data using io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddMouseWheelEvent() functions. (#4921)
• Backends: OSX: Submit keys and key mods using io.AddKeyEvent(). (#2625, #4921)
• Backends: OSX: Submit mouse data using io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddMouseWheelEvent() functions. (#4921)
• Backends: OSX: Submit gamepad data using io.AddKeyEvent()/AddKeyAnalogEvent() functions, stopped writing to io.NavInputs[]. (#4921)
• Backends: OSX: Added basic Platform IME support. (#3108, #2598) [@liuliu]
• Backends: OSX: Fix Game Controller nav mapping to use shoulder for both focusing and tweak speed. (#4759)
• Backends: OSX: Fix building with old Xcode versions that are missing gamepad features. [@rokups]
• Backends: OSX: Forward keyDown/keyUp events to OS when unused by Dear ImGui.
• Backends: Android, GLUT: Submit keys and key mods using io.AddKeyEvent(). (#2625, #4921)
• Backends: Android, GLUT: Submit mouse data using io.AddMousePosEvent(), io.AddMouseButtonEvent(), io.AddMouseWheelEvent() functions. (#4921)
• Backends: OpenGL3: Fixed a buffer overflow in imgui_impl_opengl3_loader.h init (added in 1.86). (#4468, #4830) [@dymk] It would generally not have noticeable side-effect at runtime but would be detected by runtime checkers.
• Backends: OpenGL3: Fix OpenGL ES2 includes on Apple systems. [@rokups]
• Backends: Metal: Added Apple Metal C++ API support. Enable with #define IMGUI_IMPL_METAL_CPP in your imconfig.h file. (#4824, #4746) [@luigifcruz]
• Backends: Metal: Ignore ImDrawCmd where ElemCount == 0, which are normally not emitted by the library but can theoretically be created by user code manipulating a ImDrawList. (#4857)
• Backends: Vulkan: Added support for ImTextureID as VkDescriptorSet, add ImGui_ImplVulkan_AddTexture(). (#914) [@martty]
• Backends: SDL_Renderer: Fix texture atlas format on big-endian hardware (#4927) [@Clownacy]
• Backends: WebGPU: Fixed incorrect size parameters in wgpuRenderPassEncoderSetIndexBuffer() and wgpuRenderPassEncoderSetVertexBuffer() calls. (#4891) [@FeepsDev]

Other branches & Beta features!

The Docking and Multi-viewports features are available in the docking branch, they are in beta but actively maintained and being used by many teams already. Your continuous feedback is always appreciated.

Some of changes from 1.86 to 1.87 related to the docking branch (multi-viewport and docking features) include:

• Docking: Fixed a CTRL+TAB crash when aiming at an empty docked window. (#4792)
• Docking: Tabs use their own identifier instead of the Window identifier (this will invalidate some stored .ini data such as last selected tab, sorry!)
• Docking: Fixed size constraints not working on single window holding on a dock id (still doesn't work on docked windows).
• Docking: Fixed CTRL+TAB back into a docked window not selecting menu layer when no item are on main layer.
• Viewports, IO: Added io.AddMouseViewportEvent() function to queue hovered viewport change (when known by backend).
• Viewports: Relaxed specs for backend supporting ImGuiBackendFlags_HasMouseHoveredViewport: it is now optional for the backend to have to ignore viewports with the _NoInputs flag when calling io.AddMouseViewportEvent(). It is much better if they can (Win32 and GLFW 3.3+ backends can, SDL and GLFW 3.2 backends cannot, they are lacking data). A concrete example is: when dragging a viewport for docking, the viewport is marked with _NoInputs to allow us to pick the target viewports for docking. If the backend reports a viewport with _NoInputs when calling the io.AddMouseViewportEvent() function, then Dear ImGui will revert to its flawed heuristic to find the viewport under. By lowering those specs, we allow the SDL and more backend to support this, only relying on the heuristic in a few drag and drop situations rather that relying on it everywhere.
• Viewports: Fixed a CTRL+TAB crash with viewports enabled when the window list needs to appears in its own viewport (regression from 1.86). (#4023, #787)
• Viewports: Fixed active InputText() from preventing viewports to merge. (#4212)
• Backends: SDL: Added support for ImGuiBackendFlags_HasMouseHoveredViewport now that its specs have been lowered.
• (Breaking) Removed ImGuiPlatformIO::Platform_SetImeInputPos() in favor of newly standardized io.SetPlatformImeDataFn() function. Should not affect more than default backends.

There's a CMake branch/PR (#1713) if you prefer a traditional CMake integration over registering sources files in your own project. There's a premake5 branch if you prefer Visual Studio projects generated by premake.

Gallery

Below a selection of screenshots from Gallery threads...

@mamoniem: Mirage Engine (Vulkan/C++) with ImGuizmo extension and a modified version of the super pretty Cherry theme_ (https://www.youtube.com/watch?v=HOARyIFw-5c&list=PLTfMG1EpxB2fV11Qq9-GTl9wZ3BP82YUZ&index=14

slajerek: Retro Debugger has been released today! This is retro computers APIs host for debugging (but not only!), currently supporting Commodore 64 (Vice), Atari XL/XE (Atari800), and NES (NestopiaUE) https://github.com/slajerek/RetroDebugger/

@durswd: ImGradientHDR A gradient editor which supports color, alpha and intensity. https://github.com/effekseer/ImGradientHDR

@tksuoran I heard you liked ImGui so I put ImGui inside ImGui

@hnOsmium0001: imgui-command-palette is a Sublime Text/VSCode style command palette library implemented using C++17 standard library and ImGui._ https://github.com/hnOsmium0001/imgui-command-palette

A few debug tools used by Call of Duty: Shadows of Cold War (from this talk)

@foxnne: _Pixi I built a small pixel art editor for my own use, using Dear ImGui and written in Zig: https://github.com/foxnne/pixi

@arabine: Because the world needs another Wordle (in french, sorry), here is an ImGui version : Yes, you can make games in ImGui ! https://github.com/arabine/galaxie-de-mots

PS: Dear ImGui is funded by your contributions and needs them right now. If your company uses Dear ImGui, consider reaching out today to say hi! See Sponsors page for details.

PS.2: Scroll back up and read that changelog, it is useful!