Error Handling

Since Dear ImGui 1.91.3 we provide way to configure how to handle SOME recoverable errors.

• Error recovery is provided as a way to facilitate recovery from errors in e.g. scripting languages, or after specific exceptions handlers.
• Error recovery is not perfect nor guaranteed! You are not supposed to rely on it in the course of a normal application run.
• By design, we do NOT allow error recovery to be 100% silent. One of the three options needs to be checked.
• Always ensure that on programmers seat you have at minimum Asserts or Tooltips enabled when making direct imgui API call! Otherwise it would severely hinder your ability to catch and correct mistakes!

Typical scenarios:

(1) Programmer seats (current default)

• Recoverable errors will call IM_ASSERT_USER_ERROR(), leading to IM_ASSERT() being executed.
• If you can resume execution from your assert, recovery will generally be performed.
• If you can configure your assert to be ignored, recover will generally be performed and the error tooltip will be visible.

(2) Programmer seats (nicer/experimental)

• Disable Asserts io.ConfigErrorRecoveryEnableAssert=false but keep Tooltips visible.
• Recoverable errors will be visible in an error tooltip.
• The error tooltip will allow user to enable asserts.
• This implicitly rely on functional recovery. A few cases might probably still crash/assert. If this works well, we may make it the default in future versions.

(3) Non-programmer seats: what you might want to setup:

• Use io.ConfigErrorRecoveryEnableAssert=false, but make sure log entries are well visible or reported somewhere.
• If errors are not well resurfaced to programmers, it may hinder your ability to prevent errors from staying/spreading in the codebase. Use with caution!

(4) If you offer the ability to write Dear ImGui code via e.g. scripting language, you may want to:

• Use ErrorRecoveryStoreState() to record stack sizes before running the script interpreter.
• Use io.ConfigErrorRecoveryEnableAssert=false but only while in the context of the script interpreter.
• Maybe trigger a script break from your ErrorCallback if you can.
• Ensure that io.ConfigErrorRecoveryEnableTooltip=true! And that log entries are well surfaced and visible somewhere.

(5) To handle resuming code execution after an exception:

• Use ErrorRecoveryStoreState() to record stack sizes before your try {} block.
• Temporary adjust settings (e.g. disable assert, set a log callback).
• Call ErrorRecoveryTryToRecoverState().
• Restore settings.

API

// Options to configure how we handle recoverable errors [EXPERIMENTAL]
// - Error recovery is not perfect nor guaranteed! It is a feature to ease development.
// - Functions that support error recovery are using IM_ASSERT_USER_ERROR() instead of IM_ASSERT().
// - You not are not supposed to rely on it in the course of a normal application run.
// - Possible usage: facilitate recovery from errors triggered from a scripting language or after specific exceptions handlers.
// - Always ensure that on programmers seat you have at minimum Asserts or Tooltips enabled when making direct imgui API calls!
//   Otherwise it would severely hinder your ability to catch and correct mistakes!
// Read https://github.com/ocornut/imgui/wiki/Error-Handling for details about typical usage scenarios:
// - Programmer seats: keep asserts (default), or disable asserts and keep error tooltips (new and nice!)
// - Non-programmer seats: maybe disable asserts, but make sure errors are resurfaced (visible log entries, use callback etc.)
// - Recovery after error from scripting language: record stack sizes before running script, disable assert, trigger breakpoint from ErrorCallback, recover with ErrorRecoveryTryToRecoverState(), restore settings.
// - Recovery after an exception handler:  record stack sizes before try {} block, disable assert, set log callback, recover with ErrorRecoveryTryToRecoverState(), restore settings.
bool        ConfigErrorRecovery;                // = true       // Enable error recovery support. Some errors won't be detected and lead to direct crashes if recovery is disabled.
bool        ConfigErrorRecoveryEnableAssert;    // = true       // Enable asserts on recoverable error. By default call IM_ASSERT() when returning from a failing IM_ASSERT_USER_ERROR()
bool        ConfigErrorRecoveryEnableDebugLog;  // = true       // Enable debug log output on recoverable errors.
bool        ConfigErrorRecoveryEnableTooltip;   // = true       // Enable tooltip on recoverable errors. The tooltip include a way to enable asserts if they were disabled.

Manual stack state backup/restore

e.g.

ImGuiErrorRecoveryState state;
ImGui::ErrorRecoveryStoreState(&state);
.... run scripting code
ImGui::ErrorRecoveryTryToRecoverState(&state);

Exception handling:

ImGuiErrorRecoveryState state;
ImGui::ErrorRecoveryStoreState(&state);
try
{
    .... run code
}
catch
{
    ImGui::ErrorRecoveryTryToRecoverState(&state);
}