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
- figure_check
- figure_fail
- figure_usage_error
- figure_scope_open
- figure_time
- figure_last_error
- figure_refused
- figure_draw_refused
- figure_scope_refused
- format_ok
- format_refused
- cstr
Variables
| Name | Type | Attributes | Description |
|---|---|---|---|
FORMAT_INTEGER | integer(kind=int32) | parameter | A printf format of an integer value: d, i, u. |
FORMAT_REAL | integer(kind=int32) | parameter | A printf format of a real value: f, F, e, E, g, G, a, A. |
SCOPE_WINDOW | integer(kind=c_int) | parameter | ig_begin, ig_begin_side_bar / ig_end (always paired). |
SCOPE_CHILD | integer(kind=c_int) | parameter | ig_begin_child / ig_end_child (always paired). |
SCOPE_TAB_BAR | integer(kind=c_int) | parameter | ig_begin_tab_bar / ig_end_tab_bar (after true). |
SCOPE_TAB | integer(kind=c_int) | parameter | ig_begin_tab / ig_end_tab (after true). |
SCOPE_TABLE | integer(kind=c_int) | parameter | ig_begin_table / ig_end_table (after true). |
SCOPE_TREE | integer(kind=c_int) | parameter | ig_tree_node / ig_tree_pop (after true). |
SCOPE_MAIN_MENU_BAR | integer(kind=c_int) | parameter | ig_begin_main_menu_bar / ig_end_main_menu_bar (after true). |
SCOPE_MENU_BAR | integer(kind=c_int) | parameter | ig_begin_menu_bar / ig_end_menu_bar (after true). |
SCOPE_MENU | integer(kind=c_int) | parameter | ig_begin_menu / ig_end_menu (after true). |
SCOPE_POPUP | integer(kind=c_int) | parameter | ig_begin_popup, ig_begin_popup_context, ig_begin_popup_modal / ig_end_popup (after true). |
SCOPE_PLOT | integer(kind=c_int) | parameter | ip_begin_plot / ip_end_plot (after true). |
SCOPE_SUBPLOTS | integer(kind=c_int) | parameter | ip_begin_subplots / ip_end_subplots (after true). |
SCOPE_DOCK_LAYOUT | integer(kind=c_int) | parameter | ig_dock_layout_begin / ig_dock_layout_end (after true). |
SCOPE_ID | integer(kind=c_int) | parameter | ig_push_id / ig_pop_id. |
SCOPE_DISABLED | integer(kind=c_int) | parameter | ig_begin_disabled / ig_end_disabled. |
SCOPE_FONT | integer(kind=c_int) | parameter | ig_push_font / ig_pop_font. |
SCOPE_STYLE_COLOR | integer(kind=c_int) | parameter | ig_/ip_push_style_color / ig_/ip_pop_style_color. |
SCOPE_STYLE_VAR | integer(kind=c_int) | parameter | ig_/ip_push_style_var / ig_/ip_pop_style_var. |
SCOPE_GROUP | integer(kind=c_int) | parameter | ig_begin_group / ig_end_group (always paired). |
SCOPE_ALIGN | integer(kind=c_int) | parameter | ig_align_begin / ig_align_end (always paired). |
SCOPE_ITEM_WIDTH | integer(kind=c_int) | parameter | ig_push_item_width / ig_pop_item_width (always paired). |
SCOPE_TOOLTIP | integer(kind=c_int) | parameter | ig_begin_tooltip, ig_begin_item_tooltip / ig_end_tooltip (after true). |
SCOPE_PLOT3D | integer(kind=c_int) | parameter | ip3_begin_plot / ip3_end_plot (after true). |
SCOPE_ALIGNED | integer(kind=c_int) | parameter | ip_begin_aligned / ip_end_aligned (after true). |
SCOPE_LEGEND_POPUP | integer(kind=c_int) | parameter | ip_begin_legend_popup / ip_end_legend_popup (after true). |
SCOPE_MULTI_SELECT | integer(kind=c_int) | parameter | ig_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
subroutine figure_check(status, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
status | integer(kind=c_int) | in | Status from the native layer. | |
stat | integer(kind=int32) | out | optional | Status 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
subroutine figure_fail(status, message, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
status | integer(kind=c_int) | in | Failure status (a FIG_ERR_* code). | |
message | character(len=*) | in | Message for figure_last_error. | |
stat | integer(kind=int32) | out | optional | Status 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
subroutine figure_usage_error(message, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
message | character(len=*) | in | The whole message (: ). | |
stat | integer(kind=int32) | out | optional | Status: 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
subroutine figure_scope_open(kind, who, label, returned, aux)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
kind | integer(kind=c_int) | in | SCOPE_*. | |
who | character(len=*) | in | The procedure (ig_begin). | |
label | character(len=*) | in | Its label or id ('' when none). | |
returned | logical | in | optional | What the begin returned (default true). |
aux | integer(kind=int32) | in | optional | The 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)
function figure_time() result(seconds)Call graph
figure_last_error
Message of the last failed call.
Attributes: recursive
Returns: character(len=:)
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
function figure_refused(name, stat) result(refused)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
name | character(len=*) | in | The entry point. | |
stat | integer(kind=int32) | out | optional | Status, 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
function figure_draw_refused(name, stat) result(refused)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
name | character(len=*) | in | The entry point. | |
stat | integer(kind=int32) | out | optional | Status, 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
function figure_scope_refused(kind, who, n, stat) result(refused)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
kind | integer(kind=c_int) | in | SCOPE_*. | |
who | character(len=*) | in | The procedure (ig_end). | |
n | integer(kind=int32) | in | optional | Pops (style changes; default 1). |
stat | integer(kind=int32) | out | optional | Status, 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
function format_ok(fmt, family, text) result(ok)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
fmt | character(len=*) | in | The format. | |
family | integer(kind=int32) | in | FORMAT_INTEGER or FORMAT_REAL. | |
text | logical | in | optional | Accept 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
function format_refused(name, argument, fmt, family, stat, text) result(refused)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
name | character(len=*) | in | The procedure. | |
argument | character(len=*) | in | The argument holding the format. | |
fmt | character(len=*) | in | The format. | |
family | integer(kind=int32) | in | FORMAT_INTEGER or FORMAT_REAL. | |
stat | integer(kind=int32) | out | optional | Status, on a refusal. |
text | logical | in | optional | Accept 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=:)
function cstr(s) result(c)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
s | character(len=*) | in | Fortran string. |
Call graph