Skip to content

Error handling ​

stat or error stop ​

Procedures that can fail take an optional integer(int32), intent(out) :: stat:

  • with stat, a failure is returned: stat receives FIG_OK or a FIG_ERR_* code, and figure_last_error() gives the message;
  • without stat, a failure writes FIGURE error: <message> to standard error and stops the program with error 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).

fortran
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()//'"'
text
$ ./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:

fortran
call app%init_headless(400_int32, 300_int32)
call app%init_headless(400_int32, 300_int32) ! already initialized: error stop
text
$ ./cb_error_stop
FIGURE error: figure is already initialized
ERROR STOP 1
[exit status 1]

Status codes ​

CodeValueMeaning
FIG_OK0success
FIG_ERR_STATE1call 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_ARGUMENT2invalid 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_FAILED3the 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_EXCEPTION4a 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).

fortran
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()
endif

A 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:

fortran
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 argumentMessage
ig_input, formatig_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_angleas ig_input's above, starting with the procedure's name
ip_setup_axes, xformat / yformatthe same, starting ip_setup_axes: xformat (or yformat)
ip_setup_axis, formatthe same, starting ip_setup_axis: format
ip_heatmap, ip_colormap_scale, ip_colormap_legend, label_formatthe 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 ​

RulePairs
Always paired: the end follows every begin, whatever it returnedig_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 beginig_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_begin and 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's End requires.
  • Everything is closed by the end of the frame: what is still open when next_frame is 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_frame or 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's init, 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 openerror stop at the call, the message on standard errorrefused (it does nothing); the frame goes onas '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_frameerror stop at next_frameclosed by FIGURE, in reverse orderclosed 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 messagesFIG_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 therethe samethe same
Dear ImGui's own checks (raw calls)its assertions, as beforeits error recovery, the message (Dear ImGui: Missing PopID()) among the frame'sthe 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 messagesgoes 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: stat is optional (absent: error stop with the message). FIG_ERR_ARGUMENT for an unknown mode (Messages); FIG_ERR_STATE from 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).
fortran
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 grid
fortran
call 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()
text
$ ./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).

ErrorMessage
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 frameapp%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 frameapp%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 modeapp%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_column outside 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 igEnd for an ig_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: destroy closes 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).

FailureMessage
a format of the other family, with no conversion or more than oneas 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 boundsig_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 precisionig_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').

FailureStatusMessage
columns outside 1 to 511FIG_ERR_ARGUMENTig_begin_table: columns <n> is out of 1 to 511
freeze_rows outside 0 to 127FIG_ERR_ARGUMENTig_begin_table: freeze_rows <n> is out of 0 to 127
freeze_cols outside 0 to columnsFIG_ERR_ARGUMENTig_begin_table: freeze_cols <n> is out of 0 to the columns
width and stretch togetherFIG_ERR_ARGUMENTig_table_setup_column: give width or stretch, not both
a negative or NaN widthFIG_ERR_ARGUMENTig_table_setup_column: width <w> is negative (width NaN is not a width)
stretch not above 0, or NaNFIG_ERR_ARGUMENTig_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 NaNFIG_ERR_ARGUMENTig_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 columnsFIG_ERR_ARGUMENT<call>: column <n> is out of 1 to <columns>
no table openFIG_ERR_STATE<call>: no table is open (call it between ig_begin_table and ig_end_table)
ig_table_sort in a table not sortableFIG_ERR_STATEig_table_sort: the table is not sortable (ig_begin_table(..., sortable=.true.))
ig_table_sort before every column is declaredFIG_ERR_STATEig_table_sort: call it after every column is declared (ig_table_setup_column)
ig_table_column_enabled in a table not hideableFIG_ERR_STATEig_table_column_enabled: the table is not hideable (ig_begin_table(..., hideable=.true.))
ig_table_row_color before the first rowFIG_ERR_STATEig_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').

FailureStatusMessage
an unknown layerFIG_ERR_ARGUMENT<p>: unknown layer '<layer>' ('window', 'foreground', 'background' or 'plot')
color not of 3 or 4 componentsFIG_ERR_ARGUMENT<p>: color has 3 or 4 components
a component of color outside [0, 1] or NaNFIG_ERR_ARGUMENT<p>: color components are in [0, 1]
x and y of different sizesFIG_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 precisionFIG_ERR_ARGUMENT<p>: x must be finite and within single precision (y)
thickness not above 0, NaN or infiniteFIG_ERR_ARGUMENT<p>: thickness is not a finite length above 0
radius below 0, NaN or infiniteFIG_ERR_ARGUMENTig_draw_circle: radius is not a finite length >= 0
a texture not initializedFIG_ERR_ARGUMENTig_draw_image: the texture is not initialized (ig_canvas: ...)
a canvas or invisible button size NaN or infiniteFIG_ERR_ARGUMENT<p>: width and height must be finite and within single precision
layer='plot' outside a plotFIG_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.

FailureStatusMessage
an unknown axis nameFIG_ERR_ARGUMENT<p>: unknown axis '<axis>' ('x1', 'x2', 'x3', 'y1', 'y2' or 'y3')
a y axis where an x axis is expected, or the reverseFIG_ERR_ARGUMENT<p>: x '<axis>' is not an x axis ('x1', 'x2' or 'x3') (y, xaxis, yaxis)
an unknown scaleFIG_ERR_ARGUMENT<p>: unknown scale '<scale>' ('linear', 'log', 'symlog' or 'time') (xscale, yscale)
'time' on a y axisFIG_ERR_ARGUMENTip_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_ARGUMENTip_setup_axes: xlog and xscale '<scale>' disagree (give xscale only: xlog is deprecated)
a limit NaN, or vmin >= vmaxFIG_ERR_ARGUMENTip_setup_axis_limits: vmin and vmax must not be NaN; vmin must be below vmax
tick values not finite; labels not one per valueFIG_ERR_ARGUMENTip_setup_axis_ticks: values must be finite; labels must be one per value
a constraint NaN; vmin >= vmax; zoom_min > zoom_max; a negative widthFIG_ERR_ARGUMENTip_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 axisFIG_ERR_ARGUMENTip_setup_axis_constraints: vmin must be above 0 on the log axis '<axis>'
an unknown legend locationFIG_ERR_ARGUMENTip_setup_legend: unknown location '<location>' ('n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw' or 'c')
no plot being declaredFIG_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_limitsFIG_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 frameFIG_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 upFIG_ERR_STATEtest_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.

FailureStatusMessage
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 upFIG_ERR_STATEip_tag: axis '<axis>' is not set up (call ip_setup_axis('<axis>') first, on every frame)
a NaN coordinate or pixelFIG_ERR_ARGUMENTip_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 componentsFIG_ERR_ARGUMENT<p>: a colour needs 4 components (RGBA)
an offset without 2 componentsFIG_ERR_ARGUMENTip_text: the offset needs 2 components (x, y)
bins 0, or below ImPlotBin_ScottFIG_ERR_ARGUMENTip_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 >= vmaxFIG_ERR_ARGUMENTip_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 sizesFIG_ERR_ARGUMENT<p>: the series have different sizes
a colormap not registeredFIG_ERR_ARGUMENTip_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.

FailureStatusMessage
a type of no or more than 32 charactersFIG_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 legendFIG_ERR_ARGUMENTip_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.

FailureStatusMessage
an empty group nameFIG_ERR_ARGUMENTip_link_axis: the group has no name
a group inside a groupFIG_ERR_STATEip_begin_aligned: a group of aligned plots is open (ImPlot aligns one group at a time)
an unknown buttonFIG_ERR_ARGUMENTip_begin_legend_popup: button must be 'left', 'right' or 'middle'
labels and items that differ in numberFIG_ERR_ARGUMENTip_bar_groups: <n> labels for <m> items (size(values, 2))
no valuesFIG_ERR_ARGUMENTip_bar_groups: no values
group_size outside (0, 1]FIG_ERR_ARGUMENTip_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.

FailureStatusMessage
a multi-selection inside anotherFIG_ERR_STATEig_begin_multi_select: a multi-selection is open (Dear ImGui allows one at a time)
index with none openFIG_ERR_STATE<p>: index is given, but no multi-selection is open (ig_begin_multi_select)
index outside the itemsFIG_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.

FailureStatusMessage
no plot being declared (ip_field_image)FIG_ERR_STATEip_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; equalFIG_ERR_ARGUMENTip_field_image: vmin must be finite (vmax); vmin and vmax must differ
vmin or vmax <= 0 on 'log'FIG_ERR_ARGUMENTip_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 == y1FIG_ERR_ARGUMENTip_field_image: the edges must be finite, x0 /= x1 and y0 /= y1
nan_color without 4 components; outside [0, 1]FIG_ERR_ARGUMENTip_field_image: nan_color needs 4 components (RGBA); nan_color components must be in [0, 1]
more than 16 384 values a sideFIG_ERR_ARGUMENTip_field_image: a field of at most 16384 values a side (a texture)
a colormap not registeredFIG_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.

FailureStatusMessage
count < 1FIG_ERR_ARGUMENTig_player: count must be at least 1 (got <count>)
speed <= 0, NaN or infiniteFIG_ERR_ARGUMENTig_player: speed must be > 0 snapshots per second
an unknown modeFIG_ERR_ARGUMENTig_player: unknown mode "<mode>" ('once', 'loop' or 'bounce')
labels not of count entriesFIG_ERR_ARGUMENTig_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:

FailureStatusMessage
a window or a layout added twice, or with an empty nameFIG_ERR_ARGUMENTapp%add_window: '<name>' is added already, app%add_layout: the name is empty
a window or a layout not addedFIG_ERR_ARGUMENTapp%window_visible: no window '<name>' was added, app%switch_layout: no layout '<name>' was added
a preferences' name that is not a folder'sFIG_ERR_ARGUMENTapp%open_prefs: the name '<name>' is a folder's name: letters, digits, blanks and . _ - (not first a .)
open_prefs a second timeFIG_ERR_STATEapp%open_prefs: the preferences are open already (<file>)
a malformed keyFIG_ERR_ARGUMENTapp%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 emptyFIG_ERR_ARGUMENTapp%message_box: the id is empty, app%message_box: every button label is empty
ig_splitter without two sizesFIG_ERR_ARGUMENTig_splitter: sizes has two values, the panes on either side
size limits below 0, a maximum below its minimumFIG_ERR_ARGUMENTapp%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.

FailureStatusMessage
p%start while the object's process still runsFIG_ERR_STATEprocess_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 writtenFIG_ERR_FAILEDprocess: 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_STATEprocess_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 refusesFIG_ERR_STATE; FIG_ERR_FAILEDprocess_object%kill: no process started; process: cannot kill: <SDL's reason>
t%start while the object's task runs; from a taskFIG_ERR_STATEtask_object%start: its task still runs: cancel it or wait for its end; task: a task cannot start another task
no thread can be createdFIG_ERR_FAILEDtask: cannot start a thread: <SDL's reason>
t%cancel or t%result before start; t%result before the task is doneFIG_ERR_STATEtask_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%failFIG_ERR_FAILEDthe 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 permittedFIG_ERR_FAILEDthe system's reason
app%image_result after a save_image whose file cannot be writtenFIG_ERR_FAILEDthe 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:

FailureStatusMessage
an editor procedure before initFIG_ERR_STATEcode_editor_object%<procedure>: the editor is not initialized
insert or replace in a read-only editorFIG_ERR_STATEcode_editor_object%insert: the editor is read-only
draw with an empty id, code_diff with oneFIG_ERR_ARGUMENTcode_editor_object%draw: the id is empty, code_diff: the id is empty
a line past the last for mark, below 1 for anyFIG_ERR_ARGUMENTcode_editor_object%mark: line <n> is past the last, <count>, code_editor_object%goto: lines and columns are numbered from 1
an unknown severityFIG_ERR_ARGUMENTcode_editor_object%mark: severity must be 'error', 'warning' or 'info'
an empty text to find or replaceFIG_ERR_ARGUMENTcode_editor_object%find: the text is empty
a tab size outside [1, 16]FIG_ERR_ARGUMENTcode_editor_object%set_options: tab_size must be in [1, 16]
an unknown language nameFIG_ERR_ARGUMENTcode_language: unknown language "<name>"
an empty language name, a keyword or type with a blank, a longer preprocessorFIG_ERR_ARGUMENTlanguage_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:

FailureStatusMessage
ig_markdown or md%draw with no frame openFIG_ERR_STATEig_markdown: no frame open, markdown_view_object%draw: no frame open
a document procedure before md%initFIG_ERR_STATEmarkdown_view_object%<procedure>: the view is not initialized
md%draw with an empty idFIG_ERR_ARGUMENTmarkdown_view_object%draw: the id is empty
md%find with a text over 255 bytes, or of more than one lineFIG_ERR_ARGUMENTmarkdown_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 headingFIG_ERR_ARGUMENTmarkdown_view_object%scroll_to: the heading is empty
md%load with an empty nameFIG_ERR_ARGUMENTmarkdown_view_object%load: no file name
md%load of a file that cannot be read (the text kept)FIG_ERR_FAILEDmarkdown_view_object%load: '<path>' cannot be read: <SDL's reason>
the bundled fonts not loaded into the atlasFIG_ERR_FAILEDmarkdown: 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):

FailureStatusMessage
view_cube or gizmo before draw in this frame and windowFIG_ERR_STATEview3d_object%view_cube: draw the view first, in this frame and in this window
a cube's size not above 0, an unknown cornerFIG_ERR_ARGUMENTview3d_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 spaceFIG_ERR_ARGUMENTview3d_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 0FIG_ERR_ARGUMENTview3d_object%gizmo: snap must be positive
a matrix not finite, or whose last row is not (0, 0, 0, 1)FIG_ERR_ARGUMENTview3d_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_ARGUMENTig_gradient_edit: unknown colormap '<name>' (ip_colormap_names lists them)
a reversed mapFIG_ERR_ARGUMENTig_gradient_edit: '<name>_r' is a reversed map: edit '<name>'
a qualitative mapFIG_ERR_ARGUMENTig_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):

FailureStatusMessage
an item, a text or ip3_setup_axes outside a 3-D plotFIG_ERR_STATEip3_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 itemFIG_ERR_STATEip3_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 countsFIG_ERR_ARGUMENTip3_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 zFIG_ERR_ARGUMENTip3_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 maximumFIG_ERR_ARGUMENTip3_surface: give both scale_min and scale_max, or neither, ip3_surface: scale_min must be below scale_max
a colormap not registeredFIG_ERR_ARGUMENTip3_surface: the colormap <id> is not registered (see ip_colormap)
triangles without 3 rows, a vertex outside [1, size(x)]FIG_ERR_ARGUMENTip3_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 angleFIG_ERR_ARGUMENTip3_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 valuesFIG_ERR_ARGUMENTip3_text: x, y and z must not be NaN, ip3_text: the offset needs 2 components (x, y)
a colour without 4 valuesFIG_ERR_ARGUMENTip3_spec: a colour needs 4 components (RGBA)
triangles or quads of a vertex count not a multiple of 3 or 4FIG_ERR_ARGUMENTip3_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 initializedFIG_ERR_ARGUMENTip3_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 locationFIG_ERR_ARGUMENTip3_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 angleFIG_ERR_ARGUMENTip3_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 0FIG_ERR_ARGUMENTip3_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 finiteFIG_ERR_ARGUMENTip3_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_ARGUMENTpush 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 itemFIG_ERR_STATEas ip3_setup_axes
ip3_image, ip3_mouse_ray, ip3_plot_to_pixels outside a 3-D plotFIG_ERR_STATEas 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).

Released under the MIT licence.