diff --git a/Error-Handling.md b/Error-Handling.md index 07bfebb..acc4235 100644 --- a/Error-Handling.md +++ b/Error-Handling.md @@ -37,3 +37,39 @@ Typical scenarios: - Call `ErrorRecoveryTryToRecoverState()`. - Restore settings. +### API + +```cpp +// 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. +```cpp +ImGuiErrorRecoveryState state; +try +{ + ImGui::ErrorRecoveryStoreState(&state); +.... run code +} +catch +{ + ImGui::ErrorRecoveryTryToRecoverState(&state); +} +``` \ No newline at end of file