Ammerhai/Mikemon
2
0
Fork 0
Code Issues 8 Pull Requests Packages Projects 2 Releases 1 Wiki Activity

update dear imgui from 1.92.6-docking to 1.92.7-docking

Browse Source
This commit is contained in:
Sven Balzer
2026-04-02 20:22:14 +02:00
parent b549728a24
commit 85d1832a0c
40 changed files with 1823 additions and 1130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libs/imgui/docs/CHANGELOG.txt
+215 -34
View File
@@ -35,6 +35,187 @@ HOW TO UPDATE?
and API updates have been a little more frequent lately. They are documented below and in imgui.cpp and should not affect all users.
- Please report any issue!
-----------------------------------------------------------------------
VERSION 1.92.7 (Released 2026-04-02)
-----------------------------------------------------------------------
Decorated log and release notes: https://github.com/ocornut/imgui/releases/tag/v1.92.7
Breaking Changes:
- Separator: fixed a legacy quirk where `Separator()` was submitting a zero-height
item for layout purpose, even though it draws a 1-pixel separator.
The fix could affect code e.g. computing height from multiple widgets in order to
allocate vertical space for a footer or multi-line status bar. (#2657, #9263)
The "Console" example had such a bug:
float footer_height = style.ItemSpacing.y + ImGui::GetFrameHeightWithSpacing();
BeginChild("ScrollingRegion", { 0, -footer_height });
Should be:
float footer_height = style.ItemSpacing.y + style.SeparatorSize + ImGui::GetFrameHeightWithSpacing();
BeginChild("ScrollingRegion", { 0, -footer_height });
When such idiom was used and assuming zero-height Separator, it is likely that
in 1.92.7 the resulting window will have unexpected 1 pixel scrolling range.
- Multi-Select: renamed `ImGuiMultiSelectFlags_SelectOnClick` to `ImGuiMultiSelectFlags_SelectOnAuto`.
Kept inline redirection enum (will obsolete).
- Combo(), ListBox(): commented out legacy signatures which were obsoleted in 1.90
(Nov 2023), when the getter callback type was changed from:
bool (*getter)(void* user_data, int idx, const char** out_text)
To:
const char* (*getter)(void* user_data, int idx)
Other Changes:
- TreeNode:
- Moved `TreeNodeGetOpen()` helper to public API. I was hesitant to make this public
because I intend to provide a more generic and feature-full version, but in the meanwhile
this will do. (#3823, #9251, #7553, #6754, #5423, #2958, #2079, #1947, #1131, #722)
- In 'Demo->Property Editor' demonstrate a way to perform tree clipping by fast-forwarding
through non-visible chunks. (#3823, #9251, #6990, #6042)
Using SetNextItemStorageID() + TreeNodeGetOpen() makes this notably easier than
it was prior to 1.91.
- InputText:
- Shift+Enter in multi-line editor always adds a new line, regardless of
`ImGuiInputTextFlags_CtrlEnterForNewLine` being set or not. (#9239)
- Reworked `io.ConfigInputTextEnterKeepActive` mode so that pressing Enter will
deactivate/reactivate the item in order for e.g. `IsItemDeactivatedAfterEdit()`
signals to be emitted the same way regardless of that setting. (#9001, #9115)
- Fixed a glitch when using `ImGuiInputTextFlags_ElideLeft` where the local x offset
would be incorrect during the deactivation frame. (#9298)
- Fixed a crash introduced in 1.92.6 when handling `ImGuiInputTextFlags_CallbackResize`
in certain situations. (#9174)
- Fixed selection highlight Y1 offset being very slightly off (since 1.92.3). (#9311) [@v-ein]
- InputTextMultiline: fixed an issue introduced in 1.92.3 where line count calculated
for vertical scrollbar range would be +1 when the widget is inactive, word-wrap is
disabled and the text buffer ends with '\n'. Fixed a similar issue related to clipping
large amount of text.
- InputTextMultiline: avoid going through reactivation code and fixed losing revert value
when activating scrollbar.
- InputTextMultiline: fixed an issue where edit buffer wouldn't be reapplied to back
buffer on the `IsItemDeactivatedAfterEdit()` frame. This could create issues when
using the idiom of not applying edits before `IsItemDeactivatedAfterEdit()`.
(#9308, #8915, #8273)
- Tables:
- Allow reordering columns by dragging them in the context menu. (#9312)
- Context menu now presents columns in display order. (#9312)
- Fixed and clarified the behavior of using `TableSetupScrollFreeze()` with columns>1,
and where some of the columns within that range were Hidable.
- Before: `TableSetupScrollFreeze(N, 0)`: include the N left-most visible columns as
part of the scroll freeze. So if you intentionally hide columns <N, the scroll
freeze area would start covering the subsequent/following columns (N+1) etc.
- After: `TableSetupScrollFreeze(N, 0)`: include the N left-most columns (regardless of visibility),
part of the scroll freeze. So if you intentionally hide columns <N, the scroll as
freeze area will cover less columns.
- This is generally more sane and logical.
- Fixed dragging a header to reorder outside of visible bounds (due to horizontal scrolling)
from losing active id.
- Angled Headers: angled section for column being reordered via the regular headers
stays highlighted during reordering.
- Style:
- Fonts: fixed an issue introduced in 1.92.6 where `style.FontBaseSize` would be
cleared during the first frame if no fonts was explicitly added before.
- Border sizes are now scaled (and rounded) by `ScaleAllSizes()`.
- When using large values with `ScallAllSizes()`, the following items thickness
are scaled to integer amounts:
- `InputText()` caret/cursor thickness. (#7031)
- `CloseButton()` thickness.
- `TextLink()` underline thickness.
- `ColorButton()` border thickness.
- `Separator()` thickness, via scaling newly added `style.SeparatorSize`. (#2657, #9263)
- Nav:
- Popups: Shift+F10 or Menu key can now open popups menus when using
`BeginPopupContextItem()`, `BeginPopupContextWindow()` or `OpenPopupOnItemClick()`.
(#8803, #9270) [@exelix11, @ocornut]
- Changed Gamepad mapping for "Activate with Text Input" action: (#8803, #787)
- Previously: press North button (PS4/PS5 triangle, Switch X, Xbox Y).
- Now: long press (hold) Activate button (PS4/PS5 cross, Switch B, Xbox A) for ~0.60 secs.
This is rarely used, somehow easier to discover, and frees a button for other uses.
See updated Gamepad Control Sheets: https://www.dearimgui.com/controls_sheets
- Short Gamepad Activation press on InputText() always activate with Text Input mode.
- Popups: pressing North button (PS4/PS5 triangle, SwitchX, Xbox Y) also open popups menus.
- Multi-Select:
- Added `ImGuiMultiSelectFlags_SelectOnClickAlways` mode (rarely used).
This prevents Drag and Drop of multiple items, but it allows to start a new Box-Selection
from inside an existing selection (Excel style). (#9307, #1861)
- Clipper:
- Clear `DisplayStart`/`DisplayEnd` fields when `Step()` returns false.
- Added `UserIndex` helper storage. This is solely a convenience for cases where
you may want to carry an index around.
- Always pulls current context on `ImGuiListClipper::Begin()`, consistent with public
API design, and avoids issues with clipper instances outliving contexts. (#9324, #5856)
- Scrollbar:
- Implemented a custom tweak to extend hit-testing bounding box when window is sitting
at the edge of a viewport (e.g. fullscreen or docked window), so that e.g. mouse the
mouse at the extreme of the screen will reach the scrollbar. (#9276)
- Fixed an issue which could lead initial click to move the current scroll by a pixel.
- Button:
- Moved `ImGuiButtonFlags_AllowOverlap` from imgui_internal.h to imgui.h,
as a convenience for when using e.g. `InvisibleButton()`.
- Focus: fixed fallback "Debug" window temporarily taking focus and setting `io.WantCaptureKeyboard`
for one frame on e.g. application boot if no other windows are submitted. (#9243)
- DrawList:
- PathArcTo(): fixed erroneous segment count for pathologically small arcs on large
circles. (#9331, #9313) [@thedmd, @epajarre]
- Memory:
- Discard/GC of ImDrawList buffers for unused windows favor restoring them to
~Size*1.05 instead of Capacity when awakening again. Facilitate releasing ImDrawList
buffers after unusual usage spike. (#9303)
- Fixed `GetForegroundDrawList()`/`GetBackgroundDrawList()` per-viewport buffers not being
collected when unused for `io.ConfigMemoryCompactTimer` amount of time. (#9303)
- Demo: fixed `IMGUI_DEMO_MARKER` locations for examples applets. (#9261, #3689) [@pthom]
- Misc: added missing ImVec2/ImVec4 operators. (#9339, #8258) [@dkosmari, @ArashPartow]
- Internals:
- ButtonBehavior: fixed internal/low-level `ImGuiButtonFlags_PressedOnRelease`
(as well as equivalent `ImGuiSelectableFlags_SelectOnRelease` for Selectable) from
not taking current active id. `ImGuiButtonFlags_NoHoldingActiveID` allows that.
This was only used internally by MenuItem().
- Backends:
- DirectX9, OpenGL2, OpenGL3, Metal, SDLGPU3, SDLRenderer2, SDLRenderer3: fixed easy-to-fix
issues in code assuming ImTextureID_Invalid is always defined to 0. (#9295, #9310)
- GLFW: mouse cursor is properly restored if changed by user app/code while using
`glfwSetInputMode(..., GLFW_CURSOR_DISABLED)` or `ImGuiConfigFlags_NoMouseCursorChange`.
Amend optimization done in 1.92.6.
- SDLGPU3: removed unnecessary call to `SDL_WaitForGPUIdle()` when releasing
vertex/index buffers. (#9262) [@jaenis]
- WebGPU: fixed version check for Emscripten 5.0.0+.
- WebGPU: removed support for Emscripten <4.0.10. (#9281) [@ypujante]
- WebGPU: added support for WGVK native backend via `IMGUI_IMPL_WEBGPU_BACKEND_WGVK`,
using SPIRV shaders if WGSL is not available. (#9316, #9246, #9257) [@r-lyeh]
(WGVK is a lightweight alternative to Dawn or WGPU for native applications,
which is easier to build/setup, see: https://github.com/manuel5975p/WGVK)
- Examples:
- Emscripten: added `tabindex=-1` to canvas in our shell_minimal.htm. Without it,
the canvas was not focusable in the DOM, which in turn make some backends
(e.g. pongasoft/emscripten-glfw) not receive focus loss events. (#9259) [@pthom]
- Emscripten: fixed minor rendering issues with our HTML shell. (#9281) [@ypujante]
- hidden small blue outline when canvas is focused on Chrome.
- hidden scrollbar in Firefox.
- Vulkan: added `ImGui_ImplVulkan_PipelineInfo::ExtraDynamicStates[]` to allow specifying
extra dynamic states to add when creating the VkPipeline. (#9211) [@DziubanMaciej]
- Vulkan: `ImGui_ImplVulkan_AddTexture()` skips updating descriptor_set if failing
to allocate one. (#8677) [@micb25]
- WebGPU: fixed undefined behaviors in example code for requesting adapter
and device. (#9246, #9256) [@r-lyeh]
- SDL2+WebGPU: fixed hi-dpi handling. (#9300) [@ypujante]
- GLFW/SDL2/SDL3+WebGPU: added support for WGVK. (#9316, #9246, #9257) [@r-lyeh, @ocornut]
- GLFW/SDL2/SDL3+WebGPU: removed support for Emscripten <4.0.10. (#9281) [@ypujante]
Docking+Viewports Branch:
- Viewports:
- Fixed an issue where the implicit "Debug" window would erroneously be targetted for
mouse inputs while hidden if (1) the implicit "Debug" window was used in a previous
session and moved to a secondary viewport and (2) the Platform Backend does not
support the ImGuiBackendFlags_HasMouseHoveredViewport feature. (#9254)
- Backends: SDL2, SDL3: fixed an issue dated 2025/04/09 (1.92 WIP) where a refactor
and a merge caused ImGuiBackendFlags_HasMouseHoveredViewport to never be set, causing
foreign windows to be ignored when deciding of hovered viewport. (#9284) [@ravencgg]
- Backends: SDL3: use SDL_HAS_EVENT_DISPLAY_USABLE_BOUNDS_CHANGED (SDL 3.4.0+) when
available to avoid refreshing monitor work area every frame on Windows. (#8415)
- Backends: Win32: fixed setting/getting correct size when viewports have OS decorations
enabled (e.g. io.ConfigViewportsNoDecoration = false) and process is running in
Per-Monitor V2 DPI mode. (#8897) [@lailoken]
-----------------------------------------------------------------------
VERSION 1.92.6 (2026-02-17)
-----------------------------------------------------------------------
@@ -44,46 +225,46 @@ Decorated log and release notes: https://github.com/ocornut/imgui/releases/tag/v
Breaking Changes:
- Fonts:
- AddFontDefault() now automatically selects an embedded font between:
- AddFontDefaultBitmap(): classic pixel-clean font. Recommended at Size 13px with no scaling.
- AddFontDefaultVector(): new scalable font. Recommended at any higher size.
- `AddFontDefault()` now automatically selects an embedded font between:
- `AddFontDefaultBitmap()`: classic pixel-clean font. Recommended at Size 13px with no scaling.
- `AddFontDefaultVector()`: new scalable font. Recommended at any higher size.
- The default selection is based on (style.FontSizeBase * FontScaleMain * FontScaleDpi)
reaching a small threshold, but old codebases may not set any of them properly.
As as a result, it is likely that old codebase may still default to AddFontDefaultBitmap().
- Prefer explicitly calling either of them based on your own logic!
You can call AddFontDefaultBitmap() to ensure legacy behavior.
You can call `AddFontDefaultBitmap()` to ensure legacy behavior.
- Fixed handling of `ImFontConfig::FontDataOwnedByAtlas = false` which did
erroneously make a copy of the font data, essentially defeating the purpose
of this flag and wasting memory (undetected since July 2015 and now spotted
by @TellowKrinkle, this is perhaps the oldest bug in Dear ImGui history,
albeit for a rarely used feature!) (#9086, #8465)
HOWEVER, fixing this bug is likely to surface bugs in user/app code:
- Prior to 1.92, font data only needs to be available during the atlas->AddFontXXX() call.
Since 1.92, font data needs to available until atlas->RemoveFont(), or more typically
- Prior to 1.92, font data only needs to be available during the `atlas->AddFontXXX()` call.
Since 1.92, font data needs to available until `atlas->RemoveFont()`, or more typically
until a shutdown of the owning context or font atlas.
- The fact that handling of `FontDataOwnedByAtlas = false` was broken bypassed
the issue altogether.
- Removed ImFontConfig::PixelSnapV added in 1.92 which turns out is unnecessary
(and misdocumented). Post-rescale GlyphOffset is always rounded.
- Popups: changed compile-time 'ImGuiPopupFlags popup_flags = 1' default value to be '= 0' for
BeginPopupContextItem(), BeginPopupContextWindow(), BeginPopupContextVoid(), OpenPopupOnItemClick().
- Removed `ImFontConfig::PixelSnapV` added in 1.92 which turns out is unnecessary
(and was mis-documented). Post-rescale `GlyphOffset` is always rounded.
- Popups: changed compile-time `ImGuiPopupFlags popup_flags = 1` default value to be `= 0` for
`BeginPopupContextItem()`, `BeginPopupContextWindow()`, `BeginPopupContextVoid()`, `OpenPopupOnItemClick()`.
The default value has same meaning before and after. (#9157, #9146)
- Before this version, those functions had a 'ImGuiPopupFlags popup_flags = 1' default
- Before this version, those functions had a `ImGuiPopupFlags popup_flags = 1` default
value in their function signature. This was introduced by a change on 2020/06/23 (1.77)
while changing the signature from 'int mouse_button' to 'ImGuiPopupFlags popup_flags'
while changing the signature from `int mouse_button` to `ImGuiPopupFlags popup_flags`
and trying to preserve then-legacy behavior.
- We have now changed this behavior to: cleanup a very old API quirk, facilitate use by
bindings, and to remove the last and error-prone non-zero default value. Also because we
deemed it extremely rare to use those helper functions with the Left mouse button!
As using the LMB would generally be triggered via another widget,
e.g. a Button() + a OpenPopup()/BeginPopup() call.
- Before: The default = 1 means ImGuiPopupFlags_MouseButtonRight.
Explicitly passing a literal 0 means ImGuiPopupFlags_MouseButtonLeft.
- After: The default = 0 means ImGuiPopupFlags_MouseButtonRight.
Explicitly passing a literal 1 also means ImGuiPopupFlags_MouseButtonRight
- Before: The default = 1 means `ImGuiPopupFlags_MouseButtonRight`.
Explicitly passing a literal 0 means `ImGuiPopupFlags_MouseButtonLeft`.
- After: The default = 0 means `ImGuiPopupFlags_MouseButtonRight`.
Explicitly passing a literal 1 also means `ImGuiPopupFlags_MouseButtonRight`.
(if legacy behavior are enabled) or will assert (if legacy behavior are disabled).
- TL;DR: if you don't want to use right mouse button for popups, always specify it
explicitly using a named ImGuiPopupFlags_MouseButtonXXXX value.
explicitly using a named `ImGuiPopupFlags_MouseButtonXXXX` value.
Recap:
- BeginPopupContextItem("foo"); // Behavior unchanged (use Right button)
- BeginPopupContextItem("foo", ImGuiPopupFlags_MouseButtonLeft); // Behavior unchanged (use Left button)
@@ -93,11 +274,11 @@ Breaking Changes:
- BeginPopupContextItem("foo", 0); // !! Behavior changed !! Was Left button. Now will defaults to Right button! --> Use ImGuiPopupFlags_MouseButtonLeft.
- BeginPopupContextItem("foo", ImGuiPopupFlags_NoReopen); // !! Behavior changed !! Was Left button + flags. Now will defaults to Right button! --> Use ImGuiPopupFlags_MouseButtonLeft | xxx.
- Commented out legacy names obsoleted in 1.90 (Sept 2023):
- BeginChildFrame() --> BeginChild() with ImGuiChildFlags_FrameStyle flag.
- EndChildFrame() --> EndChild().
- ShowStackToolWindow() --> ShowIDStackToolWindow().
- IM_OFFSETOF() --> offsetof().
- IM_FLOOR() --> IM_TRUNC() [internal, for positive values only]
- `BeginChildFrame()` --> `BeginChild()` with `ImGuiChildFlags_FrameStyle` flag.
- `EndChildFrame()` --> `EndChild()`.
- `ShowStackToolWindow()` --> `ShowIDStackToolWindow()`.
- `IM_OFFSETOF()` --> `offsetof()`.
- `IM_FLOOR()` --> `IM_TRUNC()` [internal, for positive values only]
- Hashing: handling of "###" operator to reset to seed within a string identifier
doesn't include the "###" characters in the output hash anymore:
Before: `GetID("Hello###World") == GetID("###World") != GetID("World")`
@@ -106,11 +287,11 @@ Breaking Changes:
identifiers using "###", and will allow fixing other dangling issues.
- This will invalidate hashes (stored in .ini data) for Tables and Windows
that are using the "###" operators. (#713, #1698)
- Renamed helper macro IM_ARRAYSIZE() -> IM_COUNTOF(). Kept redirection/legacy name.
- Renamed helper macro `IM_ARRAYSIZE()` -> `IM_COUNTOF()`. Kept redirection/legacy name.
- Backends:
- Vulkan: optional ImGui_ImplVulkanH_DestroyWindow() helper used by our example
code does not call vkDestroySurfaceKHR(): because surface is created by caller
of ImGui_ImplVulkanH_CreateOrResizeWindow(), it is more consistent. (#9163)
- Vulkan: optional `ImGui_ImplVulkanH_DestroyWindow()` helper used by our example
code does not call `vkDestroySurfaceKHR()`: because surface is created by caller
of `ImGui_ImplVulkanH_CreateOrResizeWindow()`, it is more consistent. (#9163)
Other Changes:
@@ -128,22 +309,22 @@ Other Changes:
- The font data was carefully subsetted, trimmed and compressed so the embedded
data is ~14 KB. Embedding a scalable default font ensures that Dear ImGui can
be easily and readily used in all contexts, even without file system access.
- Expect minor fixes/improvements in following releases.
- As always you can opt-out of the embedded font data if desired.
- `AddFontDefault()` now automatically selects an embedded font between
the classic pixel-looking one and the new scalable one.
Prefer calling `AddFontDefaultVector()` or `AddFontDefaultBitmap()` explicitely.
Prefer calling `AddFontDefaultVector()` or `AddFontDefaultBitmap()` explicitly.
- Fixed a crash when trying to use `AddFont()` with `MergeMode==true` on a font that
has already been rendered. (#9162) [@ocornut, @cyfewlp]
- Fixed an issue where using `PushFont()` from the implicit/fallback "Debug" window
when its recorded state is collapsed would incorrectly early out. This would break
e.g. using direct draw-list calls such as GetForegroundDrawList() with current font.
e.g. using direct draw-list calls such as `GetForegroundDrawList()` with current font.
(#9210, #8865)
- Fixed an issue related to `EllipsisChar` handling, while changing
font loader or font loader flags dynamically in Style->Fonts menus.
- imgui_freetype: fixed overwriting `ImFontConfig::PixelSnapH` when hinting
is enabled, creating side-effects when later disabling hinting or
dynamically switching to stb_truetype rasterizer.
- Post rescale `ImFontConfig::GlyphOffset` is always rounded.
- Adding new fonts after removing all fonts mid-frame properly updates current state.
- Textures:
- Fixed a building issue when `ImTextureID` is defined as a struct.
@@ -154,7 +335,7 @@ Other Changes:
- Made navigation into menu-bar auto wrap on X axis. (#9178)
- TreeNode:
- Fixed highlight position when used inside a line with a large text baseline offset.
(never quite worked in this situation; but then most of the time the text
(it never quite worked in this situation; but then most of the time the text
baseline offset ends up being zero or `FramePadding.y` for a given line).
- Tables:
- Fixed an issue where a very thin scrolling table would advance parent layout
@@ -180,7 +361,7 @@ Other Changes:
- ImGuiInputTextCallbackData: Added `ID` and `EventActivated` members. (#9174)
- Text, InputText:
- Reworked word-wrapping logic:
- Try to not wrap in the middle of contiguous punctuations. (#8139, #8439, #9094)
- Try to not wrap in the middle of contiguous punctuation. (#8139, #8439, #9094)
- Try to not wrap between a punctuation and a digit. (#8503)
- Inside `InputTextMultiline()` with WordWrap enabled: prefer keeping blanks at
the end of a line rather than at the beginning of next line. (#8990, #3237)
@@ -198,7 +379,7 @@ Other Changes:
effectively making those actions faster on macOS/iOS retina screens.
(changed this to use a style scale factor that's not fully formalized yet)
- Fixed an UBSan warning when using in a `ImGuiListClipper` region . (#9160)
- Scrollbar: fixed a codepath leading to a divide-by-zero (which would not be
- Scrollbar: fixed a code-path leading to a divide-by-zero (which would not be
noticeable by user but detected by sanitizers). (#9089) [@judicaelclair]
- InvisibleButton: allow calling with size (0,0) to fit to available content
size. (#9166, #7623)
@@ -219,7 +400,7 @@ Other Changes:
- Shortcuts:
- IsItemHovered() without `ImGuiHoveredFlags_AllowWhenBlockedByActiveItem`
doesn't filter out the signal when activated item is a shortcut remote activation;
(which mimicks what's done internally in the `ItemHoverable()` function). (#9138)
(which mimics what's done internally in the `ItemHoverable()` function). (#9138)
- Fixed tooltip placement being affected for a frame when located over an item
activated by `SetNextItemShortcut()`. (#9138)
- Error Handling:
@@ -257,7 +438,7 @@ Other Changes:
- But you can also configure your system or debugger to automatically release
mouse grab when crashing/breaking in debugger, e.g.
- console: `setxkbmap -option grab:break_actions && xdotool key XF86Ungrab`
- or use a GDB script to call SDL_CaptureMouse(false). See #3650.
- or use a GDB script to call `SDL_CaptureMouse(false)`. See #3650.
- On platforms other than X11 this is unnecessary.
- SDL_GPU3: added `SamplerNearest` in `ImGui_ImplSDLGPU3_RenderState`.
- SDL_GPU3: macOS version can use MSL shaders in order to support macOS 10.14+
libs/imgui/docs/FAQ.md
+99 -24
View File
@@ -25,7 +25,7 @@ or view this file with any Markdown viewer.
| [I integrated Dear ImGui in my engine and some elements are clipping or disappearing when I move windows around...](#q-i-integrated-dear-imgui-in-my-engine-and-some-elements-are-clipping-or-disappearing-when-i-move-windows-around) |
| [I integrated Dear ImGui in my engine and some elements are displaying outside their expected windows boundaries...](#q-i-integrated-dear-imgui-in-my-engine-and-some-elements-are-displaying-outside-their-expected-windows-boundaries) |
| **Q&A: Usage** |
| **[About the ID Stack system..<br>Why is my widget not reacting when I click on it?<br>Why is the wrong widget reacting when I click on one?<br>How can I have widgets with an empty label?<br>How can I have multiple widgets with the same label?<br>How can I have multiple windows with the same label?](#q-about-the-id-stack-system)** |
| **[About the ID Stack system...](#q-about-the-id-stack-system)**<br>**[How can I have multiple widgets with the same label?](#q-how-can-i-have-multiple-widgets-with-the-same-label) (using `##` or `PushID()`)**<br>**[How can I have widgets with an empty label?](#q-how-can-i-have-widgets-with-an-empty-label) (using `##`)**<br>**[How can I animate the label of an existing widget?](#q-how-can-i-change-the-label-of-an-existing-widget) (using `###`)**<br>**[General description of the label and ID Stack system.](#general-description-of-the-label-and-id-stack-system)** |
| [How can I display an image?](#q-how-can-i-display-an-image)<br>[What are ImTextureID/ImTextureRef?](#q-what-are-imtextureidimtextureref)|
| [How can I use maths operators with ImVec2?](#q-how-can-i-use-maths-operators-with-imvec2) |
| [How can I use my own maths types instead of ImVec2/ImVec4?](#q-how-can-i-use-my-own-maths-types-instead-of-imvec2imvec4) |
@@ -55,6 +55,7 @@ or view this file with any Markdown viewer.
- Handy [Getting Started](https://github.com/ocornut/imgui/wiki/Getting-Started) guide to integrate Dear ImGui in an existing application.
- 20+ standalone example applications using e.g. OpenGL/DirectX are provided in the [examples/](https://github.com/ocornut/imgui/blob/master/examples/) folder to explain how to integrate Dear ImGui with your own engine/application. You can run those applications and explore them.
- See demo code in [imgui_demo.cpp](https://github.com/ocornut/imgui/blob/master/imgui_demo.cpp) and particularly the `ImGui::ShowDemoWindow()` function. The demo covers most features of Dear ImGui, so you can read the code and see its output.
- See pthom's online [imgui_explorer](https://pthom.github.io/imgui_explorer) which is a web version of the demo with a source code browser.
- See documentation: [Backends](https://github.com/ocornut/imgui/blob/master/docs/BACKENDS.md), [Examples](https://github.com/ocornut/imgui/blob/master/docs/EXAMPLES.md), [Fonts](https://github.com/ocornut/imgui/blob/master/docs/FONTS.md).
- See documentation and comments at the top of [imgui.cpp](https://github.com/ocornut/imgui/blob/master/imgui.cpp) + general API comments in [imgui.h](https://github.com/ocornut/imgui/blob/master/imgui.h).
- The [Glossary](https://github.com/ocornut/imgui/wiki/Glossary) page may be useful.
@@ -262,15 +263,19 @@ ctx->RSSetScissorRects(1, &r);
# Q&A: Usage
### Q: About the ID Stack system...
### Q: Why is my widget not reacting when I click on it?
### Q: Why is the wrong widget reacting when I click on one?
### Q: How can I have widgets with an empty label?
### Q: How can I have multiple widgets with the same label?
### Q: How can I have multiple windows with the same label?
## Q: About the ID Stack system...
**USING THE SAME LABEL+ID IS THE MOST COMMON USER MISTAKE!**
<br>**USING AN EMPTY LABEL IS THE SAME AS USING THE SAME LABEL AS YOUR PARENT WIDGET!**
<br>Read the questions in this section for a more general understand of how labels and ID works in Dear ImGui.
TL;DR;
- Widgets labels are also used to compute Widgets unique identifiers.
- Unique identifiers are hashes of the label + of the parent scope (e.g. parent window or parent tree node labels).
- You can use `PushID()` to append to the identifier without making it visible.
- You can use `"##something"` in a label to append to the identifier without making it visible.
- You can use `"###something"` in a label to make the identifier ignore the visible part.
<table>
<tr>
<td><img src="https://github.com/user-attachments/assets/776a8315-1164-4178-9a8c-df52e0ff28aa"></td>
@@ -301,16 +306,99 @@ ImGui::End();
</tr>
</table>
A primer on labels and the ID Stack...
### Q: How can I have multiple widgets with the same label?
A. When widgets are in a same scope and finite, you can use a `"##something"` suffix which will be part of the identifier but not visible as a label.
```cpp
Button("Play"); // Label = "Play", ID = hash of ("MyWindow", "Play")
Button("Play##foo1"); // Label = "Play", ID = hash of ("MyWindow", "Play##foo1") // Different from other buttons
Button("Play##foo2"); // Label = "Play", ID = hash of ("MyWindow", "Play##foo2") // Different from other buttons
```
B. More generally, e.g. in loops, you can use `PushID()/PopID()` to push a prefix which will be part of the identifier.
```cpp
// Using PushID() with a string
for (int i = 0; i < 100; i++)
{
MyObject* obj = Objects[i];
PushID(obj->Name);
Button("Click"); // Label = "Click", ID = hash of ("Window", obj->Name, "Click")
PopID();
}
```
```cpp
// Using PushID() with an index
for (int i = 0; i < 100; i++)
{
PushID(i);
Button("Click"); // Label = "Click", ID = hash of ("Window", i, "Click")
PopID();
}
```
### Q: How can I have widgets with an empty label?
If you want to completely hide the label, but still need an ID:
```cpp
Checkbox("##On", &b); // Label = "", ID = hash of (..., "##On") // No visible label, just a checkbox!
```
##### [Return to Index](#index)
### Q: How can I make a label dynamic?
Dear ImGui is very dynamic so you can submit different widgets every frame.
However, in order to preserve widget state (eg. which tree node is open; which button is focused) the library internaly refers to their unique ID.
Occasionally you might want to change a label while preserving a constant ID. This allows you to change/animate labels while persisting associated state.
For example, you may want to include varying information in a window title bar or button label.
Using "###" exclude the preceeding part from ID computation:
```cpp
Button("Hello###ID"); // Label = "Enable", ID = hash of (..., "ID")
Button("World###ID"); // Label = "Disable", ID = hash of (..., "ID") // Same ID, different label
```
Using a same ID ensure that associated related e.g. weither the widget is focused, won't be lost when the label changes.
<table>
<tr>
<td><img src="https://github.com/user-attachments/assets/2bf18756-e122-498d-bbd4-5c44bb1018d5"></td>
<td>
<pre lang="cpp">
// Window label has animating FPS counter
// Window ID stays the same = hash of "MyGame"
char buf[128];
sprintf(buf, "My game (%.1f FPS)###MyGame", io.Framerate);
ImGui::Begin(buf);
&nbsp;
// Label changes between "Enable" and "Disable"
// ID stays the same = hash of ("MyGame", "MyButton")
if (ImGui::Button(enabled ? "Disable###MyButton" : "Enable###MyButton", { -FLT_MIN, 0.0f }))
enabled = !enabled;
&nbsp;
ImGui::End();
</pre>
</td>
</tr>
</table>
(Hint: I'd suggest wrapping sprintf in something more compact to use, e.g. [ocornut/Str](https://github.com/ocornut/Str) for what I personally use).
##### [Return to Index](#index)
### General description of the label and ID Stack system
Dear ImGui internally needs to uniquely identify UI elements.
Elements that are typically not clickable (such as calls to the Text functions) don't need an ID.
Interactive widgets (such as calls to Button buttons) need a unique ID.
Elements that are typically not clickable (such as calls to Text() functions) don't need an ID.
Interactive widgets (such as calls to Button() functions) need a unique ID.
**Unique IDs are used internally to track active widgets and occasionally associate state to widgets.<BR>
Unique IDs are implicitly built from the hash of multiple elements that identify the "path" to the UI element.**
Since Dear ImGui 1.85, you can use `Demo>Tools>ID Stack Tool` or call `ImGui::ShowIDStackToolWindow()`. The tool display intermediate values leading to the creation of a unique ID, making things easier to debug and understand.
You can use `Demo>Tools>ID Stack Tool` or call `ImGui::ShowIDStackToolWindow()`. The tool display intermediate values leading to the creation of a unique ID, making things easier to debug and understand.
![Stack tool](https://user-images.githubusercontent.com/8225057/136235657-a0ea5665-dcd1-423f-9be6-dc3f8ced8f12.png)
@@ -364,20 +452,7 @@ Button("Play##foo2"); // Label = "Play", ID = hash of ("MyWindow", "Play##foo
Button("##foo"); // Label = "", ID = hash of ("MyWindow", "##foo") // Different from window
End();
```
- If you want to completely hide the label, but still need an ID:
```cpp
Checkbox("##On", &b); // Label = "", ID = hash of (..., "##On") // No visible label, just a checkbox!
```
- Occasionally/rarely you might want to change a label while preserving a constant ID. This allows
you to animate labels. For example, you may want to include varying information in a window title bar,
but windows are uniquely identified by their ID. Use "###" to pass a label that isn't part of ID:
```cpp
Button("Hello###ID"); // Label = "Hello", ID = hash of (..., "###ID")
Button("World###ID"); // Label = "World", ID = hash of (..., "###ID") // Same ID, different label
sprintf(buf, "My game (%f FPS)###MyGame", fps);
Begin(buf); // Variable title, ID = hash of "MyGame"
```
- Solving ID conflict in a more general manner:
Use `PushID()` / `PopID()` to create scopes and manipulate the ID stack, as to avoid ID conflicts
within the same window. This is the most convenient way of distinguishing ID when iterating and
libs/imgui/docs/README.md
+21 -20
View File
@@ -55,8 +55,8 @@ if (ImGui::Button("Save"))
ImGui::InputText("string", buf, IM_COUNTOF(buf));
ImGui::SliderFloat("float", &f, 0.0f, 1.0f);
```
![sample code output (dark, segoeui font, freetype)](https://user-images.githubusercontent.com/8225057/191050833-b7ecf528-bfae-4a9f-ac1b-f3d83437a2f4.png)
![sample code output (light, segoeui font, freetype)](https://user-images.githubusercontent.com/8225057/191050838-8742efd4-504d-4334-a9a2-e756d15bc2ab.png)
<img width="412" height="236" alt="sample code output (dark)" src="https://github.com/user-attachments/assets/32b838df-6378-498b-84a8-9a79ee6264a7" />
<img width="412" height="236" alt="sample code output (light)" src="https://github.com/user-attachments/assets/f075e2b0-98de-4be8-acb4-99ba0c9966cd" />
```cpp
// Create a window called "My First Tool", with a menu bar.
@@ -90,7 +90,7 @@ for (int n = 0; n < 50; n++)
ImGui::EndChild();
ImGui::End();
```
![my_first_tool_v188](https://user-images.githubusercontent.com/8225057/191055698-690a5651-458f-4856-b5a9-e8cc95c543e2.gif)
![my_first_tool_v192 6](https://github.com/user-attachments/assets/6c76658c-302f-403b-af26-d517e2bfb0d4)
Dear ImGui allows you to **create elaborate tools** as well as very short-lived ones. On the extreme side of short-livedness: using the Edit&Continue (hot code reload) feature of modern compilers you can add a few widgets to tweak variables while your application is running, and remove the code a minute later! Dear ImGui is not just for tweaking values. You can use it to trace a running algorithm by just emitting text commands. You can use it along with your own reflection data to browse your dataset live. You can use it to expose the internals of a subsystem in your engine, to create a logger, an inspection tool, a profiler, a debugger, an entire game-making editor/framework, etc.
@@ -110,11 +110,23 @@ Reading the changelogs is a good way to keep up to date with the things Dear ImG
### Demo
Calling the `ImGui::ShowDemoWindow()` function will create a demo window showcasing a variety of features and examples. The code is always available for reference in `imgui_demo.cpp`.
- [Web version of the demo](https://pthom.github.io/imgui_manual_online/manual/imgui_manual.html) courtesy of [@pthom](https://github.com/pthom).
- [Screenshot of the demo](https://raw.githubusercontent.com/wiki/ocornut/imgui/web/v167/v167-misc.png).
- [imgui_explorer](https://pthom.github.io/imgui_explorer): Web version of the demo w/ source code browser, courtesy of [@pthom](https://github.com/pthom).
You should be able to build the examples from sources. If you don't, let us know! If you want to have a quick look at some Dear ImGui features, you can download Windows binaries of the demo app here:
- [imgui-demo-binaries-20250625.zip](https://www.dearimgui.com/binaries/imgui-demo-binaries-20250625.zip) (Windows, 1.92.0, built 2025/06/25, master) or [older binaries](https://www.dearimgui.com/binaries).
- [imgui-demo-binaries-20260225.zip](https://www.dearimgui.com/binaries/imgui-demo-binaries-20260225.zip) (Windows, 1.92.6, built 2026/02/25, master) or [older binaries](https://www.dearimgui.com/binaries).
### Gallery
Examples projects using Dear ImGui: [Tracy](https://github.com/wolfpld/tracy) (profiler), [ImHex](https://github.com/WerWolv/ImHex) (hex editor/data analysis), [RemedyBG](https://remedybg.itch.io/remedybg) (debugger) and [hundreds of others](https://github.com/ocornut/imgui/wiki/Software-using-Dear-ImGui).
For more user-submitted screenshots of projects using Dear ImGui, check out the [Gallery Threads](https://github.com/ocornut/imgui/issues?q=label%3Agallery)!
For a list of third-party widgets and extensions, check out the [Useful Extensions/Widgets](https://github.com/ocornut/imgui/wiki/Useful-Extensions) wiki page.
| | |
|--|--|
| Custom engine [erhe](https://github.com/tksuoran/erhe) (docking branch)<BR>[![erhe](https://user-images.githubusercontent.com/8225057/190203358-6988b846-0686-480e-8663-1311fbd18abd.jpg)](https://user-images.githubusercontent.com/994606/147875067-a848991e-2ad2-4fd3-bf71-4aeb8a547bcf.png) | Custom engine for [Wonder Boy: The Dragon's Trap](http://www.TheDragonsTrap.com) (2017)<BR>[![the dragon's trap](https://user-images.githubusercontent.com/8225057/190203379-57fcb80e-4aec-4fec-959e-17ddd3cd71e5.jpg)](https://cloud.githubusercontent.com/assets/8225057/20628927/33e14cac-b329-11e6-80f6-9524e93b048a.png) |
| Custom engine (untitled)<BR>[![editor white](https://user-images.githubusercontent.com/8225057/190203393-c5ac9f22-b900-4d1e-bfeb-6027c63e3d92.jpg)](https://raw.githubusercontent.com/wiki/ocornut/imgui/web/v160/editor_white.png) | Tracy Profiler ([github](https://github.com/wolfpld/tracy))<BR>[![tracy profiler](https://user-images.githubusercontent.com/8225057/190203401-7b595f6e-607c-44d3-97ea-4c2673244dfb.jpg)](https://raw.githubusercontent.com/wiki/ocornut/imgui/web/v176/tracy_profiler.png) |
### Getting Started & Integration
@@ -139,23 +151,12 @@ Officially maintained backends (in repository):
- Many bindings are auto-generated (by good old [cimgui](https://github.com/cimgui/cimgui) or our newer [dear_bindings](https://github.com/dearimgui/dear_bindings)), you can use their metadata output to generate bindings for other languages.
[Useful Extensions/Widgets](https://github.com/ocornut/imgui/wiki/Useful-Extensions) wiki page:
- Automation/testing, Text editors, node editors, timeline editors, plotting, software renderers, remote network access, memory editors, gizmos, etc. Notable and well supported extensions include [ImPlot](https://github.com/epezent/implot) and [Dear ImGui Test Engine](https://github.com/ocornut/imgui_test_engine).
[![Useful extensions thumbnails](https://github.com/user-attachments/assets/e6b0aa7c-bf53-41c5-ac69-bea3098b1dee)](https://github.com/ocornut/imgui/wiki/Useful-Extensions)
- Automation/testing, Text editors, node editors, timeline editors, plotting, software renderers, remote network access, memory editors, gizmos, etc. Notable and well supported extensions include [ImPlot](https://github.com/epezent/implot), [ImPlot3d](https://github.com/brenocq/implot3d) and [Dear ImGui Test Engine](https://github.com/ocornut/imgui_test_engine).
Also see [Wiki](https://github.com/ocornut/imgui/wiki) for more links and ideas.
### Gallery
Examples projects using Dear ImGui: [Tracy](https://github.com/wolfpld/tracy) (profiler), [ImHex](https://github.com/WerWolv/ImHex) (hex editor/data analysis), [RemedyBG](https://remedybg.itch.io/remedybg) (debugger) and [hundreds of others](https://github.com/ocornut/imgui/wiki/Software-using-Dear-ImGui).
For more user-submitted screenshots of projects using Dear ImGui, check out the [Gallery Threads](https://github.com/ocornut/imgui/issues?q=label%3Agallery)!
For a list of third-party widgets and extensions, check out the [Useful Extensions/Widgets](https://github.com/ocornut/imgui/wiki/Useful-Extensions) wiki page.
| | |
|--|--|
| Custom engine [erhe](https://github.com/tksuoran/erhe) (docking branch)<BR>[![erhe](https://user-images.githubusercontent.com/8225057/190203358-6988b846-0686-480e-8663-1311fbd18abd.jpg)](https://user-images.githubusercontent.com/994606/147875067-a848991e-2ad2-4fd3-bf71-4aeb8a547bcf.png) | Custom engine for [Wonder Boy: The Dragon's Trap](http://www.TheDragonsTrap.com) (2017)<BR>[![the dragon's trap](https://user-images.githubusercontent.com/8225057/190203379-57fcb80e-4aec-4fec-959e-17ddd3cd71e5.jpg)](https://cloud.githubusercontent.com/assets/8225057/20628927/33e14cac-b329-11e6-80f6-9524e93b048a.png) |
| Custom engine (untitled)<BR>[![editor white](https://user-images.githubusercontent.com/8225057/190203393-c5ac9f22-b900-4d1e-bfeb-6027c63e3d92.jpg)](https://raw.githubusercontent.com/wiki/ocornut/imgui/web/v160/editor_white.png) | Tracy Profiler ([github](https://github.com/wolfpld/tracy))<BR>[![tracy profiler](https://user-images.githubusercontent.com/8225057/190203401-7b595f6e-607c-44d3-97ea-4c2673244dfb.jpg)](https://raw.githubusercontent.com/wiki/ocornut/imgui/web/v176/tracy_profiler.png) |
### Support, Frequently Asked Questions (FAQ)
See: [Frequently Asked Questions (FAQ)](https://github.com/ocornut/imgui/blob/master/docs/FAQ.md) where common questions are answered.