mirrors/imgui
1
0
Fork 0
mirror of https://github.com/ocornut/imgui.git synced 2026-07-31 12:49:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into docking

Browse Source
This commit is contained in:
ocornut
2026-07-25 13:45:27 +02:00
parent ca49eff398 01380c5797
commit 9b4eb24cee
12 changed files with 161 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/BACKENDS.md
View File

@@ -117,7 +117,7 @@ If you are not sure which backend to use, the recommended platform/frameworks fo
| GLFW | https://github.com/glfw/glfw | imgui_impl_glfw.cpp | |
| Sokol | https://github.com/floooh/sokol | [util/sokol_imgui.h](https://github.com/floooh/sokol/blob/master/util/sokol_imgui.h) | Lower-level than GLFW/SDL |
If your application runs on Windows or if you are using multi-viewport, the win32 backend handles some details a little better than other backends.
If your application runs on Windows or if you are using multi-viewports, the imgui_impl_win32 backend handles some details better than other backends.
## Using third-party Backends

92
docs/CHANGELOG.txt
View File

@@ -36,38 +36,32 @@ HOW TO UPDATE?
- Please report any issue!
-----------------------------------------------------------------------
VERSION 1.92.9 WIP (In Progress)
VERSION 1.92.9 (Released 2026-07-25)
-----------------------------------------------------------------------
Decorated log and release notes: https://github.com/ocornut/imgui/releases/tag/v1.92.8
Breaking Changes:
- TreeNode: commented out legacy name `ImGuiTreeNodeFlags_SpanTextWidth` which
was obsoleted in 1.90.7 (May 2024). Use `ImGuiTreeNodeFlags_SpanLabelWidth`.
- ColorEdit: obsoleted SetColorEditOptions() function added in 1.51 (June 2017) in
of directly poking to io.ConfigColorEditFlags. More consistent and easier to discover.
- Drag and Drop: commented out legacy name `ImGuiDragDropFlags_SourceAutoExpirePayload`
which obsoleted in 1.90.9 (July 2024). Use `ImGuiDragDropFlags_PayloadAutoExpire`.
- DragXXX, SliderXXX, InputScalar: with `ImGuiItemFlags_LiveEditOnInputScalar` now
defaulting to being disabled: inputting a value with the keyboard doesn't write
intermediate values to the backing variable. (#9476)
Before: DragFloat() with user typing "123" --> write back 1, then 12, then 123.
After: DragFloat() with user typing "123" --> write back 123 when validated/unfocused.
You can enable the flag back for a given scope if needed by specific widget/behavior.
Read below for details.
- TreeNode: commented out legacy name `ImGuiTreeNodeFlags_SpanTextWidth` which
was obsoleted in 1.90.7 (May 2024). Use `ImGuiTreeNodeFlags_SpanLabelWidth`.
- ColorEdit: obsoleted SetColorEditOptions() function added in 1.51 (June 2017) in favor
of directly poking to io.ConfigColorEditFlags. More consistent and easier to discover.
- Drag and Drop: commented out legacy name `ImGuiDragDropFlags_SourceAutoExpirePayload`
which obsoleted in 1.90.9 (July 2024). Use `ImGuiDragDropFlags_PayloadAutoExpire`.
- ImDrawData: marked `CmdListsCount` as obsolete (technically was obsoleted in 1.89.8).
Before: `draw_data->CmdListsCount`, After: `draw_data->CmdLists.Size`.
Other Changes:
- Windows:
- Clicking on a window's empty-space to move/focus a window checks
for lack of mouse button ownership. This gives an additional opportunity
for user code to bypass it without using a clickable item. (#9382)
- Clicking on a window's empty-space to move/focus a window checks
for lack of queued focus request. (#9382)
- Fixed double-click collapse toggle not owning the mouse button. If a
`SetNextWindowPos()` with pivot was queued in the same frame, the second
click could trigger another item in the same window. (#9439) [@Cleroth]
- Added `ImGuiItemFlags_LiveEditOnInputText` and `ImGuiItemFlags_LiveEditOnInputScalar`
- LiveEdit on/off: added `ImGuiItemFlags_LiveEditOnInputText` and `ImGuiItemFlags_LiveEditOnInputScalar`
flags to configure the timing of applying edits of backing variables when typing
values using a keyboard.
(#9476, #701, #3936, #3946, #5904, #6284, #8149, #8065, #8665, #9117, #9299, #700, #1351,
@@ -106,10 +100,22 @@ Other Changes:
- We intentionally are not adding `io.ConfigLiveEditXXX` fields to dictate the
default value of each `ImGuiItemFlags_LiveEditXXX`, because this is not expected
to be a user preference but a programmer/widget preferences.
Also, we strive to make the toolkit consistent.
And we strive to make the toolkit consistent.
- Windows:
- Clicking on a window's empty-space to move/focus a window checks
for lack of mouse button ownership. This gives an additional opportunity
for user code to bypass it without using a clickable item. (#9382)
- Clicking on a window's empty-space to move/focus a window checks
for lack of queued focus request. (#9382)
- Fixed double-click collapse toggle not owning the mouse button. If a
`SetNextWindowPos()` with pivot was queued in the same frame, the second
click could trigger another item in the same window. (#9439) [@Cleroth]
- Popups:
- Added bool return value to `OpenPopup()`, `OpenPopupOnItemClick()` functions
to notify when the popup was just opened. (#9429)
- InputText:
- Added `style.InputTextCursorSize` to configure cursor/caret thickness. (#7031, #9409)
This is automatically scaled by `style.ScaleAllSizes()`.
It is automatically scaled by `style.ScaleAllSizes()`.
- Reworked `io.ConfigInputTextEnterKeepActive` mode so that pressing
Ctrl+Enter or Shift+Enter still allows to deactivate. (#9239)
- Tables:
@@ -131,10 +137,10 @@ Other Changes:
- Headers: fixed label being clipped early to reserve space for a sort marker
even when no sort marker is displayed. Auto-fitting a column still accounts
for the possible marker, so that sorting after an auto-fit doesn't clip the label.
- Multi-Select
- Reworked ImGuiMultiSelectFlags_NoAutoSelect as it carried side-effects that
- Multi-Select:
- Reworked `ImGuiMultiSelectFlags_NoAutoSelect` as it carried side-effects that
were hardcoded/designed to use multi-selection on checkboxes. (#9391)
Specifically removed those undocumented behaviors from _NoAutoSelect:
Specifically removed those undocumented behaviors from `_NoAutoSelect`:
- Clicking a selected/checked item always unselect/uncheck.
- Shift+Click inverts targets value and copy to range.
- Shift+Keyboard copy selection source value to range.
@@ -143,27 +149,27 @@ Other Changes:
- Added `IMGUI_DISABLE_DEFAULT_FONT_BITMAP`/`IMGUI_DISABLE_DEFAULT_FONT_VECTOR` to
disable embedding either fonts separately. (#9407)
- Tweak `CalcTextSize()` awkward width rounding/ceiling code to reduce floating-point
imprecisions altering the result by 1 even at relatively small width. (#791)
- Better document the fact that ImFontAtlas::Clear()/ClearFonts() functions are
precision issues altering the result by 1 even at relatively small width. (#791)
- Better document the fact that `ImFontAtlas::Clear()`/`ClearFonts()` functions are
unlikely to be useful nowadays. Better recover to an edge case of mistakenly
calling ClearFonts() during rendering.
calling `ClearFonts()` during rendering.
- Fixed an issue where passing a manually created ImFontAtlas to CreateContext() would
incorrectly destroy it in DestroyContext() when ref-count gets back to zero. (#9426)
- Destroying an ImGui context using a ImFontAtlas checks that the later has no references.
incorrectly destroy it in `DestroyContext()` when ref-count gets back to zero. (#9426)
- Destroying an ImGui context using a `ImFontAtlas` checks that the later has no references.
- Nav:
- Fixed context menu activation with gamepad erroneously testing for _NavEnableKeyboard
instead of _NavEnableGamepad. (#9454, #8803, #9270) [@Clownacy]
- TreeNode:
- Fixed nav cursor rendering with rounding even though tree nodes don't have it. (#7589)
- Inputs:
- Added GetItemClickedCountWithSingleClickDelay() helper for easy disambiguation
- Added `GetItemClickedCountWithSingleClickDelay()` helper for easy disambiguation
between single-click and double-click for actions that needs single-click to do
something other than selection. (#8337)
- Returns 1 on single-click but delayed by io.MouseSingleClickDelay.
- Returns 2 on double-click, and 2+ on subsequent repeated cicks.
- Added io.MouseSingleClickDelay to configure default delayed single click delay when
using GetItemClickedCountWithSingleClickDelay() or IsMouseReleasedWithDelay(). (#8337)
Note that io.MouseSingleClickDelay is always > io.MouseDoubleClickTime.
- Returns 2 on double-click, and 2+ on subsequent repeated clicks.
- Added `io.MouseSingleClickDelay` to configure default delayed single click delay when
using `GetItemClickedCountWithSingleClickDelay()` or `IsMouseReleasedWithDelay()`. (#8337)
Note that `io.MouseSingleClickDelay` is always `> io.MouseDoubleClickTime`.
- ColorEdit:
- Added `io.ConfigColorEditFlags` to read/modify current color edit/picker settings.
- ColorPicker: added `ImGuiColorEditFlags_PickerNoRotate` to disable rotation of the
@@ -179,13 +185,13 @@ Other Changes:
- Settings:
- Windows/Tables settings entries can now record the last used date in YYYYMMDD format,
allowing tools to run to e.g. delete entries that haven't been used in X months. (#9460)
- Added bool io.ConfigIniSettingsSaveLastUsedDate to disable saving that info. (#9460)
- Added int io.ConfigIniSettingsAutoDiscardMonths to enable a mode where unused settings
- Added `bool io.ConfigIniSettingsSaveLastUsedDate` to disable saving that info. (#9460)
- Added `int io.ConfigIniSettingsAutoDiscardMonths` to enable a mode where unused settings
are automatically discard after xx months. (#9460)
- Added a trimming tool under Metrics->Settings, along with a yet-unexposed function.
- The current system date is fed through ImGuiPlatformIO::Platform_SessionDate,
- The current system date is fed through `ImGuiPlatformIO::Platform_SessionDate`,
which is automatically set by a call to time() done during context creation. (#9460)
- Added IMGUI_DISABLE_TIME_FUNCTIONS to disable setting platform_io.Platform_SessionDate.
- Added `IMGUI_DISABLE_TIME_FUNCTIONS` to disable setting platform_io.Platform_SessionDate.
A custom backend may still set it manually. (#9460)
- DrawList:
- Minor optimization to `AddLine()`, `AddLineH()`, `AddLineV()` functions. (#4091)
@@ -194,24 +200,24 @@ Other Changes:
- Demo:
- Extract 'Widgets->Tree Nodes->Selectable Nodes' out of the 'Advanced'
demo for clarity (manual reimplementation of basic selection).
- Misc:
- Added IM_DEBUG_BREAK() handler for GCC+AArch64/ARM64. [@tom-seddon]
- Debug Tools:
- Added `IM_DEBUG_BREAK()` handler for GCC+AArch64/ARM64. [@tom-seddon]
- Backends:
- Android:
- Clear mouse position on touch release (AMOTION_EVENT_ACTION_UP) to prevent
- Clear mouse position on touch release (`AMOTION_EVENT_ACTION_UP`) to prevent
items from staying in hovered state. (#6627, #9474) [@Turtle-PB]
- Metal4:
- Added new Metal 4 backend (forked from Metal 3 backend). (#9458, #9451) [@AmelieHeinrich]
- Added Metal-cpp support enabled with `IMGUI_IMPL_METAL_CPP` define. (#9461) [@MERL10N]
- OpenGL2:
- Backup and restore GL_UNPACK_ROW_LENGTH and GL_UNPACK_ALIGNMENT when updating texture
- Backup and restore `GL_UNPACK_ROW_LENGTH` and `GL_UNPACK_ALIGNMENT` when updating texture
to avoid altering caller GL state. (#8802, #9473) [@Turtle-PB]
- OpenGL3:
- GLSL version detection assume GLSL 410 when GL context is 4.1.
Fixes an issue running on macOS with Wine. [#9427, #6577) [@perminovVS]
- Expose selected render state in ImGui_ImplOpenGL3_RenderState, allowing to
dynamically select between use of glBindSampler() and glTexParameter(). (#9378)
- Backup and restore GL_UNPACK_ROW_LENGTH and GL_UNPACK_ALIGNMENT when updating texture
- Expose selected render state in `ImGui_ImplOpenGL3_RenderState`, allowing to
dynamically select between use of `glBindSampler()` and `glTexParameter()`. (#9378)
- Backup and restore `GL_UNPACK_ROW_LENGTH` and `GL_UNPACK_ALIGNMENT` when updating texture
to avoid altering caller GL state. (#8802, #9473) [@Turtle-PB]
- SDL2:
- Restore SDL_StartTextInput()/SDL_StopTextInput() in IME handler for on-screen keyboard

105
docs/FAQ.md
View File

@@ -9,42 +9,58 @@ or view this file with any Markdown viewer.
## Index
| **Q&A: Basics** |
:---------------------------------------------------------- |
| [Where is the documentation?](#q-where-is-the-documentation) |
| [What is this library called?](#q-what-is-this-library-called) |
| [What is the difference between Dear ImGui and traditional UI toolkits?](#q-what-is-the-difference-between-dear-imgui-and-traditional-ui-toolkits) |
| [Which version should I get?](#q-which-version-should-i-get) |
| **Q&A: Integration** |
| **[How to get started?](#q-how-to-get-started)** |
| **[How can I tell whether to dispatch mouse/keyboard to Dear ImGui or my application?](#q-how-can-i-tell-whether-to-dispatch-mousekeyboard-to-dear-imgui-or-my-application)** |
| [How can I enable keyboard or gamepad controls?](#q-how-can-i-enable-keyboard-or-gamepad-controls) |
| [How can I use this on a machine without mouse, keyboard or screen? (input share, remote display)](#q-how-can-i-use-this-on-a-machine-without-mouse-keyboard-or-screen-input-share-remote-display) |
| [How can I create my own backend?](#q-how-can-i-create-my-own-backend)
| [I integrated Dear ImGui in my engine and little squares are showing instead of text...](#q-i-integrated-dear-imgui-in-my-engine-and-little-squares-are-showing-instead-of-text) |
| [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...](#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 make a label dynamic?](#q-how-can-i-make-a-label-dynamic) (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) |
| [How can I interact with standard C++ types (such as std::string and std::vector)?](#q-how-can-i-interact-with-standard-c-types-such-as-stdstring-and-stdvector) |
| [How can I display custom shapes? (using low-level ImDrawList API)](#q-how-can-i-display-custom-shapes-using-low-level-imdrawlist-api) |
| **Q&A: Fonts, Text** |
| [How should I handle DPI in my application?](#q-how-should-i-handle-dpi-in-my-application) |
| [How can I load a different font than the default?](#q-how-can-i-load-a-different-font-than-the-default) |
| [How can I easily use icons in my application?](#q-how-can-i-easily-use-icons-in-my-application) |
| [How can I load multiple fonts?](#q-how-can-i-load-multiple-fonts) |
| [How can I display and input non-Latin characters such as Chinese, Japanese, Korean, Cyrillic?](#q-how-can-i-display-and-input-non-latin-characters-such-as-chinese-japanese-korean-cyrillic) |
| **Q&A: Concerns** |
| [Who uses Dear ImGui?](#q-who-uses-dear-imgui) |
| [Can you create elaborate/serious tools with Dear ImGui?](#q-can-you-create-elaborateserious-tools-with-dear-imgui) |
| [Can you reskin the look of Dear ImGui?](#q-can-you-reskin-the-look-of-dear-imgui) |
| [Why using C++ (as opposed to C)?](#q-why-using-c-as-opposed-to-c) |
| **Q&A: Community** |
| [How can I help?](#q-how-can-i-help) |
### Basics
- [Where is the documentation?](#q-where-is-the-documentation)
- [What is this library called?](#q-what-is-this-library-called)
- [What is the difference between Dear ImGui and traditional UI toolkits?](#q-what-is-the-difference-between-dear-imgui-and-traditional-ui-toolkits)
- [Which version should I get?](#q-which-version-should-i-get)
### Integration
- **[How to get started?](#q-how-to-get-started)**
- **[How can I tell whether to dispatch mouse/keyboard to Dear ImGui or my application?](#q-how-can-i-tell-whether-to-dispatch-mousekeyboard-to-dear-imgui-or-my-application)**
- [How can I enable keyboard or gamepad controls?](#q-how-can-i-enable-keyboard-or-gamepad-controls)
- [How can I use this on a machine without mouse, keyboard or screen? (input share, remote display)](#q-how-can-i-use-this-on-a-machine-without-mouse-keyboard-or-screen-input-share-remote-display)
- [How can I create my own backend?](#q-how-can-i-create-my-own-backend)
- [I integrated Dear ImGui in my engine and little squares are showing instead of text...](#q-i-integrated-dear-imgui-in-my-engine-and-little-squares-are-showing-instead-of-text)
- [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)
### Usage
- **[About the ID Stack system...](#q-about-the-id-stack-system)**
- **[How can I have multiple widgets with the same label?](#q-how-can-i-have-multiple-widgets-with-the-same-label) (using `##` or `PushID()`)**
- **[How can I have widgets with an empty label?](#q-how-can-i-have-widgets-with-an-empty-label) (using `##`)**
- **[How can I make a label dynamic?](#q-how-can-i-make-a-label-dynamic) (using `###`)**
- **[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), [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)
- [How can I interact with standard C++ types (such as std::string and std::vector)?](#q-how-can-i-interact-with-standard-c-types-such-as-stdstring-and-stdvector)
- [How can I display custom shapes? (using low-level ImDrawList API)](#q-how-can-i-display-custom-shapes-using-low-level-imdrawlist-api)
- [About Multi-Threading](#about-multi-threading)
### Fonts, Text
- [How should I handle DPI in my application?](#q-how-should-i-handle-dpi-in-my-application)
- [How can I load a different font than the default?](#q-how-can-i-load-a-different-font-than-the-default)
- [How can I easily use icons in my application?](#q-how-can-i-easily-use-icons-in-my-application)
- [How can I load multiple fonts?](#q-how-can-i-load-multiple-fonts)
- [How can I display and input non-Latin characters such as Chinese, Japanese, Korean, Cyrillic?](#q-how-can-i-display-and-input-non-latin-characters-such-as-chinese-japanese-korean-cyrillic)
### Concerns
- [Who uses Dear ImGui?](#q-who-uses-dear-imgui)
- [Can you create elaborate/serious tools with Dear ImGui?](#q-can-you-create-elaborateserious-tools-with-dear-imgui)
- [Can you reskin the look of Dear ImGui?](#q-can-you-reskin-the-look-of-dear-imgui)
- [Why using C++ (as opposed to C)?](#q-why-using-c-as-opposed-to-c)
### Community
- [How can I help?](#q-how-can-i-help)
--------
# Q&A: Basics
@@ -667,6 +683,7 @@ This way you will be able to use your own types everywhere, e.g. passing `MyVect
---
### Q: How can I interact with standard C++ types (such as std::string and std::vector)?
- Being highly portable (backends/bindings for several languages, frameworks, programming styles, obscure or older platforms/compilers), and aiming for compatibility & performance suitable for every modern real-time game engine, Dear ImGui does not use any of std C++ types. We use raw types (e.g. char* instead of std::string) because they adapt to more use cases.
- To use ImGui::InputText() with a std::string or any resizable string class, see [misc/cpp/imgui_stdlib.h](https://github.com/ocornut/imgui/blob/master/misc/cpp/imgui_stdlib.h).
- To use combo boxes and list boxes with `std::vector` or any other data structure: the `BeginCombo()/EndCombo()` API
@@ -686,6 +703,10 @@ One possible implementation of a helper to facilitate printf-style building of s
This is a small helper where you can instance strings with configurable local buffers length. Many game engines will
provide similar or better string helpers.
Using string views:
- String view types such as `std::string_view` may be used with the [feature/string_view](https://github.com/ocornut/imgui/tree/features/string_view) branch. This branch is actively maintained and supported. Please provide feedback if you use it. We are waiting for a good moment to merge it.
##### [Return to Index](#index)
---
@@ -726,6 +747,20 @@ ImGui::End();
---
### About Multi-Threading
A same Dear ImGui context may be not used from multiple threads in parallel.
If you want to use a same context within parallel tasks for occasional debug purpose, consider using a lock.
If you want to submit contents from a main/update thread but render Dear ImGui output in a dedicated render thread, you'll need to stage `ImDrawData` and texture requests. See the `ImDrawDataSnapshot` and `ImTextureQueue` helpers in [imgui_threaded_rendering](https://github.com/ocornut/imgui_club#imgui_threaded_rendering). Also see topics with [label: multi-threading](https://github.com/ocornut/imgui/issues?q=label%3Amulti-threading).
If you use multiple Dear ImGui contexts and want to use them from multiple threads, you need to `#define GImGui` to become a TLS variable (see details near the definition of `GImGui`. If you need to display multiple contexts simultaneously, consider using [imgui_multicontext_compositor](https://github.com/ocornut/imgui_club#imgui_multicontext_compositor). Also see topics with [label: multi-contexts](https://github.com/ocornut/imgui/issues?q=label%3Amulti-contexts).
There is a script/patch to make the API take an explicit context pointer: [#5856](https://github.com/ocornut/imgui/pull/5856). It is presently unmaintained and likely to easy to update. It has been decided that the change is not currently worth applying to main-line but maybe will be in a future version.
---
# Q&A: Fonts, Text
### Q: How should I handle DPI in my application?