diff --git a/Debug-Tools.md b/Debug-Tools.md index 955f2f9..3b09392 100644 --- a/Debug-Tools.md +++ b/Debug-Tools.md @@ -1,42 +1,26 @@ (work in progress) Also see [[Tips]]. ## Index -- [Debug Configuration Flags](#debug-configuration-flags) +- [Item Picker](#item-picker) - [Metrics/Debugger window](#metricsdebugger-window) - [Debug Log](#debug-log) +- [Debug Configuration Flags](#debug-configuration-flags) - [Debug Break Buttons](#debug-break-buttons) - [ID Stack Tool](#id-stack-tool) -- [Item Picker](#item-picker) - [UTF-8 Encoding Viewer](utf-8-encoding-viewer) ---- -## Debug Configuration Flags +## Item Picker -![image](https://github.com/ocornut/imgui/assets/8225057/2b94e38b-e5ca-45ce-a562-ce6612c82535) +https://github.com/ocornut/imgui/issues/2673 -Runtime flags available in `ImGuiIO` (and exposed in Demo->Configuration): -```cpp -// 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(). +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](https://github.com/ocornut/imgui/issues/2673) for more details. -// 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. +![image](https://github.com/ocornut/imgui/assets/8225057/52707662-37c3-4526-a82a-1f2f1daf25dd) -// 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) -``` +![image](https://github.com/ocornut/imgui/assets/8225057/96828020-215c-4e30-879e-919fb8ea55f3) ## Metrics/Debugger window @@ -76,6 +60,33 @@ If `io.ConfigDebugIsDebuggerPresent` is enabled, an additional tooltip will appe ![image](https://github.com/ocornut/imgui/assets/8225057/a8f992a7-71dc-48c4-82da-6594ee08d65a) +## Debug Configuration Flags + +![image](https://github.com/ocornut/imgui/assets/8225057/2b94e38b-e5ca-45ce-a562-ce6612c82535) + +Runtime flags available in `ImGuiIO` (and exposed in Demo->Configuration): +```cpp +// 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: @@ -100,17 +111,6 @@ ImGui::ShowIdStackToolWindow(); ![stack_tool_03](https://user-images.githubusercontent.com/8225057/136235657-a0ea5665-dcd1-423f-9be6-dc3f8ced8f12.png) -## 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](https://github.com/ocornut/imgui/issues/2673) for more details. - -![image](https://github.com/ocornut/imgui/assets/8225057/52707662-37c3-4526-a82a-1f2f1daf25dd) - -![image](https://github.com/ocornut/imgui/assets/8225057/96828020-215c-4e30-879e-919fb8ea55f3) - ## UTF-8 Encoding Viewer See https://github.com/ocornut/imgui/blob/master/docs/FONTS.md#about-utf-8-encoding