Debug Tools - ocornut/imgui GitHub Wiki

(work in progress) Also see Tips.

Index

Item Picker

https://github.com/ocornut/imgui/issues/2673

image

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 Demo>Tools>ItemPicker* or Metrics>Tools>Item Picker or expose it in your own UI by calling ImGui::DebugStartItemPicker().See #2673 for more details.

(*) The Item Picker shortcut from 'Demo->Tools->Item Picker' is disabled until your code set io.ConfigDebugIsDebuggerPresent = true. This is in order to avoid accidental use by non-debugger users. It is always available from Demo->Tools->Metrics regardless of that setting.

image

image

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.

Metrics

Fonts debugging

debug tools 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.

Debug Log

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:

image

If io.ConfigDebugIsDebuggerPresent is enabled, an additional tooltip will appear after some time:

image

image

Debug Configuration Flags

image

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]

image

image

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();

stack_tool_03

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("こんにちは");

UTF-8 Encoding viewer