Skip to content

figure_base ​

figure_base, error handling and string conversion shared by the FIGURE modules.

Procedures that can fail take an optional stat: if present it receives FIG_OK or a FIG_ERR_* code and figure_last_error() gives the message; if absent, a failure prints the message and stops (error stop).

Usage checks: every drawing procedure asks figure_draw_refused first (a task, or no frame open), and every begin/end and push/pop pair registers in the scope record of the frame (figure_scope_open after the begin, figure_scope_refused before the end): see errors.md, "Pairing and frames".

Source: src/lib/figure_base.F90

Dependencies

Contents ​

Variables ​

NameTypeAttributesDescription
FORMAT_INTEGERinteger(kind=int32)parameterA printf format of an integer value: d, i, u.
FORMAT_REALinteger(kind=int32)parameterA printf format of a real value: f, F, e, E, g, G, a, A.
SCOPE_WINDOWinteger(kind=c_int)parameterig_begin, ig_begin_side_bar / ig_end (always paired).
SCOPE_CHILDinteger(kind=c_int)parameterig_begin_child / ig_end_child (always paired).
SCOPE_TAB_BARinteger(kind=c_int)parameterig_begin_tab_bar / ig_end_tab_bar (after true).
SCOPE_TABinteger(kind=c_int)parameterig_begin_tab / ig_end_tab (after true).
SCOPE_TABLEinteger(kind=c_int)parameterig_begin_table / ig_end_table (after true).
SCOPE_TREEinteger(kind=c_int)parameterig_tree_node / ig_tree_pop (after true).
SCOPE_MAIN_MENU_BARinteger(kind=c_int)parameterig_begin_main_menu_bar / ig_end_main_menu_bar (after true).
SCOPE_MENU_BARinteger(kind=c_int)parameterig_begin_menu_bar / ig_end_menu_bar (after true).
SCOPE_MENUinteger(kind=c_int)parameterig_begin_menu / ig_end_menu (after true).
SCOPE_POPUPinteger(kind=c_int)parameterig_begin_popup, ig_begin_popup_context, ig_begin_popup_modal / ig_end_popup (after true).
SCOPE_PLOTinteger(kind=c_int)parameterip_begin_plot / ip_end_plot (after true).
SCOPE_SUBPLOTSinteger(kind=c_int)parameterip_begin_subplots / ip_end_subplots (after true).
SCOPE_DOCK_LAYOUTinteger(kind=c_int)parameterig_dock_layout_begin / ig_dock_layout_end (after true).
SCOPE_IDinteger(kind=c_int)parameterig_push_id / ig_pop_id.
SCOPE_DISABLEDinteger(kind=c_int)parameterig_begin_disabled / ig_end_disabled.
SCOPE_FONTinteger(kind=c_int)parameterig_push_font / ig_pop_font.
SCOPE_STYLE_COLORinteger(kind=c_int)parameterig_/ip_push_style_color / ig_/ip_pop_style_color.
SCOPE_STYLE_VARinteger(kind=c_int)parameterig_/ip_push_style_var / ig_/ip_pop_style_var.
SCOPE_GROUPinteger(kind=c_int)parameterig_begin_group / ig_end_group (always paired).
SCOPE_ALIGNinteger(kind=c_int)parameterig_align_begin / ig_align_end (always paired).
SCOPE_ITEM_WIDTHinteger(kind=c_int)parameterig_push_item_width / ig_pop_item_width (always paired).
SCOPE_TOOLTIPinteger(kind=c_int)parameterig_begin_tooltip, ig_begin_item_tooltip / ig_end_tooltip (after true).
SCOPE_PLOT3Dinteger(kind=c_int)parameterip3_begin_plot / ip3_end_plot (after true).
SCOPE_ALIGNEDinteger(kind=c_int)parameterip_begin_aligned / ip_end_aligned (after true).
SCOPE_LEGEND_POPUPinteger(kind=c_int)parameterip_begin_legend_popup / ip_end_legend_popup (after true).
SCOPE_MULTI_SELECTinteger(kind=c_int)parameterig_begin_multi_select / ig_end_multi_select (always paired).

Subroutines ​

figure_check ​

Store status in stat if present, else stop on failure with the last error message.

Attributes: recursive

fortran
subroutine figure_check(status, stat)

Arguments

NameTypeIntentAttributesDescription
statusinteger(kind=c_int)inStatus from the native layer.
statinteger(kind=int32)outoptionalStatus for the caller.

Call graph

figure_fail ​

Report a failure detected on the Fortran side: set the last error message, then act as figure_check.

Attributes: recursive

fortran
subroutine figure_fail(status, message, stat)

Arguments

NameTypeIntentAttributesDescription
statusinteger(kind=c_int)inFailure status (a FIG_ERR_* code).
messagecharacter(len=*)inMessage for figure_last_error.
statinteger(kind=int32)outoptionalStatus for the caller.

Call graph

figure_usage_error ​

A usage error found by a wrapper (FIG_ERR_STATE: a call out of its place, as ig_table_sort outside a table): returned in stat when present; without it, mode 'abort' stops the program here and the other modes keep it for the next app%next_frame, as the errors of figure_draw_refused.

Attributes: recursive

fortran
subroutine figure_usage_error(message, stat)

Arguments

NameTypeIntentAttributesDescription
messagecharacter(len=*)inThe whole message (: ).
statinteger(kind=int32)outoptionalStatus: FIG_ERR_STATE.

Call graph

figure_scope_open ​

After a begin or a push: its scope in the record of the frame (a begin of the "end only after true" kind that returned false is remembered for the message of a wrong end, not opened).

Attributes: recursive

fortran
subroutine figure_scope_open(kind, who, label, returned, aux)

Arguments

NameTypeIntentAttributesDescription
kindinteger(kind=c_int)inSCOPE_*.
whocharacter(len=*)inThe procedure (ig_begin).
labelcharacter(len=*)inIts label or id ('' when none).
returnedlogicalinoptionalWhat the begin returned (default true).
auxinteger(kind=int32)inoptionalThe dock id of a dock layout.

Call graph

Functions ​

figure_time ​

Seconds since the first call of figure_time in the program, on a monotonic clock (clock_gettime of CLOCK_MONOTONIC on Linux, mach_absolute_time on macOS, QueryPerformanceCounter on Windows): never decreasing, not stepped when the system sets its time, as system_clock is under nvfortran. Resolution: the counter's tick, 1 ns on Linux, 1 ns or 42 ns on macOS (Intel, Apple silicon), usually 100 ns on Windows; the first call returns (about) 0. Callable at any time (before init*, after destroy) and from any thread, a task included; the same in every mode.

Attributes: recursive

Returns: real(kind=real64)

fortran
function figure_time() result(seconds)

Call graph

figure_last_error ​

Message of the last failed call.

Attributes: recursive

Returns: character(len=:)

fortran
function figure_last_error() result(msg)

Call graph

figure_refused ​

True when called from a task's worker thread: the drawing entry point name must return at once. The task's status becomes FIG_ERR_STATE with a message naming name (given by t%result), the task is asked to stop, and stat, if present, is FIG_ERR_STATE. False on the main thread (nothing changes).

Attributes: recursive

Returns: logical

fortran
function figure_refused(name, stat) result(refused)

Arguments

NameTypeIntentAttributesDescription
namecharacter(len=*)inThe entry point.
statinteger(kind=int32)outoptionalStatus, on a refusal.

Call graph

figure_draw_refused ​

True when the drawing entry point name must return at once: called from a task (as figure_refused), or with no frame open (a usage error: FIG_ERR_STATE, <name>: no frame open). A usage error is returned in stat when present; without it, mode 'abort' stops the program here and the other modes keep it for the next app%next_frame (app%set_checks). False, stat untouched, inside a frame on the main thread.

Attributes: recursive

Returns: logical

fortran
function figure_draw_refused(name, stat) result(refused)

Arguments

NameTypeIntentAttributesDescription
namecharacter(len=*)inThe entry point.
statinteger(kind=int32)outoptionalStatus, on a refusal.

Call graph

figure_scope_refused ​

Before an end or a pop: true when it must return at once, because it is called from a task or with no frame open (as figure_draw_refused) or because it does not close the innermost open scope of the record (FIG_ERR_STATE, the message naming both calls); in mode 'recover' an end whose scope is open further down closes the scopes opened after it and goes on. A usage error is returned in stat when present; without it, mode 'abort' stops here and the other modes keep it for the next app%next_frame.

Attributes: recursive

Returns: logical

fortran
function figure_scope_refused(kind, who, n, stat) result(refused)

Arguments

NameTypeIntentAttributesDescription
kindinteger(kind=c_int)inSCOPE_*.
whocharacter(len=*)inThe procedure (ig_end).
ninteger(kind=int32)inoptionalPops (style changes; default 1).
statinteger(kind=int32)outoptionalStatus, on a refusal.

Call graph

format_ok ​

True when fmt is a printf format for one value of family (FORMAT_INTEGER or FORMAT_REAL): exactly one conversion of the family (d, i, u; f, F, e, E, g, G, a, A), with optional flags (-+ #0), width and precision (digits), and any number of %% and other characters. Refused: no conversion or more than one, a conversion of the other family or of none (%s, %c, %p, %x, %n, ...), * for a width or a precision, length modifiers (%ld, %Lf), a % at the end. With text=.true., a format with no conversion (text, %% included, or empty) is accepted too: C prints it as it is and ignores the value. Formats given to C's formatter unchecked are undefined behaviour when they do not match the value: a wrong label at best, a crash at worst.

Attributes: pure

Returns: logical

fortran
function format_ok(fmt, family, text) result(ok)

Arguments

NameTypeIntentAttributesDescription
fmtcharacter(len=*)inThe format.
familyinteger(kind=int32)inFORMAT_INTEGER or FORMAT_REAL.
textlogicalinoptionalAccept a format without conversion (default false).

Call graph

format_refused ​

True when fmt is not a printf format of family (format_ok): the failure is reported as figure_fail does, FIG_ERR_ARGUMENT with a message naming the procedure, the argument and the family expected (stat absent: error stop with it). False, stat untouched, for a good format.

Returns: logical

fortran
function format_refused(name, argument, fmt, family, stat, text) result(refused)

Arguments

NameTypeIntentAttributesDescription
namecharacter(len=*)inThe procedure.
argumentcharacter(len=*)inThe argument holding the format.
fmtcharacter(len=*)inThe format.
familyinteger(kind=int32)inFORMAT_INTEGER or FORMAT_REAL.
statinteger(kind=int32)outoptionalStatus, on a refusal.
textlogicalinoptionalAccept a format without conversion (format_ok).

Call graph

cstr ​

s NUL-terminated, for cimgui/cimplot (trailing blanks kept: labels are taken verbatim).

Attributes: pure

Returns: character(kind=c_char, len=:)

fortran
function cstr(s) result(c)

Arguments

NameTypeIntentAttributesDescription
scharacter(len=*)inFortran string.

Call graph

Released under the MIT licence.