(work in progress) Also see Tips.
Index
- Item Picker
- Metrics/Debugger window
- Debug Log
- Debug Configuration Flags
- Debug Break Buttons
- ID Stack Tool
- UTF-8 Encoding Viewer
Item Picker
https://github.com/ocornut/imgui/issues/2673
The Item Picker will allow you to pick an item with the mouse and have Dear ImGui break within the call-stack of that item. This is useful if you have large UI / codebase and you would to easily find out where some UI item is emitted.
You can find it in Metrics>Tools>Item Picker or expose it in your own UI by calling ImGui::DebugStartItemPicker().See #2673 for more details.
Metrics/Debugger window
Access the Metrics/Debugger window via Demo->Tools->Metrics/Debugger or by calling ShowMetricsWindow() from your code.
Many internal state and tools are exposed in the Metrics window. They will help you understand how Dear ImGui works, and can help you diagnose many problems.
Some of the debug tools
Debug Log
Access the Debug Log window via Demo->Tools->Debug Log or Metrics->Tools->Debug Log or by calling ShowDebugLogWindow(). Also see #5855.
It has options to enable logging of variety of events. Useful e.g.:
- You have issue with focus or active id being taken away.
- You have issue with popup closing.
- You have issue with windows being undocked.
- You want to visualize submitted input events.
- You want to visualize clipper steps etc.
- etc.
Inside the log, if you hover an ImGuiID identifier (formatted as 0xXXXXXXXX) it will automatically attempt to visually locate the item if the item still exists:
If io.ConfigDebugIsDebuggerPresent is enabled, an additional tooltip will appear after some time:
Debug Configuration Flags
Runtime flags available in ImGuiIO (and exposed in Demo->Configuration):
// Option to enable various debug tools showing buttons that will call the IM_DEBUG_BREAK() macro.
// - The Item Picker tool will be available regardless of this being enabled, in order to maximize its discoverability.
// - Requires a debugger being attached, otherwise IM_DEBUG_BREAK() options will appear to crash your application.
// e.g. io.ConfigDebugIsDebuggerPresent = ::IsDebuggerPresent() on Win32, or refer to ImOsIsDebuggerPresent() imgui_test_engine/imgui_te_utils.cpp for a Unix compatible version).
bool ConfigDebugIsDebuggerPresent; // = false // Enable various tools calling IM_DEBUG_BREAK().
// Tools to test correct Begin/End and BeginChild/EndChild behaviors.
// Presently Begin()/End() and BeginChild()/EndChild() needs to ALWAYS be called in tandem, regardless of return value of BeginXXX()
// This is inconsistent with other BeginXXX functions and create confusion for many users.
// We expect to update the API eventually. In the meanwhile we provide tools to facilitate checking user-code behavior.
bool ConfigDebugBeginReturnValueOnce; // First-time calls to Begin()/BeginChild() will return false. NEEDS TO BE SET AT APPLICATION BOOT TIME if you don't want to miss windows.
bool ConfigDebugBeginReturnValueLoop; // Some calls to Begin()/BeginChild() will return false. Will cycle through window depths then repeat. Suggested use: add "io.ConfigDebugBeginReturnValue = io.KeyShift" in your main loop then occasionally press SHIFT. Windows should be flickering while running.
// Option to deactivate io.AddFocusEvent(false) handling. May facilitate interactions with a debugger when focus loss leads to clearing inputs data.
// Backends may have other side-effects on focus loss, so this will reduce side-effects but not necessary remove all of them.
bool ConfigDebugIgnoreFocusLoss; // Ignore io.AddFocusEvent(false), consequently not calling io.ClearInputKeys() in input processing.
// Options to audit .ini data
bool ConfigDebugIniSettings; // Save .ini data with extra comments (particularly helpful for Docking, but makes saving slower)
Debug Break Buttons
When io.ConfigDebugIsDebuggerPresent is enabled, various **DebugBreak** buttons will appears in debug tools. Clicking them will attempt to break you in debugger in the desired location:
- Request a debug break in a Begin() call.
- Request a debug break in a ItemAdd() call via debug log and hovering 0xXXXXXX identifiers.
- Request a debug break in a BeginTable() call.
- Request a debug break in a SetShortcutRouting()/Shortcut() call. [Internal]
In the Debug Log you can also hover a 0xXXXXXXXX identifier and press the Pause/Break keyboard key to attempt to break in the ItemAdd() function for this item.
ID Stack Tool
https://github.com/ocornut/imgui/issues/4631
ImGui::ShowIdStackToolWindow();
UTF-8 Encoding Viewer
See https://github.com/ocornut/imgui/blob/master/docs/FONTS.md#about-utf-8-encoding
ImGui::SeparatorText("CORRECT");
ImGui::DebugTextEncoding(u8"こんにちは");
ImGui::SeparatorText("INCORRECT");
ImGui::DebugTextEncoding("こんにちは");