Navy.gif/imgui
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated Debug Tools (markdown)

omar 2024-01-10 17:40:13 +01:00
parent 0ed852d60e
commit 79f96864c4
1 changed files with 35 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
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