Error handling
stat or error stop
Procedures that can fail take an optional integer(int32), intent(out) :: stat:
- with
stat, a failure is returned:statreceivesFIG_OKor aFIG_ERR_*code, andfigure_last_error()gives the message; - without
stat, a failure writesFIGURE error: <message>to standard error and stops the program witherror stop 1.
Every procedure that can fail takes an optional stat (the feature map shows which); the others cannot fail in a way FIGURE detects (destroy is safe in any state).
call app%init_headless(0_int32, 300_int32, stat=stat) ! invalid size
if (stat /= FIG_OK) write(output_unit, '(A,I0,A)') 'init_headless: stat = ', stat, ', "'//figure_last_error()//'"'
call app%init_headless(400_int32, 300_int32, stat=stat) ! succeeds
call app%init_headless(400_int32, 300_int32, stat=stat) ! already initialized
if (stat == FIG_ERR_STATE) write(output_unit, '(A,I0,A)') 'init_headless: stat = ', stat, ', "'//figure_last_error()//'"'$ ./cb_stat
init_headless: stat = 2, "display size must be positive"
init_headless: stat = 1, "figure is already initialized"
ip_line: stat = 2, "ip_line: the series have different sizes"
ig_input: stat = 2, "ig_input: format '%d' is not a format of a real: one conversion %f, %e, %g or %a (or %F, %E, %G, %A) expected, with optional flags, width and precision"
ip_get_style_color: stat = 2, "style colour: unknown name "PlotBackground" for ImPlot (ImPlotCol_*)"Without stat:
call app%init_headless(400_int32, 300_int32)
call app%init_headless(400_int32, 300_int32) ! already initialized: error stop$ ./cb_error_stop
FIGURE error: figure is already initialized
ERROR STOP 1
[exit status 1]Status codes
| Code | Value | Meaning |
|---|---|---|
FIG_OK | 0 | success |
FIG_ERR_STATE | 1 | call not allowed in the current state: init twice, next_frame before init, a process started again while it runs (Processes), a drawing procedure called from a task (Tasks), a file dialog or browser whose id is still open (File dialogs), ip_annotation outside a plot, a usage error: a wrong end, a scope left open, a drawing call with no frame open (Pairing and frames), an item named by a path that is disabled or not visible, a test not idle after test_run's max_frames or a menu level that never appeared (Finding items by path, Running until idle), app%open_prefs a second time (Preferences), test_capture with no frame open (Pictures as tests), p%exit_code of a process that still runs or is detached, t%result before the task is done, init* from a task (Processes, tasks and tests) |
FIG_ERR_ARGUMENT | 2 | invalid argument: non-positive window size, a file that is not a font or a fourteenth fallback for app%add_fallback_font, ip_line arrays of different sizes, a palette below the contrast rule, a text of 2 GiB or more for a text buffer, an unknown colormap name or a malformed colormap file (Colormaps), a colour without 4 components or nlevels < 1 for the plot extras and contours, a file that is not a PNG or a JPEG, or one that cannot be decoded, for fig_read_image and tex%load, a mesh array not contiguous or a connectivity index out of range for a 3-D view, an unknown key or scope of a shortcut, an unknown delay of ig_item_hovered, a ratio outside [0, 1], an unknown axis or an offset below -1 for scrolling and focus, an unknown where or a negative width for the alignment calls, a printf format that is not a format of one real for ip_setup_axes, ip_heatmap, ip_colormap_scale or ip_colormap_legend, or not one of the value's family for a number widget (Formats), an argument of a number widget Dear ImGui would assert on: a bound NaN or beyond half the range of the kind, a speed not above 0, an unknown scale, a vector of no components (Numbers and choices), a path that names no item (the message names the nearest), several, or is malformed, an item not checkable for test_item_checked or taking no text for test_item_type_text (Finding items by path), a window or a layout added twice or not added, a preference's key that is empty, has a newline or a blank at an end (Application layer), a message box without an id or a label, ig_splitter without two sizes, size limits below 0 or a maximum below its minimum, save_image of an empty rectangle or without a file name, test_capture without a file name, test_compare_image with a threshold outside 0-255, a negative max_failed, masks without 4 rows or a rectangle whose maximum is below its minimum, or a file that is not a PNG or a JPEG (Pictures as tests), a line out of range, an unknown severity, an empty text to find, an unknown language for the code editor, an unknown corner or mode, a snap not above 0, a matrix whose last row is not (0, 0, 0, 1) for the gizmos, a reversed or qualitative map for the gradient editor, an empty id, a search too long or of two lines, an empty heading or file name for Markdown |
FIG_ERR_FAILED | 3 | the platform (SDL, OpenGL) or a task reported a failure: no display, no OpenGL 3 context, a program that cannot be started, a font file that cannot be read (Fonts), an image file that cannot be read (Reading images), window size limits the system refuses (Preferences), a picture of test_compare_image that cannot be read or written (Pictures as tests), a Markdown file that cannot be read (Markdown), no thread that can be created for a task, a task that reported a failure with h%fail (given by t%result), a kill the system refuses, the port of init_remote in use or not permitted, a picture of save_image that cannot be written (given by app%image_result) (Processes, tasks and tests) |
FIG_ERR_EXCEPTION | 4 | a C++ exception was caught at the C boundary |
The codes are integer(c_int) parameters; compare them with stat directly (stat /= FIG_OK). C++ exceptions never cross into Fortran: every glue function catches them and returns FIG_ERR_EXCEPTION with the exception's message.
figure_last_error
figure_last_error() returns the message of the last failure detected by the native layer, as an allocatable character. The message is not cleared by a successful call: read it right after the failing call. Each thread has its own message: a task that fails (fig_read_image with a stat) reads its own, and leaves the main thread's alone.
ip_line checks size(x) == size(y) on the Fortran side, before calling the native layer; a mismatch returns FIG_ERR_ARGUMENT with the message ip_line: the series have different sizes (each item names itself).
if (app%next_frame(stat=stat)) then
if (ig_begin('Data')) then
if (ip_begin_plot('Mismatch')) then
call ip_line('y', x, y, stat=stat) ! size(x) /= size(y): nothing drawn
if (stat == FIG_ERR_ARGUMENT) write(output_unit, '(A,I0,A)') 'ip_line: stat = ', stat, &
', "'//figure_last_error()//'"'
call ip_end_plot()
endif
endif
call ig_end()
endifA printf format is checked the same way, on the Fortran side, before Dear ImGui or ImPlot formats a value with it (Formats): a format that is not one of a real gives FIG_ERR_ARGUMENT with a message naming the procedure, the argument and the format, and nothing is drawn. The full program checks ig_input; its output is above:
if (ig_begin('Input')) then
v = 0.5_real64
edited = ig_input('Value', v, format='%d', stat=stat) ! '%d' prints an integer: v is a real
if (stat == FIG_ERR_ARGUMENT) write(output_unit, '(A,I0,A)') 'ig_input: stat = ', stat, &
', "'//figure_last_error()//'"'
endif
call ig_end()| Procedure and argument | Message |
|---|---|
ig_input, format | ig_input: format '<format>' is not a format of a real: one conversion %f, %e, %g or %a (or %F, %E, %G, %A) expected, with optional flags, width and precision |
ig_input, ig_drag, ig_slider, ig_drag_range of an integer, format | <procedure>: format '<format>' is not a format of an integer: one conversion %d, %i or %u expected, with optional flags, width and precision |
the same of a real, and ig_slider_angle | as ig_input's above, starting with the procedure's name |
ip_setup_axes, xformat / yformat | the same, starting ip_setup_axes: xformat (or yformat) |
ip_setup_axis, format | the same, starting ip_setup_axis: format |
ip_heatmap, ip_colormap_scale, ip_colormap_legend, label_format | the same, starting <procedure>: label_format (ip_colormap_legend refuses only a format with a conversion: one without is text) |
Pairing and frames
Dear ImGui's begin/end pairs are the likeliest bug of a FIGURE program: an ig_end_table where an ig_tree_pop belongs, an ip_end_plot after a plot that did not begin. FIGURE keeps a scope record of the frame, in its native layer: every begin/end and push/pop pair it wraps registers there (its kind, its label, what the begin returned, the Fortran procedure), and every end is checked against the record before Dear ImGui sees it. A wrong end never reaches Dear ImGui, so the error is a message naming the Fortran calls, not an assertion inside imgui.cpp.
Changed in v0.4.0
Until v0.3.1 a broken pairing aborted the program inside Dear ImGui, with an assertion that named no Fortran call (imgui.cpp:11325: ... Assertion '(0) && "Missing End()"' failed), and a widget called with no frame open could crash. From v0.4.0 FIGURE checks the pairs itself, by default in mode 'report': the wrong call does nothing, the frame goes on, and the next app%next_frame(stat) returns FIG_ERR_STATE with the messages. A loop that passes no stat to next_frame still stops (error stop), now with FIGURE's message; one that passes a stat and ignores it no longer stops. app%set_checks('abort') stops at the faulty call itself.
The rules checked
| Rule | Pairs |
|---|---|
| Always paired: the end follows every begin, whatever it returned | ig_begin, ig_begin_side_bar / ig_end; ig_begin_child / ig_end_child; ig_push_id / ig_pop_id; ig_begin_disabled / ig_end_disabled; ig_push_font / ig_pop_font; ig_push_style_color, ip_push_style_color / ig_pop_style_color, ip_pop_style_color; ig_push_style_var, ip_push_style_var / ig_pop_style_var, ip_pop_style_var; ig_begin_group / ig_end_group; ig_align_begin / ig_align_end; ig_begin_multi_select / ig_end_multi_select; ig_push_item_width / ig_pop_item_width |
| End only after a true begin | ig_begin_tab_bar / ig_end_tab_bar; ig_begin_tab / ig_end_tab; ig_begin_table / ig_end_table; ig_tree_node / ig_tree_pop; ig_begin_main_menu_bar / ig_end_main_menu_bar; ig_begin_menu_bar / ig_end_menu_bar; ig_begin_menu / ig_end_menu; ig_begin_popup, ig_begin_popup_context, ig_begin_popup_modal / ig_end_popup; ig_begin_tooltip, ig_begin_item_tooltip / ig_end_tooltip; ip_begin_plot / ip_end_plot; ip_begin_subplots / ip_end_subplots; ip3_begin_plot / ip3_end_plot; ip_begin_aligned / ip_end_aligned; ip_begin_legend_popup / ip_end_legend_popup; ig_dock_layout_begin / ig_dock_layout_end |
- Scopes nest. Windows, child regions, tab bars, tabs, tables, tree nodes, menu bars, menus, popups (context menus included), tooltips, plots, subplot figures, 3-D plots, groups of aligned plots, legend popups, dock layouts, id scopes, groups, aligned groups and pushed item widths are closed innermost first: an end that is not the end of the innermost open one is wrong.
- Pushes do not nest. A style colour, a style variable, a font and a disabled block are undone by the newest push of their own kind, wherever it was made (a colour pushed before
ig_beginand popped right after it is right, as in Dear ImGui). A font or a disabled block opened inside a window (a window, a child region, a popup, a menu, a tooltip, the main menu bar) is closed before that window's end, as Dear ImGui'sEndrequires. - Everything is closed by the end of the frame: what is still open when
next_frameis called is an error. - Drawing needs a frame. A drawing procedure (a widget, a begin or an end, a plot item, a style push) called with no frame open, before the first
next_frameor after the loop, is refused: "ig_button: no frame open". Calls that draw nothing (app%set_style,ig_set_style_color,ip_colormap,ig_text_size, a texture'sinit, a 3-D view's mesh) work outside a frame as before. A task is refused first, as always (Tasks). - Raw calls are compared too. At every end, and at the end of the frame, the sizes of Dear ImGui's stacks (windows, ids, tree depth, colours, style variables, fonts, focus scopes, groups, item flags, popups, disabled blocks) and the current table, tab bar and plot are compared with what the scope's begin left: a call made through the raw bindings that opened something and did not close it is reported, and Dear ImGui's error recovery closes it.
The three modes
app%set_checks(mode [, stat]) chooses what a usage error does. It can be called before init*; destroy restores the default.
'abort' | 'report' (default) | 'recover' | |
|---|---|---|---|
| A wrong end, a drawing call with no frame open | error stop at the call, the message on standard error | refused (it does nothing); the frame goes on | as 'report'; but an end whose scope is open further down first closes the scopes opened after it, then ends its own |
A scope still open at next_frame | error stop at next_frame | closed by FIGURE, in reverse order | closed by FIGURE |
next_frame(stat) after a frame with errors | (stopped before) | FIG_ERR_STATE; figure_last_error() gives every message, one per line; the next frame is open and the loop goes on. Without stat: error stop with the messages | FIG_OK; the messages in figure_last_error() and in a notification (one per distinct set of messages, not one per frame) |
A call with a stat of its own (ig_pop_style_color(stat=s), ig_dock_layout_end(id, stat=s), a drawing call with stat) | stat = FIG_ERR_STATE there | the same | the same |
| Dear ImGui's own checks (raw calls) | its assertions, as before | its error recovery, the message (Dear ImGui: Missing PopID()) among the frame's | the same |
'report' without a stat stops the program. The plain loop do while (app%next_frame()) in the default mode ends with error stop at the frame after a usage error, its messages on standard error, as every FIGURE failure without a stat does. A program that must go on either passes stat and decides (the studio of the tutorial reports the messages in a notification and draws on: chapter 19), or chooses 'recover', which goes on by itself and shows them in a notification:
| Loop | 'report' (default) | 'recover' |
|---|---|---|
do while (app%next_frame()) | stops at the next frame: error stop with the messages | goes on; the messages in a notification |
do while (app%next_frame(stat=s)) | goes on; s = FIG_ERR_STATE, the messages in figure_last_error() | goes on; s = FIG_OK, the messages in a notification |
'abort' gives the earliest stop, at the line of the faulty call: the mode for tests (below). 'report' turns the errors into a status, as every other FIGURE failure: the program decides. 'recover' keeps an interactive program running through an error in a rarely used panel, the way NASA's Mirage.jl uses Dear ImGui's error recovery; the panel may draw wrongly until the code is fixed.
Tests run in 'abort'. A test should fail at the line of the fault, and a test that passes a stat to next_frame for another reason must not step over a usage error: call app%set_checks('abort') after init_headless. FIGURE's own test suite runs in the default mode, which stops a test just as well, one call later, because its loops pass no stat to next_frame; src/tests/figure_test_errors.F90 checks the three modes.
- Status:
statis optional (absent:error stopwith the message).FIG_ERR_ARGUMENTfor an unknown mode (Messages);FIG_ERR_STATEfrom a task: the mode belongs to the loop's thread. - Modes: the same in window, headless and remote mode.
- Threads: the frame loop's thread only.
- Dear ImGui's names: its error recovery is
io.ConfigErrorRecovery*; FIGURE sets it for the mode (assertions on in'abort', off with FIGURE's callback in the others).
subroutine grid(pop)
!< A table of blocks, a tree in its first cell; `pop` false: the tree's end forgotten.
logical, intent(in) :: pop !< Close the tree (the right code).
if (ig_begin('Grid')) then
if (ig_begin_table('blocks', 2_int32)) then
call ig_table_next_row()
call ig_table_next_column()
if (ig_tree_node('Blocks', default_open=.true.)) then
call ig_text('inlet')
call ig_text('outlet')
if (pop) call ig_tree_pop() ! only after a true ig_tree_node
endif
call ig_table_next_column()
call ig_text('2 blocks')
call ig_end_table()
endif
endif
call ig_end()
endsubroutine gridcall grid(pop=.false.) ! ig_tree_pop forgotten
ok = app%next_frame(stat=stat) ! mode 'report' (the default): the errors of the frame
if (stat /= FIG_OK) write(output_unit, '(A)') 'report:'//new_line('a')//figure_last_error()$ ./cb_scope_error
report:
ig_end_table: the open scope is ig_tree_node('Blocks') (close it with ig_tree_pop before ig_end_table)
ig_end: the open scope is ig_tree_node('Blocks') (close it with ig_tree_pop before ig_end)
app%next_frame: ig_tree_node('Blocks') is still open (close it with ig_tree_pop)
app%next_frame: ig_begin_table('blocks') is still open (close it with ig_end_table)
app%next_frame: ig_begin('Grid') is still open (close it with ig_end)
fixed: no usage error
recover: stat == FIG_OK is T, the message:
ig_end_table: the open scope is ig_tree_node('Blocks') (close it with ig_tree_pop before ig_end_table)The first line is the bug: the table's end found the tree node open. The lines after it follow from it: in mode 'report' the wrong ig_end_table was refused, so the window's ig_end found the tree open too, and the scopes were still open when the frame ended. The full program is in the cookbook.
Messages
<call> is the procedure that was called; a scope is shown as the program opened it: ig_tree_node('Blocks'), ig_push_id(7), ig_begin_main_menu_bar(); an always-paired begin that returned .false. is marked (it returned false).
| Error | Message |
|---|---|
| An end while another scope is the innermost, and its own is open below it | <call>: the open scope is <scope> (close it with <its end> before <call>) |
| An end of a kind not open, while another scope is | <call>: no <begin> is open; the open scope is <scope> (closed by <its end>) |
| An end with nothing open | <call>: no <begin> is open (no scope is open) |
An end after a begin that returned .false. (end only after a true begin) | <call>: <scope> returned false (end only after a true begin) |
| A pop with no push of its kind open; more pops than pushes | <call>: no <push> is open; <call>: <n> pops for <m> open <push> |
| A font or a disabled block left open inside a window | <call>: <scope> is still open inside <window> (close it with <its end> before <call>) |
| A scope still open at the end of the frame | app%next_frame: <scope> is still open (close it with <its end>) |
| A drawing call with no frame open | <call>: no frame open |
| A raw call left a stack open inside a scope | <call>: Dear ImGui holds <stack> <n> (<m> expected) inside <scope>: a call outside FIGURE (a raw binding) did not close what it opened |
| ... at the end of the frame | app%next_frame: Dear ImGui holds <stack> <n> (<m> expected) at the end of the frame: a call outside FIGURE (a raw binding) did not close what it opened |
An error Dear ImGui detected itself ('report', 'recover') | Dear ImGui: <its message> |
| An unknown mode | app%set_checks: mode is 'abort', 'report' or 'recover', not '<mode>' (FIG_ERR_ARGUMENT) |
A report keeps the first 20 messages of a frame and counts the others ((and 12 more)).
What the checks cost
One record entry per begin and one comparison per end: 50 ns per ig_push_id/ig_pop_id pair more than the raw calls (54 ns against 3 ns, gfortran 16 -O2, an Intel i9-13900KF under WSL2, src/tests/figure_test_errors.F90 prints both). A widget pays one test of the frame flag, beside what its wrapper already did (ig_text: 30 ns, the raw igTextUnformatted: 13 ns, the difference mostly the copy of the text to a C string). The checks cannot be turned off.
What is not checked, and what recovery cannot repair
- Calls that are not pairs are not checked against the record: an
ig_table_next_columnoutside a table. The plot items and queries check themselves that a plot is being declared (Plot queries and marks), as the 3-D ones do (ImPlot3D). - Raw calls are caught when they leave something open, and only when a FIGURE end or the frame's end compares the stacks, not at the raw call. A raw call that closes what FIGURE opened (a raw
igEndfor anig_begin) is not caught by the record, which compares what is left open; Dear ImGui's own checks see it or not (in mode'abort'its assertion stops the program, as before). - What a refused end leaves. In
'report'the widgets after a refused end are drawn in the scope that stayed open (inside the tree node, in the example above) until the frame ends: the frame looks wrong, the next one is right once the code is. - Dear ImGui's error recovery (what
'recover'and the raw-call checks rely on) is, in its authors' words, "not perfect nor guaranteed" (imgui.h,ConfigErrorRecovery): it cannot recover from inside a tab item (BeginTabItem/EndTabItem), and state a program changed through raw calls (a cursor position, a clip rectangle) is not restored. FIGURE closes its own scopes from the record, ImPlot's plots included, which Dear ImGui's recovery does not know; recovery covers only what raw calls left. - Usage errors of a frame that never ends (the program stops between frames, or the loop is left with scopes open) are not reported:
destroycloses what is open without a message.
The pairing rules of each family are on the Widgets, Plots, Menus and Docking pages.
Failures by family
The procedures of each family check their arguments, and their place, before Dear ImGui, ImPlot or the system sees them; the tables give the status and the message of each failure. A usage error (FIG_ERR_STATE for a call out of its place) follows the mode of The three modes.
Numbers and choices
The number widgets and the list box (Numbers, Choices) check their arguments on the Fortran side, before Dear ImGui sees them. A wrong argument is FIG_ERR_ARGUMENT: nothing is drawn, the value is left alone, the call returns .false. (absent stat, error stop with the message). <p> is the procedure, <half> half the largest value of the kind (1073741823 for an int32; reals are written as 1.70141E+038).
| Failure | Message |
|---|---|
| a format of the other family, with no conversion or more than one | as in the table of figure_last_error: <p>: format '<format>' is not a format of an integer: ... (or of a real) |
| a conversion longer than 24 characters | <p>: format '<format>' has a conversion longer than 24 characters |
an unknown scale | <p>: unknown scale '<scale>' ('linear' or 'log') |
scale='log' for a drag without both bounds | ig_drag: scale 'log' needs vmin and vmax |
| a bound NaN | <p>: vmin is NaN (vmax, deg_min, deg_max, radians, height, lo, hi) |
| a bound beyond half the range of the kind | <p>: vmax <value> is out of -<half> to <half> |
vmin > vmax for a drag or a range; lo > hi | <p>: vmin <value> is above vmax <value>; ig_drag_range: lo <value> is above hi <value> |
a speed not above 0, NaN or beyond single precision | <p>: speed <value> is not above 0 and within single precision |
| an angle or an end in degrees beyond single precision | ig_slider_angle: radians <value> is out of ...; deg_min <value> is out of ... |
| a vector of no components | <p>: value has no components |
Tables
The table calls (Tables) check their arguments on the Fortran side and their place in the native layer. An argument out of range is FIG_ERR_ARGUMENT (nothing done; absent stat, error stop); a call out of its place is a usage error, FIG_ERR_STATE (absent stat, reported by the next app%next_frame as the pairing errors are, or stopping at once in mode 'abort').
| Failure | Status | Message |
|---|---|---|
columns outside 1 to 511 | FIG_ERR_ARGUMENT | ig_begin_table: columns <n> is out of 1 to 511 |
freeze_rows outside 0 to 127 | FIG_ERR_ARGUMENT | ig_begin_table: freeze_rows <n> is out of 0 to 127 |
freeze_cols outside 0 to columns | FIG_ERR_ARGUMENT | ig_begin_table: freeze_cols <n> is out of 0 to the columns |
width and stretch together | FIG_ERR_ARGUMENT | ig_table_setup_column: give width or stretch, not both |
a negative or NaN width | FIG_ERR_ARGUMENT | ig_table_setup_column: width <w> is negative (width NaN is not a width) |
stretch not above 0, or NaN | FIG_ERR_ARGUMENT | ig_table_setup_column: stretch <w> is not above 0 (stretch NaN is not a weight) |
rgba not of 3 or 4 components; one outside [0, 1] or NaN | FIG_ERR_ARGUMENT | ig_table_row_color: rgba has 3 or 4 components; rgba components are in [0, 1]; rgba has a NaN component |
cell or column outside 1 to the columns | FIG_ERR_ARGUMENT | <call>: column <n> is out of 1 to <columns> |
| no table open | FIG_ERR_STATE | <call>: no table is open (call it between ig_begin_table and ig_end_table) |
ig_table_sort in a table not sortable | FIG_ERR_STATE | ig_table_sort: the table is not sortable (ig_begin_table(..., sortable=.true.)) |
ig_table_sort before every column is declared | FIG_ERR_STATE | ig_table_sort: call it after every column is declared (ig_table_setup_column) |
ig_table_column_enabled in a table not hideable | FIG_ERR_STATE | ig_table_column_enabled: the table is not hideable (ig_begin_table(..., hideable=.true.)) |
ig_table_row_color before the first row | FIG_ERR_STATE | ig_table_row_color: no row is begun (call it after ig_table_next_row) |
Changed in v0.4.0
Until v0.3.1 ig_begin_table passed any columns to Dear ImGui, whose check of a count out of 1 to 511 is an assertion: the program aborted inside imgui_tables.cpp, naming no Fortran call. From v0.4.0 FIGURE refuses it first: .false., FIG_ERR_ARGUMENT, and error stop when the call has no stat.
Canvas
The canvas and its primitives (Canvas) check their arguments on the Fortran side, before Dear ImGui sees them: a wrong one is FIG_ERR_ARGUMENT, nothing drawn (absent stat, error stop with the message). <p> is the procedure. The plot layer outside a plot is a usage error, FIG_ERR_STATE (absent stat, reported by the next app%next_frame, or stopping at once in mode 'abort').
| Failure | Status | Message |
|---|---|---|
an unknown layer | FIG_ERR_ARGUMENT | <p>: unknown layer '<layer>' ('window', 'foreground', 'background' or 'plot') |
color not of 3 or 4 components | FIG_ERR_ARGUMENT | <p>: color has 3 or 4 components |
a component of color outside [0, 1] or NaN | FIG_ERR_ARGUMENT | <p>: color components are in [0, 1] |
x and y of different sizes | FIG_ERR_ARGUMENT | <p>: x has <n> points, y <m> |
| too few points (2 for a polyline, 3 for a polygon) | FIG_ERR_ARGUMENT | <p>: <n> points, at least <m> needed |
| a coordinate NaN, infinite or beyond single precision | FIG_ERR_ARGUMENT | <p>: x must be finite and within single precision (y) |
thickness not above 0, NaN or infinite | FIG_ERR_ARGUMENT | <p>: thickness is not a finite length above 0 |
radius below 0, NaN or infinite | FIG_ERR_ARGUMENT | ig_draw_circle: radius is not a finite length >= 0 |
| a texture not initialized | FIG_ERR_ARGUMENT | ig_draw_image: the texture is not initialized (ig_canvas: ...) |
| a canvas or invisible button size NaN or infinite | FIG_ERR_ARGUMENT | <p>: width and height must be finite and within single precision |
layer='plot' outside a plot | FIG_ERR_STATE | <p>: layer 'plot' outside a plot (call it between a true ip_begin_plot and ip_end_plot) |
Plot axes
The axis calls (Axes) check their arguments on the Fortran side and their place against the plot being declared, before ImPlot sees them (ImPlot's own checks are assertions: the program aborted). A wrong argument is FIG_ERR_ARGUMENT, nothing set up (absent stat, error stop with the message); a call out of its place is a usage error, FIG_ERR_STATE (absent stat, reported by the next app%next_frame, or stopping at once in mode 'abort'). <p> is the procedure.
| Failure | Status | Message |
|---|---|---|
| an unknown axis name | FIG_ERR_ARGUMENT | <p>: unknown axis '<axis>' ('x1', 'x2', 'x3', 'y1', 'y2' or 'y3') |
| a y axis where an x axis is expected, or the reverse | FIG_ERR_ARGUMENT | <p>: x '<axis>' is not an x axis ('x1', 'x2' or 'x3') (y, xaxis, yaxis) |
| an unknown scale | FIG_ERR_ARGUMENT | <p>: unknown scale '<scale>' ('linear', 'log', 'symlog' or 'time') (xscale, yscale) |
'time' on a y axis | FIG_ERR_ARGUMENT | ip_setup_axis: scale 'time' on axis '<axis>' is refused: ImPlot labels time on x axes only |
xlog and an xscale other than 'log' | FIG_ERR_ARGUMENT | ip_setup_axes: xlog and xscale '<scale>' disagree (give xscale only: xlog is deprecated) |
a limit NaN, or vmin >= vmax | FIG_ERR_ARGUMENT | ip_setup_axis_limits: vmin and vmax must not be NaN; vmin must be below vmax |
| tick values not finite; labels not one per value | FIG_ERR_ARGUMENT | ip_setup_axis_ticks: values must be finite; labels must be one per value |
a constraint NaN; vmin >= vmax; zoom_min > zoom_max; a negative width | FIG_ERR_ARGUMENT | ip_setup_axis_constraints: vmin is NaN; vmin must be below vmax; zoom_min must not be above zoom_max; a zoom width must not be negative |
vmin <= 0 on a log axis | FIG_ERR_ARGUMENT | ip_setup_axis_constraints: vmin must be above 0 on the log axis '<axis>' |
| an unknown legend location | FIG_ERR_ARGUMENT | ip_setup_legend: unknown location '<location>' ('n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw' or 'c') |
| no plot being declared | FIG_ERR_STATE | <p>: no plot is being declared (call it between a true ip_begin_plot and ip_end_plot) |
a setup call after an item, ip_set_axes or ip_plot_limits | FIG_ERR_STATE | <p>: the setup of the plot is over (call the ip_setup_* procedures before the first item, ip_set_axes and ip_plot_limits) |
| an axis not set up on this frame | FIG_ERR_STATE | <p>: axis '<axis>' is not set up (call ip_setup_axis('<axis>') first, on every frame) |
test_plot_tick of an axis not set up | FIG_ERR_STATE | test_plot_tick: axis '<axis>' is not set up (ip_setup_axis('<axis>')) |
Changed in v0.4.0
Until v0.3.1 ip_setup_axes, ip_setup_axes_limits and ip_plot_limits outside a plot, or a setup call after an item, reached ImPlot's assertions: the program aborted inside implot.cpp, naming no Fortran call. From v0.4.0 they are usage errors with the messages above.
Plot queries and marks
The calls that read a plot (Reading a plot), its marks (Marks in a plot), the drag tools and every item (from v0.8.0; until then an item outside a plot reached ImPlot, which dereferenced a null plot in modes 'report' and 'recover') check their arguments and their place as the axis calls do (Plot axes: the axis names, an axis not set up, no plot being declared give the messages there). <p> is the procedure.
| Failure | Status | Message |
|---|---|---|
no plot being declared (also ip_drag_line_x, ip_drag_line_y, ip_drag_point, from v0.4.0) | FIG_ERR_STATE | <p>: no plot is being declared (call it between a true ip_begin_plot and ip_end_plot) |
ip_tag on an axis not set up | FIG_ERR_STATE | ip_tag: axis '<axis>' is not set up (call ip_setup_axis('<axis>') first, on every frame) |
| a NaN coordinate or pixel | FIG_ERR_ARGUMENT | ip_plot_to_pixels: x and y must not be NaN; ip_pixels_to_plot: px and py must not be NaN; ip_text: x and y must not be NaN; ip_tag: the value is NaN; ip_drag_rect: an edge is NaN |
| a colour without 4 components | FIG_ERR_ARGUMENT | <p>: a colour needs 4 components (RGBA) |
| an offset without 2 components | FIG_ERR_ARGUMENT | ip_text: the offset needs 2 components (x, y) |
bins 0, or below ImPlotBin_Scott | FIG_ERR_ARGUMENT | ip_histogram: bins must be a count above 0 or an ImPlotBin_* rule (xbins, ybins) |
one end of a histogram's range without the other; a NaN end; vmin >= vmax | FIG_ERR_ARGUMENT | ip_histogram: give both vmin and vmax, or neither; vmin and vmax must not be NaN; vmin must be below vmax (xmin/xmax, ymin/ymax) |
| series of different sizes | FIG_ERR_ARGUMENT | <p>: the series have different sizes |
| a colormap not registered | FIG_ERR_ARGUMENT | ip_histogram2d: the colormap <id> is not registered (see ip_colormap) |
Drag and drop
ig_drag_source, ig_drop_target and ip_drop_target (Drag and drop, A plot as a drop target); ip_drop_target's place and axis give the messages of Plot axes. <p> is the procedure.
| Failure | Status | Message |
|---|---|---|
| a type of no or more than 32 characters | FIG_ERR_ARGUMENT | <p>: type '<type>' must have 1 to 32 characters |
a type starting with _ | FIG_ERR_ARGUMENT | <p>: type '<type>' starts with '_' (Dear ImGui's own types) |
ip_drop_target with both axis and legend | FIG_ERR_ARGUMENT | ip_drop_target: give axis or legend, not both |
Plots across plots
ip_link_axis, ip_begin_aligned, the legend's calls, ip_hide_next_item, ip_digital and ip_bar_groups (Plots across plots, Grouped bars); their place and axis give the messages of Plot axes and the pairs.
| Failure | Status | Message |
|---|---|---|
| an empty group name | FIG_ERR_ARGUMENT | ip_link_axis: the group has no name |
| a group inside a group | FIG_ERR_STATE | ip_begin_aligned: a group of aligned plots is open (ImPlot aligns one group at a time) |
| an unknown button | FIG_ERR_ARGUMENT | ip_begin_legend_popup: button must be 'left', 'right' or 'middle' |
| labels and items that differ in number | FIG_ERR_ARGUMENT | ip_bar_groups: <n> labels for <m> items (size(values, 2)) |
| no values | FIG_ERR_ARGUMENT | ip_bar_groups: no values |
group_size outside (0, 1] | FIG_ERR_ARGUMENT | ip_bar_groups: group_size must be in (0, 1] |
Multi-selection
ig_begin_multi_select, ig_end_multi_select and the index of ig_selectable and ig_tree_node (Selecting many items); a wrong end gives the messages of the pairs.
| Failure | Status | Message |
|---|---|---|
| a multi-selection inside another | FIG_ERR_STATE | ig_begin_multi_select: a multi-selection is open (Dear ImGui allows one at a time) |
index with none open | FIG_ERR_STATE | <p>: index is given, but no multi-selection is open (ig_begin_multi_select) |
index outside the items | FIG_ERR_ARGUMENT | <p>: index <i> is out of 1 to <n> |
Fields
ip_field_image, ip_colormap_legend and ip_colormap_legend_edit (Fields) check their arguments on the Fortran side; a field outside a plot is a usage error, as the plot queries. <p> is the procedure.
| Failure | Status | Message |
|---|---|---|
no plot being declared (ip_field_image) | FIG_ERR_STATE | ip_field_image: no plot is being declared (call it between a true ip_begin_plot and ip_end_plot) |
an unknown scale ('time' included) | FIG_ERR_ARGUMENT | <p>: unknown scale '<scale>' ('linear', 'log' or 'symlog') |
vmin or vmax not finite; equal | FIG_ERR_ARGUMENT | ip_field_image: vmin must be finite (vmax); vmin and vmax must differ |
vmin or vmax <= 0 on 'log' | FIG_ERR_ARGUMENT | ip_field_image: a log scale needs vmin above 0 (vmax); <p>: a log scale needs vmin and vmax above 0 (legends) |
edges not finite, or x0 == x1, y0 == y1 | FIG_ERR_ARGUMENT | ip_field_image: the edges must be finite, x0 /= x1 and y0 /= y1 |
nan_color without 4 components; outside [0, 1] | FIG_ERR_ARGUMENT | ip_field_image: nan_color needs 4 components (RGBA); nan_color components must be in [0, 1] |
| more than 16 384 values a side | FIG_ERR_ARGUMENT | ip_field_image: a field of at most 16384 values a side (a texture) |
| a colormap not registered | FIG_ERR_ARGUMENT | <p>: the colormap <id> is not registered (see ip_colormap) |
The legends' other failures (levels, formats, equal ends) are those of ip_colormap_legend.
Players
ig_player (Players) checks the player_object and labels on the Fortran side, before it draws: a wrong one is FIG_ERR_ARGUMENT, nothing drawn and .false. returned (absent stat, error stop with the message). No frame open, or a task, is FIG_ERR_STATE, as for every widget.
| Failure | Status | Message |
|---|---|---|
count < 1 | FIG_ERR_ARGUMENT | ig_player: count must be at least 1 (got <count>) |
speed <= 0, NaN or infinite | FIG_ERR_ARGUMENT | ig_player: speed must be > 0 snapshots per second |
an unknown mode | FIG_ERR_ARGUMENT | ig_player: unknown mode "<mode>" ('once', 'loop' or 'bounce') |
labels not of count entries | FIG_ERR_ARGUMENT | ig_player: labels has <n> entries, not count |
An index outside 1 to count is not an error: the player moves it to the nearest end and returns .true..
Application layer
The window registry, the layouts, the preferences, the message boxes, the splitter and the size limits check their arguments in the native layer; each section has its table of messages: Windows and layouts, Preferences, Message boxes, Splitters. In short:
| Failure | Status | Message |
|---|---|---|
| a window or a layout added twice, or with an empty name | FIG_ERR_ARGUMENT | app%add_window: '<name>' is added already, app%add_layout: the name is empty |
| a window or a layout not added | FIG_ERR_ARGUMENT | app%window_visible: no window '<name>' was added, app%switch_layout: no layout '<name>' was added |
| a preferences' name that is not a folder's | FIG_ERR_ARGUMENT | app%open_prefs: the name '<name>' is a folder's name: letters, digits, blanks and . _ - (not first a .) |
open_prefs a second time | FIG_ERR_STATE | app%open_prefs: the preferences are open already (<file>) |
| a malformed key | FIG_ERR_ARGUMENT | app%save_pref: the key '<key>' is empty, has a newline, a blank at an end, or starts with [ # ; |
| a message box without an id, or with every label empty | FIG_ERR_ARGUMENT | app%message_box: the id is empty, app%message_box: every button label is empty |
ig_splitter without two sizes | FIG_ERR_ARGUMENT | ig_splitter: sizes has two values, the panes on either side |
| size limits below 0, a maximum below its minimum | FIG_ERR_ARGUMENT | app%set_size_limits: a negative size, app%set_size_limits: a maximum below its minimum |
before init* | FIG_ERR_STATE | <procedure>: figure is not initialized |
A preference that is not of the kind asked is not an error: load_pref returns .false. and gives the default. A save of the file that fails is printed once on standard error; the program goes on.
Processes, tasks and tests
Processes and tasks check their state on the Fortran side and report what the system refuses; the statuses of each are listed on their page, the messages here. A task's own failure reaches the program through t%result, on the main thread.
| Failure | Status | Message |
|---|---|---|
p%start while the object's process still runs | FIG_ERR_STATE | process_object%start: its process still runs: kill it or wait for its end |
| a program that cannot be started; a log file that cannot be written | FIG_ERR_FAILED | process: cannot start '<program>': not found in PATH (or the system's reason), process: cannot write the log file '<file>': <reason> |
p%exit_code before start, while the process runs, of a detached process (the result is -1) | FIG_ERR_STATE | process_object%exit_code: no process started, process_object%exit_code: the process still runs, process_object%exit_code: the exit code of a detached process is not known |
p%kill before start; a kill the system refuses | FIG_ERR_STATE; FIG_ERR_FAILED | process_object%kill: no process started; process: cannot kill: <SDL's reason> |
t%start while the object's task runs; from a task | FIG_ERR_STATE | task_object%start: its task still runs: cancel it or wait for its end; task: a task cannot start another task |
| no thread can be created | FIG_ERR_FAILED | task: cannot start a thread: <SDL's reason> |
t%cancel or t%result before start; t%result before the task is done | FIG_ERR_STATE | task_object%cancel: no task started, task_object%result: no task started, task_object%result: the task still runs |
t%result of a task that called h%fail | FIG_ERR_FAILED | the task's message (its first failure) |
t%result of a task that called a drawing procedure (init* included) | FIG_ERR_STATE | <procedure>: a drawing procedure called from a task (only the main thread draws); the task is asked to stop |
init_remote on a port in use, or not permitted | FIG_ERR_FAILED | the system's reason |
app%image_result after a save_image whose file cannot be written | FIG_ERR_FAILED | the reason |
The test procedures (figure_testing) fail as the rows of Status codes say: a path that names no item, a test not idle after max_frames, a picture that cannot be read (Headless testing).
Code editor
The code editor and the diff check their arguments in the native layer, language_object%init and code_language on the Fortran side:
| Failure | Status | Message |
|---|---|---|
an editor procedure before init | FIG_ERR_STATE | code_editor_object%<procedure>: the editor is not initialized |
insert or replace in a read-only editor | FIG_ERR_STATE | code_editor_object%insert: the editor is read-only |
draw with an empty id, code_diff with one | FIG_ERR_ARGUMENT | code_editor_object%draw: the id is empty, code_diff: the id is empty |
a line past the last for mark, below 1 for any | FIG_ERR_ARGUMENT | code_editor_object%mark: line <n> is past the last, <count>, code_editor_object%goto: lines and columns are numbered from 1 |
| an unknown severity | FIG_ERR_ARGUMENT | code_editor_object%mark: severity must be 'error', 'warning' or 'info' |
| an empty text to find or replace | FIG_ERR_ARGUMENT | code_editor_object%find: the text is empty |
| a tab size outside [1, 16] | FIG_ERR_ARGUMENT | code_editor_object%set_options: tab_size must be in [1, 16] |
| an unknown language name | FIG_ERR_ARGUMENT | code_language: unknown language "<name>" |
| an empty language name, a keyword or type with a blank, a longer preprocessor | FIG_ERR_ARGUMENT | language_object%init: the name is empty, language_object%init: a keyword is empty or holds a blank, language_object%init: the preprocessor is one character |
The queries (text, line_count, mark_of, cursor, selection, word_at_cursor, completing, is_read_only, line_rect) fail on nothing: before init they return their empty value. A task calling an editor procedure is refused as any drawing procedure is.
Markdown
Markdown (ig_markdown, markdown_view_object) checks its arguments in the native layer:
| Failure | Status | Message |
|---|---|---|
ig_markdown or md%draw with no frame open | FIG_ERR_STATE | ig_markdown: no frame open, markdown_view_object%draw: no frame open |
a document procedure before md%init | FIG_ERR_STATE | markdown_view_object%<procedure>: the view is not initialized |
md%draw with an empty id | FIG_ERR_ARGUMENT | markdown_view_object%draw: the id is empty |
md%find with a text over 255 bytes, or of more than one line | FIG_ERR_ARGUMENT | markdown_view_object%find: the text is longer than 255 bytes, markdown_view_object%find: the text is more than one line |
md%scroll_to with an empty heading | FIG_ERR_ARGUMENT | markdown_view_object%scroll_to: the heading is empty |
md%load with an empty name | FIG_ERR_ARGUMENT | markdown_view_object%load: no file name |
md%load of a file that cannot be read (the text kept) | FIG_ERR_FAILED | markdown_view_object%load: '<path>' cannot be read: <SDL's reason> |
| the bundled fonts not loaded into the atlas | FIG_ERR_FAILED | markdown: cannot load the font <name> (or cannot merge ...) |
The queries (md%text, md%matches, md%current_match) fail on nothing: before init they return their empty value. A task calling a Markdown procedure is refused as any drawing procedure is. A heading md%scroll_to names that the text lacks is not an error: nothing happens.
Gizmos and the gradient editor
The view cube and the gizmos and the gradient editor check their arguments on the Fortran side (names) and in the native layer (values):
| Failure | Status | Message |
|---|---|---|
view_cube or gizmo before draw in this frame and window | FIG_ERR_STATE | view3d_object%view_cube: draw the view first, in this frame and in this window |
| a cube's size not above 0, an unknown corner | FIG_ERR_ARGUMENT | view3d_object%view_cube: the size must be positive, view3d_object%view_cube: corner must be 'top-right', 'top-left', 'bottom-right' or 'bottom-left', got '<corner>' |
| an unknown mode or space | FIG_ERR_ARGUMENT | view3d_object%gizmo: mode must be 'translate', 'rotate' or 'scale', got '<mode>', view3d_object%gizmo: space must be 'world' or 'local', got '<space>' |
| a snap not above 0 | FIG_ERR_ARGUMENT | view3d_object%gizmo: snap must be positive |
| a matrix not finite, or whose last row is not (0, 0, 0, 1) | FIG_ERR_ARGUMENT | view3d_object%gizmo: the matrix is not finite, view3d_object%gizmo: the matrix's last row must be (0, 0, 0, 1) |
an unknown map (a discrete name, <name>|<levels>, included) | FIG_ERR_ARGUMENT | ig_gradient_edit: unknown colormap '<name>' (ip_colormap_names lists them) |
| a reversed map | FIG_ERR_ARGUMENT | ig_gradient_edit: '<name>_r' is a reversed map: edit '<name>' |
| a qualitative map | FIG_ERR_ARGUMENT | ig_gradient_edit: 'Deep' is qualitative (a list of colours, not a scale): it has no gradient |
ip_colormap_stops refuses the same maps, its messages starting ip_colormap_stops:. On a failure a gizmo leaves its matrix and the camera as they were and returns .false.; view_matrix and projection_matrix fail only on a view not initialized (FIG_ERR_STATE), their matrix then zero.
ImPlot3D
The 3-D plots check their arguments on the Fortran side, before ImPlot3D sees them (ImPlot3D asserts on an item outside a plot and on a setup after the first item):
| Failure | Status | Message |
|---|---|---|
an item, a text or ip3_setup_axes outside a 3-D plot | FIG_ERR_STATE | ip3_line: no 3-D plot is being declared (call it between ip3_begin_plot and ip3_end_plot), ip3_setup_axes: no 3-D plot is being declared (call it after ip3_begin_plot returned true) |
ip3_setup_axes after an item | FIG_ERR_STATE | ip3_setup_axes: the setup of the 3-D plot is over (call it before the first item) |
series of different sizes, more points than a C int counts | FIG_ERR_ARGUMENT | ip3_line: the series have different sizes, ip3_line: more points than a C int can count (and the same for ip3_scatter, ip3_mesh) |
x, y that do not match z | FIG_ERR_ARGUMENT | ip3_surface: x and y must match z: size(x) = size(z, 1), size(y) = size(z, 2) (or x and y of the shape of z), ip3_surface: x, y and z of a grid must have the same shape |
| one scale end, a minimum not below the maximum | FIG_ERR_ARGUMENT | ip3_surface: give both scale_min and scale_max, or neither, ip3_surface: scale_min must be below scale_max |
| a colormap not registered | FIG_ERR_ARGUMENT | ip3_surface: the colormap <id> is not registered (see ip_colormap) |
triangles without 3 rows, a vertex outside [1, size(x)] | FIG_ERR_ARGUMENT | ip3_mesh: triangles needs 3 rows (the vertices of each triangle), ip3_mesh: a triangle has a vertex outside [1, size(x)] |
limits without 6 values, or a minimum not below its maximum; one angle | FIG_ERR_ARGUMENT | ip3_setup_axes: limits needs 6 values (xmin, xmax, ymin, ymax, zmin, zmax), ip3_setup_axes: each minimum of limits must be below its maximum, ip3_setup_axes: give both elevation and azimuth, or neither |
| a NaN position, an offset without 2 values | FIG_ERR_ARGUMENT | ip3_text: x, y and z must not be NaN, ip3_text: the offset needs 2 components (x, y) |
| a colour without 4 values | FIG_ERR_ARGUMENT | ip3_spec: a colour needs 4 components (RGBA) |
| triangles or quads of a vertex count not a multiple of 3 or 4 | FIG_ERR_ARGUMENT | ip3_triangles: <n> vertices are not a whole number of triangles (3 each), ip3_quads: <n> vertices are not a whole number of quads (4 each) |
| an image's corners not 3 × 4, a tint without 4 values, a texture not initialized | FIG_ERR_ARGUMENT | ip3_image: corners must be 3 x 4 (x, y, z of four corners), ip3_image: a colour needs 4 components (RGBA), ip3_image: the texture is not initialized (texture%init) |
| an unknown axis, scale or legend location | FIG_ERR_ARGUMENT | ip3_setup_axis: unknown axis '<a>' ('x', 'y' or 'z'), ip3_setup_axis: unknown scale '<s>' ('linear', 'log' or 'symlog'), ip3_setup_legend: unknown location '<l>' ('n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw' or 'c') |
| a box scale without 3 positive values; one angle | FIG_ERR_ARGUMENT | ip3_setup_box: scale needs 3 values (x, y, z), ip3_setup_box: each value of scale must be above 0, ip3_setup_box: give both elevation and azimuth, or neither |
per-point colours not (4, size(x)) or out of [0, 1], sizes not one per point or below 0 | FIG_ERR_ARGUMENT | ip3_scatter: colors must be (4, size(x)): one RGBA per point, ip3_scatter: colour components must be in [0, 1], ip3_scatter: sizes must be one per point, ip3_scatter: sizes must be finite and not below 0 (and ip3_line's colours) |
| a format that is not one real's; tick labels not one per value, values not finite | FIG_ERR_ARGUMENT | ip3_setup_axis: format '<f>' is not a format of a real: ..., ip3_setup_axis_ticks: labels must be one per value, ip3_setup_axis_ticks: values must be finite |
an unknown ImPlot3D colour or variable (ip3_push_style_*) | FIG_ERR_ARGUMENT | push style colour: unknown name "<n>", push style variable: unknown name "<n>" |
ip3_setup_axis, ip3_setup_axis_ticks, ip3_setup_box, ip3_setup_legend outside a 3-D plot or after an item | FIG_ERR_STATE | as ip3_setup_axes |
ip3_image, ip3_mouse_ray, ip3_plot_to_pixels outside a 3-D plot | FIG_ERR_STATE | as the items |
A refused item draws nothing; the plot goes on. An ip3_end_plot without a true ip3_begin_plot is a pairing error (Pairing and frames).