Skip to content

Feature map ​

use figure exports everything below except the testing procedures (use figure_testing). The modules it re-exports (the modules) can also be used directly; figure_c_native and the generated raw layer (figure_cimgui, figure_cimplot, figure_cimplot3d and their _enums) is internal: programs call the wrappers, and a Dear ImGui or ImPlot function without one is listed as "raw only" in Dear ImGui names (Raw bindings). A few names are public in their module for FIGURE's other modules only, not API, and figure does not re-export them: plot_copies, plot_stride and the series_* helpers of figure_implot (for figure_implot3d, and for test_plot_copies and test_plot_stride), and texture_ref of figure_texture (for the modules that draw a texture).

How to read a row: the call, its optional arguments in brackets (→ gives a function's result); what it is for; and, in parentheses, the section that documents it, with its statuses and an example. All kinds are those of iso_fortran_env: int32, real32, real64. Optional arguments are in brackets. A name of Dear ImGui's or ImPlot's documentation (SetScrollHereY, PlotLine) is found in the name map, with the FIGURE call that exposes it.

Application: app_object ​

ProcedurePurpose
app%init(title, width, height [, vsync] [, stat] [, ini_file] [, decorations] [, buttons])open the window (decorations='figure': its frame drawn by FIGURE, the menus in the title bar), create the ImGui and ImPlot contexts (frame loop, the window's frame)
app%init_headless(width, height [, stat] [, decorations] [, buttons])contexts only, on a virtual display: no window, no GPU (decorations='figure': the title bar drawn, for tests) (headless testing)
app%set_icon(image [, stat]), app%set_icon(icon [, stat])the window's icon: an RGBA image integer(int8) :: image(4, width, height), or an ICON_* (window mode) (the window's frame)
app%init_remote([port] [, host] ...)the interface in a web browser: no window, display or GPU on the program's side (remote UI)
app%next_frame([stat]) → logicalrender the open frame, wait for input, open the next; .false. on quit (frame loop)
app%set_checks(mode [, stat])what a usage error (a wrong end, a scope left open, a drawing call with no frame open) does: 'abort', 'report' (default), 'recover' (usage checks)
app%set_lazy(enabled [, max_wait])lazy redraw on/off, longest sleep (default 0.5 s) (lazy redraw)
app%request_frames(n)draw at least n more frames without waiting for input (lazy redraw)
app%wake()the next frame starts without waiting for input or max_wait, from any thread (waking the loop)
app%set_confirm_quit(enabled)the close button reports a request instead of ending the loop (ask before quitting)
app%quit_requested() → logicalthe user asked to quit, once per request (ask before quitting)
app%dropped(paths [, x] [, y] [, stat]) → logicalthe files and folders dropped on the window since the last frame, and the point of the drop; .true. on that frame only (drops)
app%quit()the next next_frame returns .false. (next_frame)
app%set_title(text [, stat]), app%title() → characterthe window's title after init (window mode shows it; every mode keeps it) (the window's title)
app%open_file_dialog(id [, filters] [, default_path] [, stat] [, prefer]), app%save_file_dialog(...), app%open_folder_dialog(id [, default_path] [, stat] [, prefer])the system's file dialogs (window mode), answered on a later frame; prefer='figure': FIGURE's browser instead, in every mode (file dialogs)
app%open_file_browser(id [, filters] [, default_path] [, folders]), app%save_file_browser(id [, filters] [, default_path])FIGURE's file browser, drawn in Dear ImGui, the same in every mode (remote included): a file to open, a folder, where to save (file browser)
app%file_dialog_result(id, path, done [, cancelled])the answer to a dialog or a browser, once (file dialogs)
app%save_image(path, xmin, ymin, xmax, ymax)a rectangle of the window as a PNG file (every mode: the GPU's pixels in a window, the CPU renderer's in headless and remote modes) (save an image)
app%image_result(path, done)the outcome of save_image, once (save an image)
app%save_layout(path [, comment])the arrangement of the windows (docking included) to a file (layouts)
app%load_layout(path)an arrangement from a file, before the next frame (layouts)
app%add_window(name [, visible] [, closable] [, in_view_menu] [, remember] [, stat])register a window (its ig_begin name): listed in the View menu, a close button that hides it, its visibility kept between runs (windows and layouts)
app%window_visible(name [, stat]) → logical, app%set_window_visible(name, visible [, stat])a registered window is shown (draw it then); show or hide it (windows and layouts)
app%view_menu([label] [, stat])the View menu, in a menu bar: the registered windows, the layouts, Reset layout (windows and layouts)
app%add_layout(name [, windows] [, stat]), app%layout() → characterdeclare a layout of the dock space (and the windows it shows); the current one, which the program builds when ig_dock_layout_begin is true (windows and layouts)
app%switch_layout(name [, stat]), app%reset_layout([stat])make a layout current (as the user left it, or built again); lay the current one out again (windows and layouts)
app%open_prefs(name [, file] [, stat]), app%prefs_file() → characterkeep the preferences in the program's file (the platform's folder for name): read now, written every 30 s when changed and at destroy, through a temporary file (preferences)
app%save_pref(key, value [, stat]), app%load_pref(key, value [, default] [, stat]) → logicalkeep a text, an integer, a real or a logical by key; read it back, or the default (preferences)
app%set_size_limits(min_width, min_height [, max_width] [, max_height] [, stat])the window's least and greatest size (window mode) (preferences)
app%message_box(id, title, text [, buttons] [, stat]) → integer(int32)a question in a modal box drawn by FIGURE: 0 while open, then the button chosen; several at once (message boxes)
app%notify(text [, kind] [, seconds] [, stat])tell the user something in a notification drawn by FIGURE (bottom-right, stacked): 'info', 'success', 'warning', 'error'; it fades after seconds (default 5; 0: until clicked) (notifications)
app%notifications(list [, kinds] [, shown])the notifications kept (the last 100), oldest first (notifications)
app%content_scale() → real(real64)display content scale (frame loop)
app%set_font(font [, size] [, stat])the default font: 'plex-sans' (default, 15 px), 'plex-mono' (monospace), 'proggy', or a TTF/OTF file (styles)
app%add_fallback_font(file [, stat])a TTF/OTF file asked for the glyphs every text font lacks, after Plex, the icons and the bundled Noto Sans Math (Greek, ∇, the operators) (the fallback fonts)
app%load_style(file [, stat]), app%save_style(file [, stat])apply a theme file; write the style in effect as one (styles)
app%set_docking(enabled [, stat])docking on (default) or off (docking)
app%set_style([name] [, lines] [, stat] [, look] [, palette] [, auto_dark] [, auto_light])the style by name ('seal', default, 'seal-light', 'paper', 'high-contrast', 'dark', 'light', 'classic'), or by parts: a look (geometry) and a palette (colours, or 'auto': the system's light or dark setting); lines='okabe-ito' (styles)
app%palette_color(role, rgba [, stat])the colour of a palette role in effect ('text', 'accent', 'error', ...) as [r, g, b, a] in [0, 1] (palette roles)
app%destroy()close the window, destroy the contexts (frame loop)
figure_time() → real(real64)seconds since its first call on a monotonic clock (not stepped by the system, unlike nvfortran's system_clock); before init* and from any thread (time)
figure_make_folder(path [, parents] [, stat])a folder and its missing parents, on every platform (no shell) (files and folders)
figure_remove(path [, recursive] [, stat])remove a file, an empty folder or (recursive) a tree; a missing path is no error (files and folders)
figure_set_file_time(path, time [, stat])a file's or folder's modification time, as a local 'YYYY-MM-DD hh:mm[:ss]' (files and folders)
figure_file_time(path [, stat]) → character(len=19)its modification time, local 'YYYY-MM-DD hh:mm:ss' (files and folders)
figure_file_exists(path) → logicala file or a folder is there (files and folders)

Widgets: ig_* ​

Grouped as Widgets is, in its order; menus, popups and shortcuts last (Menus and shortcuts).

Windows ​

ProcedurePurpose
ig_begin(name [, open] [, flags]) → logicalbegin a window (ImGuiWindowFlags_*); .false. when collapsed or clipped (Windows)
ig_begin_side_bar(name, side, size)a bar along one side of the display (a toolbar), left out of the dock space (Docking)
ig_end()end the window (always, whatever ig_begin returned) (Windows)
ig_set_next_window(x, y [, width, height] [, always])place (and size) the next window (Windows)
ig_focus_window(name) → logicalbring a window forward (a docked one: its tab); refused (.false.) while a popup is open (Windows)

Controls ​

ProcedurePurpose
ig_button(label [, width] [, height]) → logicala button; .true. on the frame it is clicked (Controls)
ig_tool_button(label, icon [, width] [, height] [, selected] [, accent]) → logicala workspace button: an icon above the label, framed; selected tinted in the accent (Controls)
ig_checkbox(label, value) → logicala check box bound to a logical; .true. when toggled (Controls)
ig_input_text(label, value [, hint] [, flags]) → logicala text field bound to a character variable, whose length is the field's capacity; .true. when edited (Controls)
ig_set_next_item_width(width)width of the next widget's field [pixels]; negative: up to that distance from the right edge (Controls)

Text and layout ​

ProcedurePurpose
ig_text_wrapped(text), ig_text_disabled(text), ig_text_colored(text, color)text wrapped at the region's edge, in the disabled colour, in a given colour (Text and layout)
ig_text(text)plain text (Text and layout)
ig_same_line([offset])put the next item on the same line; with offset, at that distance from the left edge (Text and layout)
ig_align_text_to_frame_padding()the text that follows on the line is level with the text of fields and buttons (Text and layout)
ig_text_size(text) → real(real64)(2)width and height of a text in the current font [pixels] (a label: the part before ##) (Text and layout)
ig_separator()horizontal separator (Text and layout)
ig_show_demo_window([open])the Dear ImGui demo window (Text and layout)

Layout ​

ProcedurePurpose
ig_separator_text(label)a separator with a title at its left (Layout)
ig_font_size() → real(real64)the current font size [pixels]: one em (Layout)
ig_em(x) → real(real64)x em [pixels] (x real64 or int32): a size that follows the font (Layout)
ig_line_height([spacing]) → real(real64), ig_frame_height([spacing]) → real(real64)a line of text's height, a framed widget's height [pixels]; with spacing, the distance between two lines, two rows of fields (Layout)
ig_available(w, h)the space left in the window or region from where the next item goes [pixels] (Layout)
ig_spacing(), ig_dummy(w, h), ig_new_line()a gap of the item spacing; an empty item w x h [pixels]; end the line (Layout)
ig_indent([w]), ig_unindent([w])move the lines that follow right by w [pixels] (default: the style's indent), and back (Layout)
ig_begin_group(), ig_end_group()always paired: the items in between count as one item, their bounding rectangle (Layout)
ig_align_begin(id, where [, stat]), ig_align_end()always paired: a group centred ('centre') or right-aligned ('right') on the line; its width from the previous frame (Layout)
ig_align_next(width, where [, stat])centre or right-align the next item, width [pixels] wide (Layout)
ig_push_item_width(w), ig_pop_item_width()always paired: the fields' width [pixels] up to the pop (Layout)

Progress bars ​

ProcedurePurpose
ig_progress_bar(fraction [, label] [, width])a progress bar, fraction in [0, 1]; fraction < 0: indeterminate (Progress bars)

Lists and regions ​

ProcedurePurpose
ig_splitter(id, sizes [, vertical] [, min_size] [, stat]) → logicala bar between two panes the user drags: their sizes [pixels] change (Splitters)
ig_selectable(label, selected [, index] [, stat]) → logicala line of a list, highlighted when selected; .true. when clicked; index: an item of a multi-selection (Lists and regions)
ig_begin_child(id [, width] [, height] [, border]) → logical, ig_end_child()a region that scrolls on its own; always paired (Lists and regions)
list_clipper_object: clip%begin(count [, item_height] [, keep]), clip%step() → logical, clip%first, clip%last, clip%item_heighta long list: only the rows in view are drawn; item_height the distance between rows [pixels]; keep a row drawn wherever it is (a multi-selection's range source) (Lists and regions)

Scrolling and focus ​

ProcedurePurpose
ig_scroll_here([ratio] [, axis] [, stat])after an item: scroll its line to ratio of the visible height (0 top, 0.5 centre, 1 bottom), on the next frame (Scrolling and focus)
ig_scroll_to_pos(pos [, ratio] [, axis] [, stat])scroll the point pos [pixels] of the content to ratio of the visible height: a row a clipper does not draw (Scrolling and focus)
ig_get_scroll(y, ymax [, x] [, xmax])the scroll of the current window or region and its largest value [pixels] (Scrolling and focus)
ig_set_scroll([y] [, x])scroll the current window or region to y, x [pixels] (Scrolling and focus)
ig_focus_here([offset] [, stat])the next item takes the keyboard focus (a field is edited, as if clicked) (Scrolling and focus)
ig_default_focus()the item drawn last has the focus when its window (a modal, a popup) appears (Scrolling and focus)

Groups: headers, tabs, tables ​

ProcedurePurpose
ig_collapsing_header(label [, default_open]) → logicala header that shows or hides what follows; .true. while open (no end call) (Groups)
ig_begin_tab_bar(id) → logical, ig_end_tab_bar()a bar of tabs; end it only when the begin returned .true. (Groups)
ig_begin_tab(label [, open]) → logical, ig_end_tab()a tab; .true. when selected: draw its content, then end it (only then) (Groups)
ig_push_id(id), ig_pop_id()an id scope (character or int32): the same label in two scopes is two widgets (rows, loops) (Groups)
ig_begin_disabled([disabled]), ig_end_disabled()the widgets in between are greyed out and ignore input (Groups)

Tables ​

ProcedurePurpose
ig_begin_table(id, columns [, flags] [, height] [, freeze_rows] [, freeze_cols] [, sortable] [, hideable] [, reorderable] [, scroll_x] [, stat]) → logical, ig_end_table()a table (every ImGuiTableFlags_* exported); rows or columns frozen in view while the rest scrolls; end it only when the begin returned .true. (Tables)
ig_table_setup_column(label [, width] [, stretch] [, sort] [, default_sort] [, descending] [, hidden] [, no_hide] [, stat]), ig_table_headers_row()declare a column (fixed width, or a stretch weight of the rest; how it sorts and hides); a row of their labels (Tables)
ig_table_sort(column, descending [, stat]) → logical.true. on the frame the user asks a new order of a sortable table: its key column and direction; the program sorts (Tables)
ig_table_row_color(rgba [, cell] [, stat])a colour behind the current row, or one of its cells (Tables)
ig_table_hovered_column([stat]) → integer(int32)the column under the pointer, 0 when none (Tables)
ig_table_column_enabled(column, enabled [, stat])show or hide a column of a hideable table from the program (Tables)
ig_table_next_row(), ig_table_next_column(), ig_table_set_column(column)start a row; move to the next cell, or to cell column (1-based) (Tables)

Trees ​

ProcedurePurpose
ig_tree_node(label [, default_open] [, selected] [, leaf] [, span_full_width] [, clicked] [, span_all_columns] [, index] [, stat]) → logical, ig_tree_pop()a tree node; .true. while open: draw its children, then pop (only then); clicked: the label, not the arrow; in a table, span_all_columns: its whole row (Trees)
ig_set_next_item_open(open [, always])open or close the next tree node or header from the program: first time only, or with always now (Trees)

Numbers ​

ProcedurePurpose
ig_input(label, value [, step] [, format] [, enter_returns] [, read_only] [, stat]) → logicala field for an int32, int64, real32 or real64, scalar or vector, typed; -/+ buttons with step; .true. when changed (Numbers)
ig_drag(label, value [, speed] [, vmin] [, vmax] [, format] [, scale] [, clamp] [, stat]) → logicala drag box for a number or a vector of any of the four kinds: speed per pixel, bounds, 'log' scale (Numbers)
ig_slider(label, value, vmin, vmax [, format] [, scale] [, clamp] [, stat]) → logicala slider for a number or a vector of any of the four kinds; 'log' scale, typed values clamped with clamp (Numbers)
ig_slider_angle(label, radians [, deg_min] [, deg_max] [, format] [, stat]) → logicalan angle kept in radians, shown and set in degrees (Numbers)
ig_drag_range(label, lo, hi [, speed] [, vmin] [, vmax] [, format] [, stat]) → logicaltwo drag boxes for the ends of a range, lo <= hi kept (Numbers)

Choices ​

ProcedurePurpose
ig_radio(label, current, value [, stat]) → logicala radio button of a group sharing current; a click sets current = value (Choices)
ig_list_box(label, current, items [, height] [, stat]) → logicala list of the character array items that stays open and scrolls; current the index chosen (Choices)
ig_combo(label, current, items) → logicala drop-down list of the character array items; current is the index chosen; .true. when the user picks one (Choices)

Multi-line text ​

ProcedurePurpose
ig_input_text_multiline(label, buffer [, width] [, height] [, read_only] [, tab_input] [, flags]) → logicala field of several lines over a text_buffer_object, of any length; Enter a newline, undo and redo; .true. when edited (Multi-line text)
text_buffer_object: buf%set(text [, stat]), buf%text() → character, buf%length() → int64the text of a multi-line field, kept by the native layer and grown as needed: replace it (CRLF becomes LF), copy it out, its length in bytes (Multi-line text)

Clipboard ​

ProcedurePurpose
ig_set_clipboard(text [, stat]), ig_get_clipboard() → characterput a text on the clipboard; read it (window: the system's; headless: the program's own; remote: the program's, joined to the browser's where it allows it) (Clipboard)

What happened to an item ​

ProcedurePurpose
ig_item_rect(xmin, ymin, xmax, ymax)screen rectangle of the last item (What happened to an item)
ig_last_item() → item_status_objectwhat happened to the item drawn last, in one snapshot: hovered, active, focused, visible, activated, edited, deactivated, deactivated_after_edit, toggled_open, clicked(3), double_clicked(3), rect(4) (What happened to an item)
ig_item_hovered([delay] [, stat]) → logicalthe pointer is over the item drawn last; delay 'none', 'short' (0.15 s) or 'normal' (0.40 s) (What happened to an item)
ig_any_item_hovered() → logical, ig_any_item_active() → logicalthe pointer is over some item; some item is held or edited (What happened to an item)

Tooltips ​

ProcedurePurpose
ig_tooltip(text)a tooltip on the previous widget, shown while the pointer rests on it (Tooltips)
ig_begin_item_tooltip() → logical, ig_begin_tooltip() → logical, ig_end_tooltip()a tooltip with any content (a table, a plot): on the item just drawn after the hover delay, or now wherever the pointer is; end only after a true begin (Tooltips)
ProcedurePurpose
ig_text_link(label) → logical, ig_text_link_url(label, url)text drawn as a link, .true. when clicked; a link that opens url in the browser (remote mode: the page opens it) (Links)

Players ​

ProcedurePurpose
ig_player(id, player [, labels] [, stat]) → logicala player for snapshots: previous, play/pause, next, a slider (showing labels(index)), a right-click menu for the speed and the mode; plays on the frame clock and asks for frames while playing; .true. when player%index changed (Players)
player_object: %index, %count, %playing, %speed, %modethe state of a player: the snapshot shown (1 to count), playing or not, snapshots per second, 'once', 'loop' or 'bounce' (Players)

Colour editing ​

ProcedurePurpose
ig_color_edit(label, rgba [, alpha] [, stat]) → logicala colour editor with a picker, bound to real(real64) RGB or RGBA (Colour editing)
ig_color_picker(label, rgba [, alpha] [, wheel] [, inputs] [, stat]) → logicala colour picker drawn in place, a hue bar or a hue wheel (Colour editing)

Drag and drop ​

ProcedurePurpose
ig_drag_source(type, payload [, preview] [, stat]) → logical, ig_drop_target(type, payload [, stat]) → logical, ig_dragging(type) → logicaldrag and drop of a text payload between items, matched by type (Drag and drop)

Selecting many items ​

ProcedurePurpose
selection_object, sel%resize(n), sel%is_selected(i) → logical, sel%set(i, on), sel%clear(), sel%selected_count() → integer, sel%indices() → integer(:), sel%flags() → logical(:)what is selected among n items, read and set by the program (Selecting many items)
ig_begin_multi_select(sel [, single] [, box_select] [, clear_on_escape] [, no_select_all] [, stat]), ig_end_multi_select(sel [, stat])a multi-selection over the lines and nodes drawn with index=: clicks, shift, ctrl, ctrl+a, box (Selecting many items)
ProcedurePurpose
ig_begin_main_menu_bar() → logical, ig_end_main_menu_bar()the menu bar along the top of the display; end only after a true begin (Menus)
ig_begin_menu_bar() → logical, ig_end_menu_bar()a window's own menu bar (ImGuiWindowFlags_MenuBar) (Menus)
ig_begin_menu(label [, enabled]) → logical, ig_end_menu()a menu or submenu; .true. while open (Menus)
ig_menu_item(label [, shortcut] [, selected] [, enabled]) → logicala menu item; .true. when picked; a check mark with selected (Menus)
ig_open_popup(id), ig_close_current_popup()open a popup (once, on an event); close the one being declared (Popups)
ig_begin_popup(id) → logical, ig_begin_popup_modal(title [, open]) → logical, ig_end_popup()a popup, a modal dialog; end only after a true begin (Popups)
ig_begin_popup_context(id [, on] [, button] [, stat]) → logicala context menu, opened by a right click on the item just drawn (on='item'), a window's empty space ('window') or the background ('void'); closed with ig_end_popup after a true begin (Context menus)
ig_shortcut(keys [, scope] [, repeat] [, stat]) → logicala key chord such as 'ctrl+s' pressed this frame (cmd on macOS), routed: 'focused' (default) only in the focused window, 'global', 'item'; or 'always', not routed: every call fires (Shortcuts)
ig_set_next_item_shortcut(keys [, scope] [, stat])the next item owns a chord: the chord presses it, its tooltip shows it (Shortcuts)

Docking: ig_dock_* ​

ProcedurePurpose
ig_dock_id(name) → integer(int32)the dock id of a name (Docking)
ig_dock_space(id [, flags] [, stat])a dock space over the display, every frame, before its windows (Docking)
ig_dock_layout_begin(id [, stat]) → logical.true. when the dock space needs its layout (first time) (Docking)
ig_dock_split(id, direction, fraction, id_at_dir, id_other [, stat])split a dock node in two (Docking)
ig_dock_window(name, id [, stat])put a window into a dock node of the layout (Docking)
ig_dock_layout_end(id [, stat])finish the layout (Docking)
ig_window_dock(id, docked)inside a window: its dock node and whether it is docked (Docking)
ig_set_next_window_dock(id [, always])dock the next window into a node the first time it appears (a window created after the layout) (Docking)

Details: Docking.

Styles: ig_/ip_ set_/get_ style_color, style_var ​

ProcedurePurpose
ig_set_style_color(name, color [, stat]), ip_set_style_color(...)a colour by name ('#rrggbb[aa]' or components) (Styles)
ig_get_style_color(name, rgba [, stat]), ip_get_style_color(...)a colour by name (Styles)
ig_set_style_var(name, value [, stat]), ip_set_style_var(...)a style variable by name (number, pair, logical, integer) (Styles)
ig_get_style_var(name, values, n [, stat]), ip_get_style_var(...)a style variable by name (Styles)
ig_show_style_editor([open] [, stat])Dear ImGui's and ImPlot's style editors, in a window (Styles)
ig_push_font(font [, size] [, stat]), ig_pop_font([stat])another font ('plex-mono' for columns that line up) or size for a block of widgets (Fonts)
ig_push_style_color(name, color [, stat]), ig_pop_style_color([n] [, stat])a colour for a block of widgets (Styles)
ip_push_style_color(name, color [, stat]), ip_pop_style_color([n] [, stat])a colour for a block of plots (Styles)
ip3_push_style_color(name, color [, stat]), ip3_pop_style_color([n] [, stat])an ImPlot3D colour for a block of 3-D plots (3-D plots)
ip3_push_style_var(name, value [, stat]), ip3_pop_style_var([n] [, stat])an ImPlot3D style variable for a block of 3-D plots (3-D plots)
ig_push_style_var(name, value [, stat]), ig_pop_style_var([n] [, stat])a style variable for a block of widgets (Styles)
ip_push_style_var(name, value [, stat]), ip_pop_style_var([n] [, stat])a style variable for a block of plots (Styles)
ICON_* (ICON_PLAY, ICON_FILE_PEN, ... 2171 Lucide icons)an icon as a UTF-8 string, for any label: ICON_PLAY//' Run' (Icons)

Details: Styles, Icons.

Plots: ip_* ​

ProcedurePurpose
ip_begin_plot(title [, width] [, height] [, equal]) → logicalbegin a plot; .true. when visible (plots)
ip_setup_axes(xlabel, ylabel [, auto_fit] [, xlog] [, ylog] [, xformat] [, yformat] [, xscale] [, yscale] [, stat])labels of X1 and Y1; the axes fit the data on first use, every frame with auto_fit=.true.; xscale/yscale: 'linear', 'log', 'symlog', 'time' (xlog/ylog: deprecated 'log'); xformat/yformat: tick label formats (checked)
ip_begin_subplots(title, rows, cols [, width] [, height] [, link_x] [, link_y]) → logical, ip_end_subplots()a grid of plots, optionally sharing the x or y range (plots)
ip_link_axis(axis, group [, stat])an axis linked to a named group: one range for every plot of the group (plots)
ip_begin_aligned(group [, horizontal] [, stat]) → logical, ip_end_aligned([stat])plots whose plot areas start and end at the same pixels (plots)
ip_legend_hovered(label [, stat]) → logical, ip_begin_legend_popup(label [, button] [, stat]) → logical, ip_end_legend_popup([stat])the pointer on an item's legend entry; a popup opened from it (plots)
ip_hide_next_item([hidden] [, always] [, stat])the next item hidden or shown, once or every frame (plots)
ip_setup_axes_limits(xmin, xmax, ymin, ymax [, always] [, stat])initial ranges of X1 and Y1 (plots)
ip_setup_axis(axis [, label] [, scale] [, auto_fit] [, format] [, opposite] [, invert] [, lock] [, no_grid] [, stat])set up one of the six axes 'x1'..'x3', 'y1'..'y3': label, scale ('linear', 'log', 'symlog', 'time'), format, side, direction, lock, grid (plots)
ip_set_axes(x, y [, stat])the axes the next items use ('x1'..'x3', 'y1'..'y3') (plots)
ip_setup_axis_limits(axis, vmin, vmax [, always] [, stat])initial range of one axis (plots)
ip_setup_axis_ticks(axis, values [, labels] [, stat])ticks at given values, with given labels or the axis's format (plots)
ip_setup_axis_constraints(axis [, vmin] [, vmax] [, zoom_min] [, zoom_max] [, stat])bounds the user cannot pan or zoom one axis past (plots)
ip_setup_legend([location] [, outside] [, horizontal] [, stat])the legend at a compass point, inside or outside the plot area, in a column or a row (plots)
ip_plot_limits(xmin, xmax, ymin, ymax [, xaxis] [, yaxis] [, stat]), ip_plot_size(...)the ranges the user panned and zoomed to, of the current axes or the named ones; the plot's size in pixels (plots)
ip_line(label, x, y [, spec] [, stat])a line through (x(i), y(i)); arrays of any stride read in place, x may be int32/int64 (plots)
ip_line(label, y [, xscale, xstart] ...), ip_line(label, y, row ...)uniform x; a matrix row read in place (plots)
ip_scatter(label, x, y [, spec] [, stat])markers at (x(i), y(i)) (plots)
ip_bars(label, x, y, bar_size [, spec] [, stat])bars of height y(i) at x(i) (plots)
ip_shaded(label, x, y1, y2 [, spec] [, stat]), ip_shaded(label, x, y, yref ...)area between two curves, or a curve and y = yref (plots)
ip_spec(...) → plot_spec_objectitem style: colours, line weight, markers, flags (ImPlotMarker_*, ImPlot*Flags_*) (plots)
ip_heatmap(label, f, xmin, xmax, ymin, ymax ...)a field f(i, j) as coloured cells, read in place, j = 1 at the bottom (heatmaps)
ip_colormap_scale(label, scale_min, scale_max ... [, colormap] [, stat])the colour bar of a heatmap (default colormap: Viridis) (heatmaps)
ip_colormap_legend(id, colormap, vmin, vmax [, levels] [, horizontal] [, width] [, height] [, label_format] [, scale] [, stat])a colour-scale legend, vertical or horizontal, continuous or in bands, ticks on a linear, log or symlog scale (legend)
ip_colormap_legend_edit(id, colormap, vmin, vmax [, levels] [, horizontal] [, width] [, height] [, label_format] [, scale] [, stat]) → logicalthe same legend whose range the user drags and zooms with the wheel; vmin, vmax updated in place (fields)
ip_field_image(label, f, x0, x1, y0, y1 [, colormap] [, vmin] [, vmax] [, scale] [, nan_color] [, changed] [, range] [, stat])a field through a colormap in one call: a texture coloured when it changes, linear, log or symlog, NaN colour (fields)
ip_colormap(name [, levels] [, stat]) → integer(int32)a colormap's id by name: bundled ('cividis', 'batlow', 'cool-warm', ...), ImPlot's own or loaded; <name>_r reversed, levels discrete bands (colormaps)
ip_load_colormap(name, file [, stat])a user colormap from a CSV table of RGB rows or a ParaView JSON preset (user maps)
ip_colormap_names(names)the names ip_colormap knows (colormaps)
ig_gradient_edit(id, colormap [, width] [, height] [, stat]) → logicala gradient editor of a colormap (ImGuizmo's ImGradient): stops dragged, added, recoloured, removed; the map, its variants and what is drawn with it follow (editing a colormap)
ip_colormap_stops(name, positions, colours [, stat])a colormap's stops, as the editor shows them; saved as a CSV, read back by ip_load_colormap (editing a colormap)
ip_image(label, tex, xmin, xmax, ymin, ymax ...)a texture in a plot, pixel row 1 at the bottom (textures)
ip_error_bars(label, x, y, err [, err_high] [, spec] [, horizontal] [, stat])error bars, symmetric or not, vertical or along x (plots)
ip_bubbles(label, x, y, radii [, spec] [, stat])circles of given radii in plot units (plots)
ip_pie_chart(labels, values, x, y, radius [, label_format] [, angle0] [, normalize] [, colormap] [, spec] [, stat])a pie chart, one slice per value (plots)
ip_annotation(x, y, text [, color] [, offset] [, stat])a text at a plot point, in a box of a colour or alone (plots)
ip_drag_line_x(id, x [, color] [, thickness] [, stat]) → logical, ip_drag_line_y(...)a vertical (horizontal) line the user drags; the value updated in place (plots)
ip_drag_point(id, x, y [, color] [, radius] [, stat]) → logicala point the user drags (plots)
ip_contour(label, f, x0, x1, y0, y1 [, levels] [, nlevels] [, colormap] [, color] [, labels] [, line_weight] [, stat])contour lines of a field, read in place; NaNs leave holes (plots)
ip_contour_lines(f, x0, x1, y0, y1, levels, x, y, first)the contour segments without drawing them (marching squares, pure) (plots)
ip_contour_levels(f [, count]) → real(real64) arraylevels at round numbers inside a field's finite range (plots)
ip_stairs(label, x, y [, spec] [, stat])a staircase through the points; pre-step or shaded by flags (plots)
ip_digital(label, x, y [, spec] [, stat])a digital signal in a band at the bottom of the plot (plots)
ip_bar_groups(labels, values [, group_size] [, shift] [, horizontal] [, stacked] [, colormap] [, spec] [, stat])items in groups of bars, side by side or stacked (plots)
ip_stems(label, x, y [, ref] [, spec] [, stat])stems from y = ref to the points, with markers (plots)
ip_inf_lines(label, values [, horizontal] [, spec] [, stat])lines across the whole plot at x (or y) values, real or integer (plots)
ip_histogram(label, values [, bins] [, vmin] [, vmax] [, bar_scale] [, max_count] [, spec] [, stat])a histogram: a bin count or a rule (ImPlotBin_*), NaNs left out (plots)
ip_histogram2d(label, x, y [, xbins] [, ybins] [, xmin] [, xmax] [, ymin] [, ymax] [, colormap] [, max_count] [, spec] [, stat])a 2-D histogram, cells coloured by count (plots)
ip_plot_hovered([stat]) → logicalthe pointer is over the plot area (plots)
ip_plot_mouse(x, y [, xaxis] [, yaxis] [, stat])the pointer in plot units (plots)
ip_plot_to_pixels(x, y, px, py [, xaxis] [, yaxis] [, stat]), ip_pixels_to_plot(px, py, x, y ...)plot units to display pixels and back (plots)
ip_plot_selection(xmin, xmax, ymin, ymax [, xaxis] [, yaxis] [, stat]) → logical, ip_cancel_selection([stat])the box the user drags with the right button; ended without the zoom (plots)
ip_drag_rect(id, xmin, xmax, ymin, ymax [, color] [, stat]) → logicala rectangle the user moves and resizes; the values updated in place (plots)
ip_drop_target(type, payload [, axis] [, legend] [, x] [, y] [, stat]) → logicala plot, one of its axes or its legend as a drop target; where the payload landed (plots)
ip_tag(axis, value [, color] [, text] [, stat])a box on an axis at a value, with a text or the axis's label (plots)
ip_text(text, x, y [, offset] [, vertical] [, stat])a text at a plot point (plots)
ip_end_plot()end the plot (only if ip_begin_plot returned .true.) (plots)

Items take real(real32) or real(real64) arrays. Details: Plots, Colormaps.

3-D plots: ip3_* ​

ProcedurePurpose
ip3_begin_plot(title [, width] [, height] [, equal]) → logicalbegin a 3-D plot (ImPlot3D): a box the user turns (right drag), pans and zooms; .true. when visible (3-D plots)
ip3_setup_axes(xlabel, ylabel, zlabel [, auto_fit] [, limits] [, elevation] [, azimuth] [, stat])labels of the three axes, their initial ranges, the box's initial rotation; fit every frame with auto_fit=.true. (3-D plots)
ip3_line(label, x, y, z [, spec] [, colors] [, stat])a line through (x(i), y(i), z(i)), a colour per segment; arrays of any stride read in place (3-D plots)
ip3_scatter(label, x, y, z [, spec] [, colors] [, sizes] [, stat])markers at (x(i), y(i), z(i)), a colour and a radius per point (3-D plots)
ip3_surface(label, x, y, z [, colormap] [, scale_min] [, scale_max] [, spec] [, stat])a field z(i, j) as a height surface over x(i), y(j) or a grid x(i, j), y(i, j), coloured by a FIGURE colormap (3-D plots)
ip3_mesh(label, x, y, z, triangles [, spec] [, stat])triangles over vertices, triangles(1:3, k) from 1 (3-D plots)
ip3_text(text, x, y, z [, angle] [, offset] [, stat])a text at a point of the box (3-D plots)
ip3_triangles(label, x, y, z [, spec] [, stat]), ip3_quads(label, x, y, z [, spec] [, stat])triangles (each 3 points in a row) and quadrilaterals (each 4) as items of their own (3-D plots)
ip3_image(label, texture, corners [, tint] [, stat])an image on a quadrilateral of the box: a field on a plane (3-D plots)
ip3_setup_axis(axis [, label] [, scale] [, auto_fit] [, invert] [, lock] [, no_grid] [, format] [, stat])one axis: its scale ('log', 'symlog'), fit, direction, lock, grid, tick format (3-D plots)
ip3_setup_axis_ticks(axis, values [, labels] [, stat])the ticks of one axis at given values, with labels (3-D plots)
ip3_setup_box([scale] [, elevation] [, azimuth] [, animate] [, stat])the box's proportions; turned to a view by the program (3-D plots)
ip3_setup_legend([location] [, horizontal] [, no_buttons] [, stat])where the legend goes (3-D plots)
ip3_mouse_ray(origin, direction [, stat]) → logical, ip3_plot_to_pixels(x, y, z, px, py [, stat])the ray under the pointer, for picking; the pixel of a point (3-D plots)
ip3_spec(...) → plot3d_spec_objecta 3-D item's style: colours, line weight, markers, flags (ImPlot3DMarker_*, ImPlot3D*Flags_*) (3-D plots)
ip3_end_plot()end the 3-D plot (only if ip3_begin_plot returned .true.) (3-D plots)

ImPlot3D is for plots of up to about 10⁴ primitives; meshes of millions of faces belong to view3d_object (which one).

Images: texture_object, ig_image ​

ProcedurePurpose
tex%init(width, height [, smooth] [, stat]), tex%update(rgba [, stat]), tex%destroy()an RGBA texture on the GPU, integer(int8) :: rgba(4, width, height) uploaded in place (textures)
tex%width(), tex%height() → integer(int32), tex%is_initialized() → logicalits size (0 before init); whether it exists (textures)
ig_image(tex [, width, height])the texture in a window, pixel row 1 at the top (textures)
tex%load(path [, smooth] [, stat])a texture from a PNG or JPEG file, its size the image's (main thread) (reading images)
fig_read_image(path, rgba [, stat])a PNG or JPEG file decoded into integer(int8), allocatable :: rgba(:,:,:), rgba(4, width, height), row 1 at the top; draws nothing: a task may call it (reading images)

Details: Heatmaps and images.

Canvas: ig_canvas, ig_draw_* ​

ProcedurePurpose
ig_canvas(id, width, height, ev [, texture] [, stat])an area taking the mouse; ev a canvas_event_object: hovered, active, clicked, double-clicked, down and released per button, the pointer in canvas pixels, the drag, the wheel (owned while hovered), the modifiers, the canvas's origin and size (Canvas)
canvas_event_object: %hovered, %active, %clicked(3), %double_clicked(3), %down(3), %released(3), %mouse(2), %drag(2), %delta(2), %wheel, %wheel_h, %ctrl, %shift, %alt, %super, %origin(2), %size(2)what happened over a canvas on a frame, a plain value; per button (left, right, middle) (The canvas)
ig_draw_line(x1, y1, x2, y2, color [, thickness] [, layer] [, stat])a segment (Primitives)
ig_draw_rect(x1, y1, x2, y2, color [, thickness] [, filled] [, layer] [, stat])a rectangle, outline or filled (Primitives)
ig_draw_circle(x, y, radius, color [, thickness] [, filled] [, layer] [, stat])a circle, its radius in pixels (Primitives)
ig_draw_polyline(x, y, color [, thickness] [, closed] [, layer] [, stat])a polyline through the arrays x(:), y(:) (Primitives)
ig_draw_polygon(x, y, color [, thickness] [, filled] [, layer] [, stat])a polygon, outline or filled, convex or not (Primitives)
ig_draw_text(x, y, text, color [, layer] [, stat])text, its top-left at the point (Primitives)
ig_draw_image(texture, x1, y1, x2, y2 [, color] [, layer] [, stat])a texture stretched over a rectangle, tinted by color (Primitives)
ig_cursor_screen_pos(x, y)where the next item goes, in screen pixels (Coordinates)
ig_invisible_button(id, width, height [, stat]) → logicala button that draws nothing: a hot zone over a drawing (The canvas)

layer is 'window' (default), 'foreground', 'background' or 'plot' (plot units, inside a plot). Details: Canvas.

Processes: process_object, log_view_object ​

ProcedurePurpose
p%start(args [, cwd] [, env] [, merge_stderr] [, detached] [, log_file] [, stat])start a program, the arguments as an array (no shell): captured (output piped) or detached (output to log_file, it outlives the program) (processes)
p%poll(lines [, stat])the complete lines printed since the last poll (character(len=:), allocatable :: lines(:)) (processes)
p%running() → logical, p%exit_code([stat]) → int32, p%killed() → logical, p%pid() → int64its state: running, its exit code (captured, ended), ended by kill, its process id (processes)
p%kill([force] [, stat])ask it to end (force: at once) (processes)
log%add(line | lines), log%clear(), log%set_cap(cap [, stat])the lines of a log view, a ring buffer of cap lines (default 10000) (log view)
log%draw(id [, height])the lines in a region of their own, only those in view; follows the end while at the bottom; click, shift+click, ctrl+c to copy (log view)
log%count() → int32, log%line(i) → character, log%following() → logical, log%in_view(first, last), log%copy([all]) → characterthe lines kept, one line, whether the view follows the end, the lines in view, the chosen lines (log view)

Details: Processes and tasks.

Tasks: task_object, task_handle_object ​

ProcedurePurpose
t%start(work, data [, stat])run work(h, data) (a task_work module procedure) on a worker thread, on a copy of data (class(*)) (tasks)
task_work(h, data)the abstract interface of a task's procedure: type(task_handle_object), intent(inout) :: h, class(*), intent(inout) :: data (its own copy) (tasks)
t%running() → logical, t%done() → logical, t%progress(fraction [, message])it runs; it has ended (its result waits); its last progress in [0, 1] and message (tasks)
t%cancel([stat]), t%result(data [, stat])ask it to stop at its next safe point; once done, its data moved out (class(*), allocatable) (tasks)
h%report(fraction [, message]), h%cancelled() → logical, h%fail(message)in the task: post progress (wakes the frame loop), the program asked it to stop, report a failure (tasks)

A task never draws: FIGURE's drawing entry points refuse a call from a worker with FIG_ERR_STATE. Details: Processes and tasks.

3-D views: view3d_object ​

ProcedurePurpose
v%init([threads] [, fast_moves] [, lighting] [, background] [, stat]), v%destroy(), v%is_initialized() → logicalcreate a 3-D view drawn by FIGURE's software rasterizer (the same pixels in every mode); release it; whether it exists (meshes)
v%triangles(xyz, tri [, scalar] [, cell_scalar] [, colormap] [, color] [, edges] [, flat] [, stat]) → int32, v%quads(xyz, quad [, ...]) → int32, v%surface(xyz [, ...]) → int32, v%lines(xyz [, seg] [, ...]) → int32add a mesh, read in place from the program's target arrays: triangles, quads, a structured surface xyz(3, ni, nj), lines; coloured by a scalar per vertex or per cell through a colormap, or in one colour (meshes)
v%set_mesh(mesh [, scalar] [, cell_scalar] [, no_scalar] [, colormap] [, vmin, vmax] [, auto_range] [, color] [, edges] [, edge_color] [, flat] [, visible] [, stat]), v%changed([mesh] [, stat]), v%remove(mesh [, stat]), v%clear([stat])change a mesh's field or style; its arrays changed in place; remove one, all (fields and colours)
v%set_camera([target] [, distance] [, azimuth] [, elevation] [, fov] [, stat]), v%get_camera(...), v%fit([stat]), v%view(name [, stat]), v%orbit(azimuth [, elevation] [, stat]), v%pan(right, up [, stat]), v%zoom(factor [, stat])the camera: set, read, fit, the six standard views ('+x' ... '-z'), turn, move, zoom (the camera)
v%clip(normal, point [, stat]), v%unclip([stat])clipping planes (up to 6) (clipping planes)
v%draw(id [, width] [, height] [, stat])the view as a widget; the mouse orbits, pans, zooms, fits; rendered only when something changed, at half resolution while moving (meshes)
v%pick(x, y, mesh, element [, point] [, stat]) → logical, v%hovered(mesh, element [, point] [, stat]) → logical, v%clicked(...) → logicalthe element under a pixel, under the mouse, clicked (picking)
v%image(rgba [, stat]), v%render_info([count] [, milliseconds] [, width] [, height] [, half] [, stat])the pixels of the last render; renders so far, the last one's time and size (rendering)
v%view_cube([size] [, corner] [, stat])a view cube over the view (ImGuizmo's ViewManipulate): a click on a face, an edge or a corner turns the camera to it, a drag orbits (gizmos)
v%gizmo(id, matrix [, mode] [, space] [, snap] [, stat]) → logicalhandles over the view moving a 4x4 placement (ImGuizmo's Manipulate): translate, rotate, scale, in world or local axes, snapped; a clipping plane, a box, a probe placed by hand (gizmos)
v%view_matrix(m [, stat]), v%projection_matrix(m [, stat])the camera's view and projection matrices, column-major 4x4 real(real64) (OpenGL's conventions) (matrices)

Details: 3-D views.

Code editor: code_editor_object, code_diff ​

ProcedurePurpose
ed%init([language] [, stat]), ed%destroy(), ed%is_initialized() → logical, ed%set_language(language [, stat])create a code editor (ImGuiColorTextEdit, drawn through Dear ImGui: the same in every mode), highlighting a language; release it; whether it exists; another language (code editor)
ed%set_text(text [, stat]), ed%text() → character, ed%line_count() → int32replace the text (marks and undo history go); the text, every line ended by LF; its lines (code editor)
ed%draw(id [, width] [, height] [, stat]) → logicalthe editor as a widget, in IBM Plex Mono with the fallback symbols; .true. on the frame the user changed the text (code editor)
ed%mark(line, severity, message [, stat]), ed%clear_marks([stat]), ed%mark_of(line [, message]) → charactera finding on its line: 'error', 'warning', 'info', a tint, an icon and a tooltip; remove them; read one back (marks)
ed%goto(line [, column] [, focus] [, stat]), ed%focus([stat]), ed%cursor(line, column), ed%selection(first_line, first_column, last_line, last_column [, text]) → logical, ed%select(first_line, first_column, last_line, last_column [, stat])move the cursor, give the editor the keyboard; where the cursor is; the selection; select a range (code editor)
ed%insert(text [, stat]), ed%word_at_cursor() → character, ed%undo([stat]) → logical, ed%redo([stat]) → logicalinsert at the cursor; the word the cursor is in; undo, redo a change (code editor)
ed%find(text [, case_sensitive] [, whole_word] [, stat]) → logical, ed%replace(text, by [, case_sensitive] [, whole_word] [, stat]) → int32select the next occurrence; replace every one, in one undo (find and replace)
ed%set_completions(words [, stat]), ed%completing([words]) → logicalthe words completion offers (keys of several words in a key = value language); whether the popup is open, with what it offers (completion)
ed%read_only(on [, stat]), ed%is_read_only() → logical, ed%set_options([line_numbers] [, tab_size] [, whitespace] [, line_highlight] [, stat]), ed%line_rect(line, x0, y0, x1, y1) → logicalread-only or editable; the editor's options; a line's rectangle on the last draw (code editor)
code_language(name [, stat]) → language_object, lang%init(name [, keywords] [, types] [, comment] [, comment_alt] [, block_comment] [, preprocessor] [, single_quotes] [, double_quotes] [, numbers] [, case_sensitive] [, key_value] [, stat]), lang%name() → characterthe shipped languages ('fortran', 'input', 'text', the fork's thirteen); a language of the program's own (languages)
code_diff(id, left, right [, side_by_side] [, language] [, width] [, height] [, stat])the difference of two texts as a widget, one column or side by side (the diff)
code_diff_lines(left, right, added, removed [, stat])the lines added and removed, without drawing; a task may call it (the diff)

Markdown: ig_markdown, markdown_view_object ​

ProcedurePurpose
ig_markdown(text [, link] [, stat]) → logicala Markdown text at the cursor (imgui_rich_md, drawn through Dear ImGui: the same in every mode): headings, emphasis, lists, tables, code in IBM Plex Mono, quotes, images from files; .true. on the frame a link is clicked, its URL in link, nothing opened (Markdown)
md%init([toc] [, search] [, stat]), md%destroy(), md%is_initialized() → logicalcreate a document (markdown_view_object) with a table of contents and a find bar; release it; whether it exists (Markdown)
md%set_text(text [, stat]), md%load(path [, stat]), md%text() → characterthe document's text, given or read from a file; a copy of it (Markdown)
md%draw(id [, link] [, width] [, height] [, stat]) → logicalthe document as a widget with its own scroll; .true. on the frame a link is clicked, its URL in link; a link to a heading scrolls there (Markdown)
md%find(text [, stat]), md%matches() → int32, md%current_match() → int32, md%scroll_to(heading [, stat])search as the find bar does, its matches and the current one; scroll to a heading by its text or anchor (Markdown)

Testing: figure_testing ​

ProcedurePurpose
test_click(x, y [, button]), test_drag(x0, y0, x1, y1)queue a click, a drag (synthetic input)
test_mouse_move, test_mouse_button, test_wheelqueue mouse input, one part at a time (synthetic input)
test_key(name [, down]), test_type(text)queue keys and typed text (synthetic input)
test_drop(paths, x, y [, stat])queue a drop of files or folders at (x, y), reported by app%dropped on the next frame (synthetic input)
test_next_frame()a frame boundary in the queued input (synthetic input)
test_item_center(x, y), test_window_rect(name, ...)where a widget or a window is (synthetic input)
test_popup_rect(xmin, ymin, xmax, ymax [, found] [, stat])where the open popup is (a menu, a context menu, a combo's list, a colour picker) (probes)
test_opened_url() → characterthe URL the last click on an ig_text_link_url asked to open (headless mode opens nothing) (Links)
test_quit()a quit request, as the window's close button makes it (synthetic input)
test_plot_tick(axis, index, label [, count] [, stat])a tick label of any of the six axes of the plot being declared ('x1'..'y3'; 'x', 'y') (plots)
test_plot_copies() → int64the arrays the plot items copied so far (a stride differing from the ordinates', integer abscissae) (plots)
test_plot_stride() → int64the byte stride the last plot item gave ImPlot (plots)
test_field_uploads() → int64the colourings ip_field_image uploaded so far (fields)
test_field_textures() → int32the field textures kept (fields)
test_field_time() → real64the last colouring's time [ms] (fields)
test_field_pixel(label, i, j, rgba [, stat])the colour a field's value got (fields)
test_frame_hit(x, y) → characterwhat the frame of decorations='figure' does at a point: 'client', 'drag', 'resize-top-left', ... (the window's frame)
test_frame_rect(part, x0, y0, x1, y1 [, found] [, stat])a part of its title bar in the last frame: 'bar', 'icon', 'menus', 'title', 'minimize', 'maximize', 'close' (probes)
test_frame_state(minimized, maximized [, stat])the window minimized, maximized (headless: as the bar's buttons recorded it) (probes)
test_system_theme(theme [, stat])the system's light or dark setting changes ('light', 'dark', 'system'), at the next frame: tests of palette='auto' (styles)
test_notification_rect(index, x0, y0, x1, y1 [, found] [, alpha])a notification shown in the last frame, 1 the newest, and the alpha it was drawn with (notifications)
test_capture(path [, stat])the whole frame as a PNG file, written when it is rendered: the CPU renderer's pixels headless (pictures as tests)
test_compare_image(path, golden [, threshold] [, max_failed] [, masks] [, failed] [, stat]) → logicala picture against a golden: per channel within threshold (2), at most max_failed (0) pixels more, masks left out; <stem>.new.png and <stem>.diff.png on a mismatch (pictures as tests)
test_glyph(text, font, source, pixels [, width] [, height] [, checksum] [, stat])the font of a text font's stack that draws a character, its bitmap's pixels, advance, height and checksum (Glyphs)
test_drawn_extent(color, x0, y0, x1, y1 [, found] [, stat] [, layer] [, vertices])the extent drawn so far in the current window in a style colour by name ('PlotHistogram': a progress bar's fill) or an RGBA colour (an item's ip_spec colour); with layer, the foreground or background layer; vertices, how many (Canvas)
test_file_browser(shown [, folder] [, entries] [, error] [, asking] [, path_field] [, name_field] [, recent])the file browser in front: its folder, the entries in the order shown, the error shown, the replace question, the fields, the recent folders (file browser)
test_file_browser_rect(part, x0, y0, x1, y1 [, found])a part of the file browser in the last frame ('entry:NAME', 'ok', 'cancel', 'path', ...), to click it (probes)
test_item_exists(path [, stat]) → logicalan item or a window of the last frame named by a path: Window/Label, //Window, ##id, *, $$n (finding items by path)
test_item_rect(path, x, y, w, h [, stat]) → logicalthe rectangle of the item a path names, in the last frame; false when there is none (finding items by path)
test_item_click(path [, button] [, stat])queue a click on the item a path names; a missing path names the nearest item (finding items by path)
test_item_type_text(path, text [, stat])queue typing into a field, a slider or a drag: a click with the shortcut key, select all, the text, Enter (finding items by path)
test_item_checked(path [, stat]) → logicala checkbox or a menu item checked in the last frame (finding items by path)
test_item_value(path, text [, shown] [, stat]) → logicalthe item showed text as its value (the text drawn in it, its label taken out) (finding items by path)
test_menu_click(path [, stat])queue a click through a menu path, each submenu clicked once it opens (finding items by path)
test_record_items(on [, stat])record the items of each frame, or stop (on from init_headless) (finding items by path)
test_run(max_frames [, stat]) → logicaltrue while input is queued or frames are asked for: the loop of a test, do while (test_run(60)) (running until idle)
test_id_conflicts([list]) → int32the ids two items shared in the last frame, found without the pointer over them, and their paths (checks)
test_unnamed_items([list]) → int32the items with no visible name and no tooltip (icon-only buttons, '##id' labels), and their paths (checks)
test_settings_file(path [, stat])the file keeping the browser's recent folders, instead of FIGURE's own ('': memory only) (probes)

Details: Headless testing.

Errors ​

EntityPurpose
FIG_OK, FIG_ERR_STATE, FIG_ERR_ARGUMENT, FIG_ERR_FAILED, FIG_ERR_EXCEPTIONstatus codes returned in stat (stat or error stop)
figure_last_error() → character(len=:), allocatablemessage of the last failure (figure_last_error)

Details: Error handling.

Environment variables ​

VariableEffect
FIGURE_DEBUG_REDRAWany value: once per second, redraw statistics on standard error (window mode) — see frame loop
FIGURE_DEBUG_WAKEany value: each wake-up sent and what ended each wait of the loop, on standard error (window and remote modes) — see frame loop
FIGURE_STYLEthe style at initialisation: a name of app%set_style, or a theme file — see styles
FIGURE_CAPTURE, FIGURE_CAPTURE_*record the frames of a window to image files, with scripted input — see screenshots and videos
FIGURE_RENDER_THREADSthe CPU renderer's threads, 1-64 (default: the hardware's, at most 8; headless and remote frames, pictures) — see screenshots and videos
GALLIUM_DRIVER=d3d12not read by FIGURE: on WSL2, makes Mesa render on the GPU — see installation
SDL_VIDEO_DRIVERread by SDL3: x11 or wayland to choose the video driver

Released under the MIT licence.