Skip to content

figure_app ​

figure_app, the application: window, frame loop and lazy redraw.

The whole life of a FIGURE program is one loop:

fortran
 call app%init('My tool', 1280, 720)
 do while (app%next_frame())
    ! declare the UI: widgets return what happened this frame
 enddo
 call app%destroy()

next_frame renders the previous frame, then waits for input and opens the next one (lazy redraw: once the UI settles it sleeps until input or max_wait, so an idle window costs a fraction of a percent of one core); it returns .false. when the user closes the window. There are no widget objects, handles or callbacks: the state is the application's own variables.

Source: src/lib/figure_app.F90

Dependencies

Contents ​

Derived Types ​

app_object ​

A FIGURE application (one per program).

The native layer owns the lifecycle state (initialized, frame open) and rejects out-of-order calls with FIG_ERR_STATE; only in_frame is mirrored here, because next_frame must know whether to close a frame.

Components

NameTypeAttributesDescription
in_framelogicalA frame is open.

Type-Bound Procedures

NameAttributesDescription
initpass(self)Open the window.
init_headlesspass(self)Contexts only, no window (tests).
init_remotepass(self)The UI in a web browser (no window, display or GPU).
next_framepass(self)Close the current frame, open the next; false on quit.
set_checkspass(self)What a usage error does: 'abort', 'report' (default), 'recover'.
set_lazypass(self)Lazy redraw on/off, longest sleep.
set_stylepass(self)The style: a name, or a look and a palette.
palette_colorpass(self)The colour of a palette role in effect.
set_dockingpass(self)Docking on (the default) or off.
set_fontpass(self)The default font and its size.
add_fallback_fontpass(self)A font for the glyphs the text fonts lack.
load_stylepass(self)A theme file.
save_stylepass(self)The style in effect, as a theme file.
request_framespass(self)Redraw without waiting for input.
wakepass(self)Start the next frame at once (from any thread).
set_confirm_quitpass(self)Report a quit request instead of quitting.
quit_requestedpass(self)The user asked to quit (once per request).
droppedpass(self)The files and folders dropped on the window this frame.
quitpass(self)End the loop at the next frame.
set_titlepass(self)The window's title, after init.
titlepass(self)The window's title.
open_file_dialogpass(self)The system's dialog to choose a file to open.
save_file_dialogpass(self)The system's dialog to choose where to save.
open_folder_dialogpass(self)The system's dialog to choose a folder.
open_file_browserpass(self)FIGURE's browser to choose a file (or a folder) to open.
save_file_browserpass(self)FIGURE's browser to choose where to save.
file_dialog_resultpass(self)The answer to a dialog or a browser, once given.
save_imagepass(self)A rectangle of the window as a PNG file, after this frame.
image_resultpass(self)The outcome of save_image, once.
save_layoutpass(self)The arrangement of the windows (docking included) to a file.
load_layoutpass(self)An arrangement from a file, applied before the next frame.
notifypass(self)Tell the user something, in a notification.
notificationspass(self)The notifications kept (the last 100).
add_windowpass(self)Register a window: the View menu, its close button, kept hidden.
window_visiblepass(self)A registered window is shown.
set_window_visiblepass(self)Show or hide a registered window.
view_menupass(self)The View menu: the windows, the layouts, Reset layout.
add_layoutpass(self)Declare a named layout.
switch_layoutpass(self)Make a layout current: laid out again, or as the user left it.
reset_layoutpass(self)Lay the current layout out again.
layoutpass(self)The current layout's name: the one to build.
open_prefspass(self)Read the preferences from the program's file, kept there from now on.
prefs_filepass(self)The preferences' file.
save_pref_logicalpass(self)Keep the preference key: a logical (as save_pref of a text, written true or false).
save_pref_real64pass(self)Keep the preference key: a real (as save_pref of a text, written with 17 significant digits: read back exactly).
save_pref_real32pass(self)Keep the preference key: a real (as save_pref of a text, written with 9 significant digits: read back exactly).
save_pref_int64pass(self)Keep the preference key: a 64-bit integer (as save_pref of a text, written in decimal).
save_pref_int32pass(self)Keep the preference key: an integer (as save_pref of a text, written in decimal).
save_pref_textpass(self)Keep the preference key: a text (every character kept, trailing blanks too). In memory until the next save of the file (open_prefs); without open_prefs, for this run. Statuses: FIG_ERR_ARGUMENT for a key that is empty, has a newline or a blank at an end, or starts with [, # or ;; FIG_ERR_STATE before init* or from a task.
save_prefKeep a preference. Generic: save_pref_text, save_pref_int32, save_pref_int64
save_prefKeep a preference. Generic: save_pref_real32, save_pref_real64, save_pref_logical
load_pref_logicalpass(self)The preference key into value as a logical (true or false): as load_pref of an integer.
load_pref_real64pass(self)The preference key into value as a real: as load_pref of an integer.
load_pref_real32pass(self)The preference key into value as a real: as load_pref of an integer.
load_pref_int64pass(self)The preference key into value as a 64-bit integer: as load_pref of an integer.
load_pref_int32pass(self)The preference key into value as an integer: true when it is kept and is one; otherwise false, and value takes default if present, else stays as it is (a text edited into something else counts as not kept).
load_pref_textpass(self)The preference key into value: true when it is kept (value takes it, blank-padded or cut to its length); false when it is not, and value takes default if present, else stays as it is. Statuses: as save_pref's.
load_prefA preference kept, or a default. Generic: load_pref_text, load_pref_int32, load_pref_int64
load_prefA preference kept, or a default. Generic: load_pref_real32, load_pref_real64, load_pref_logical
message_boxpass(self)A question in a box: 0 while open, then the button chosen.
set_size_limitspass(self)The window's least and greatest size.
content_scalepass(self)Display content scale.
destroypass(self)Close everything.
set_icon_imagepass(self)The window's icon from an image.
set_icon_glyphpass(self)The window's icon from an ICON_*.
set_iconThe window's icon: an image or an ICON_*. Generic: set_icon_image, set_icon_glyph

Subroutines ​

init ​

Open the window (width x height logical pixels) and create the ImGui/ImPlot contexts.

Window positions and sizes are not saved by default: with ini_file, Dear ImGui keeps them in that file, read at the first frame and written while the program runs (its imgui.ini); not while FIGURE_CAPTURE records.

decorations='figure' opens the window without the system's frame and draws one: a title bar with the icon (set_icon), the program's main menu bar (ig_begin_main_menu_bar) inside it, the title centred, and the minimize, maximize (restore) and close buttons, in the colours of the palette's roles. The bar drags the window, its edges resize it, a double-click on it maximizes; close takes the quit path of the system's close button (set_confirm_quit). buttons puts them on the 'right' (the default) or the 'left' (the default on macOS).

Attributes: recursive

fortran
subroutine init(self, title, width, height, vsync, stat, ini_file, decorations, buttons)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
titlecharacter(len=*)inWindow title.
widthinteger(kind=int32)inWidth [logical pixels].
heightinteger(kind=int32)inHeight [logical pixels].
vsynclogicalinoptionalSynchronize with the display (default true).
statinteger(kind=int32)outoptionalFIG_ERR_ARGUMENT for a wrong size or option.
ini_filecharacter(len=*)inoptionalFile keeping the window layout (default: none).
decorationscharacter(len=*)inoptionalThe window's frame: 'native' (default) or 'figure'.
buttonscharacter(len=*)inoptionalWith 'figure': 'right' or 'left' (default: the platform's side, left on macOS).

Call graph

init_headless ​

Create the contexts on a virtual width x height display, without window or GPU.

decorations='figure' draws the title bar of init's decorations='figure' as in a window, for tests: its buttons' actions are recorded as state (test_frame_state), close takes the quit path.

Attributes: recursive

fortran
subroutine init_headless(self, width, height, stat, decorations, buttons)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
widthinteger(kind=int32)inWidth [pixels].
heightinteger(kind=int32)inHeight [pixels].
statinteger(kind=int32)outoptionalStatus: FIG_ERR_ARGUMENT for a wrong size or option.
decorationscharacter(len=*)inoptional'native' (default: no bar) or 'figure'.
buttonscharacter(len=*)inoptionalWith 'figure': 'right' or 'left'.

Call graph

set_icon_image ​

The window's icon (task bar, dock, the title bar of decorations='figure') from an image, image(4, width, height): image(:, i, j) = R, G, B, A of pixel (i, j), j = 1 the top row. Window mode only (and a window's program captured headless, FIGURE_CAPTURE_HEADLESS: the title bar's icon); 1 to 1024 pixels a side (64 x 64 or 256 x 256 are usual).

Attributes: recursive

fortran
subroutine set_icon_image(self, image, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
imageinteger(kind=int8)incontiguous, targetPixels.
statinteger(kind=int32)outoptionalmodes, FIG_ERR_ARGUMENT for a wrong shape, FIG_ERR_FAILED where the system has no window icons (the title bar's is set).

Call graph

set_icon_glyph ​

The window's icon from one of the bundled icons, ICON_*: rendered at 64 x 64 pixels in the palette's text on accent colour on a rounded square of its accent; the title bar of decorations='figure' shows the glyph in the accent colour. Window mode only (and a window's program captured headless, FIGURE_CAPTURE_HEADLESS: the title bar's icon).

Attributes: recursive

fortran
subroutine set_icon_glyph(self, icon, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
iconcharacter(len=*)inOne ICON_* constant.
statinteger(kind=int32)outoptionalFIG_ERR_ARGUMENT if icon is not one icon, FIG_ERR_FAILED where the system has no window icons (the title bar's is set).

Call graph

init_remote ​

Create the contexts and serve the UI to a web browser on http://host:port/ instead of opening a window: the program needs no display or GPU (a cluster node will do). One browser at a time, which can come and go while the program runs. The page and its connection need an access token in the address (http://localhost:8080/?token=..., printed at start, returned in url): 32 random hex digits, or token (token='' disables it: anyone who reaches the port then controls the program). Keep the default host (127.0.0.1) and reach a remote machine through an SSH tunnel (ssh -L 8080:localhost:8080 node).

A browser has no vsync to pace the program, so frames are capped at max_fps per second (default 60), and a frame is sent only once the previous one has left: with a slow client the newest frame goes, the ones in between are skipped. A frame equal to the last one sent is not sent again. Vertices travel in 12 bytes instead of 20, and compress deflates frames and textures: 'auto' (default) while the client is the bottleneck (frames are being skipped), 'always', or 'never'; deflate costs about 7 ms of CPU per MB and shrinks frames 2.5 to 3.5 times. With lossy (default true) an image updated in consecutive frames (a 3-D view while the camera moves) travels as JPEG at quality 75 while it changes, 30 to 190 times smaller than raw, and exact once it has not changed for 150 ms; lossy=.false. always sends exact pixels. Images with transparent pixels always go exact.

Attributes: recursive

fortran
subroutine init_remote(self, port, host, width, height, port_used, quiet, max_fps, compress, lossy, token, url, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
portinteger(kind=int32)inoptionalPort (default 8080; 0: any free port).
hostcharacter(len=*)inoptionalAddress to listen on (default 127.0.0.1).
widthinteger(kind=int32)inoptionalDisplay width until the browser's [pixels] (default 1280).
heightinteger(kind=int32)inoptionalDisplay height until the browser's [pixels] (default 800).
port_usedinteger(kind=int32)outoptionalThe port listened on (useful with port 0).
quietlogicalinoptionalDo not print the address to open (default false).
max_fpsreal(kind=real64)inoptionalMost frames per second (default 60; 0: no cap).
compresscharacter(len=*)inoptionalDeflate frames and textures: 'auto', 'always', 'never'.
lossylogicalinoptionalChanging images as JPEG, exact when still (default true).
tokencharacter(len=*)inoptionalAccess token (default: random; '': none).
urlcharacter(len=*)outoptionalThe address to open, with the token (blank-padded).
statinteger(kind=int32)outoptionalStatus.

Call graph

set_checks ​

What a usage error does: a wrong end (one that does not close the innermost open scope, or follows a begin that returned false where the rule is "end only after a true begin"), a scope left open at the end of the frame, a drawing procedure called with no frame open. FIGURE keeps a record of the scopes open in the frame (every begin/end and push/pop pair it wraps) and checks each end against it before Dear ImGui sees it; the messages name the Fortran calls (ig_end_table: the open scope is ig_tree_node('Blocks') (close it with ig_tree_pop before ig_end_table)). mode:

  • 'abort': the program stops (error stop, the message on standard error) at the call that breaks the rule, or at next_frame for a scope left open; calls outside FIGURE (raw bindings) meet Dear ImGui's own assertions;
  • 'report' (the default): the wrong call is refused (it does nothing), the frame goes on, the scopes left open are closed, and the next next_frame returns FIG_ERR_STATE with every message (without its stat: error stop, as any failure);
  • 'recover': as 'report', but an end whose scope is open further down first closes the scopes opened after it, and next_frame shows the messages in a notification (figure_last_error has them) and returns FIG_OK.

A call with a stat of its own (ig_pop_style_color(stat=s)) gets its usage error there, in every mode. Callable before init*; destroy restores the default. Statuses: FIG_ERR_ARGUMENT for another mode, FIG_ERR_STATE from a task. The same in every mode (window, headless, remote).

Attributes: recursive

fortran
subroutine set_checks(self, mode, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
modecharacter(len=*)in'abort', 'report' or 'recover'.
statinteger(kind=int32)outoptionalStatus.

Call graph

set_lazy ​

Lazy redraw (default on): once the UI settles, sleep until input or max_wait seconds (default 0.5). Callable from any thread (a task included).

Attributes: recursive

fortran
subroutine set_lazy(self, enabled, max_wait)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
enabledlogicalinLazy redraw on.
max_waitreal(kind=real64)inoptionalLongest sleep [s]: the refresh period of live data.

Call graph

set_style ​

The style of the interface, the plots and the window's background, after init*: by name, or by its two parts, a look (the geometry) and a palette (the colours). Changing one part keeps the other.

Names (each a theme file, themes/<name>.toml, embedded):

  • 'seal' (the default), 'seal-light': FIGURE's, from its mark: ink (or paper) and one vermilion, spent on what the user touches and on the first plotted line; square corners;
  • 'paper': for publication, black on white, thin borders, line colours that survive greyscale printing;
  • 'high-contrast': white on black with yellow accents, text at 7:1 or more (WCAG AAA);
  • 'dark', 'light', 'classic': Dear ImGui's own styles, with ImPlot's default line colours.

Looks: 'seal', 'fusion', 'adwaita', 'fluent'. Palettes: 'seal', 'seal-light', 'paper', 'high-contrast', 'nord', 'solarized-dark', 'solarized-light', 'gruvbox-dark', 'gruvbox-light', 'dracula', 'catppuccin-mocha', 'catppuccin-latte', 'tokyo-night', 'one-dark', and 'auto', which follows the system's light or dark setting (auto_dark, default 'seal'; auto_light, default 'seal-light') and changes with it while the program runs; in headless and remote modes the setting is unknown and counts as dark. A palette's colours are derived from twelve roles and checked for contrast (docs, Styles, Palettes).

The parts are applied in order, all or none: name, then look, then palette, then lines ('okabe-ito' replaces the line colours with Okabe and Ito's colour-blind-safe set). The environment variable FIGURE_STYLE picks the style at initialisation; this call overrides it. The font and its size are kept; colours and variables changed by name are reset by the part that sets them.

Attributes: recursive

fortran
subroutine set_style(self, name, lines, stat, look, palette, auto_dark, auto_light)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
namecharacter(len=*)inoptionalStyle name.
linescharacter(len=*)inoptionalLine palette: 'okabe-ito' (default: the style's own).
statinteger(kind=int32)outoptionalpalette, a palette below the contrast rule, or no argument.
lookcharacter(len=*)inoptionalLook: the geometry (rounding, padding, spacing, borders).
palettecharacter(len=*)inoptionalPalette: the colours, or 'auto'.
auto_darkcharacter(len=*)inoptionalPalette of 'auto' on a dark system (default 'seal').
auto_lightcharacter(len=*)inoptionalPalette of 'auto' on a light system (default 'seal-light').

Call graph

palette_color ​

The colour of a palette role in effect, as [r, g, b, a] in [0, 1]: 'background', 'surface', 'raised_surface', 'border', 'text', 'dimmed_text', 'accent', 'text_on_accent', 'selection', 'success', 'warning', 'error'. With a style that has no palette ('dark', 'light', 'classic', a theme file without one), the roles are read from Dear ImGui's colours (WindowBg, FrameBg, Button, Border, Text, TextDisabled, CheckMark, Header), and success, warning and error are Okabe and Ito's bluish green, orange and vermilion. After init*; the same in every mode.

Attributes: recursive

fortran
subroutine palette_color(self, role, rgba, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
rolecharacter(len=*)inRole name.
rgbareal(kind=real64)outColour, components in [0, 1].
statinteger(kind=int32)outoptionalStatus: FIG_ERR_ARGUMENT for an unknown role.

Call graph

notify ​

Tell the user something without a dialog: a notification drawn by FIGURE after the program's windows, in the bottom-right corner (above a bottom side bar), the newest at the bottom, older ones stacked above. kind: 'info' (default), 'success', 'warning' or 'error', drawn with its palette role (accent, success, warning, error) and its icon (ICON_INFO, ICON_CIRCLE_CHECK, ICON_TRIANGLE_ALERT, ICON_CIRCLE_X). It stays seconds (default 5; 0 or less: until clicked), fading out in its last half second, timed by the frame time (the fixed one in headless mode and in recordings); a click dismisses it. The last 100 are kept (notifications). Statuses: FIG_ERR_STATE before init* or from a task, FIG_ERR_ARGUMENT for an unknown kind. The same in every mode.

Attributes: recursive

fortran
subroutine notify(self, text, kind, seconds, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
textcharacter(len=*)inWhat to tell (UTF-8; wrapped).
kindcharacter(len=*)inoptional'info', 'success', 'warning' or 'error'.
secondsreal(kind=real64)inoptionalTime shown [s] (default 5; <= 0: until clicked).
statinteger(kind=int32)outoptionalStatus.

Call graph

notifications ​

The notifications kept, the last 100, oldest first: their texts (list, padded with blanks to the longest), their kinds ('info', ...) and whether each is still shown (not yet timed out or dismissed). None before init*.

Attributes: recursive

fortran
subroutine notifications(self, list, kinds, shown)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.
listcharacter(len=:)outallocatableTexts.
kindscharacter(len=7)outallocatable, optionalKinds.
shownlogicaloutallocatable, optionalStill shown.

Call graph

set_font ​

The default font of the interface, after init*: 'plex-sans' (IBM Plex Sans, bundled: the default, at 15 logical pixels), 'plex-mono' (IBM Plex Mono, bundled: monospace, every character as wide), 'proggy' (Dear ImGui's own 13-pixel bitmap font), or the path of a TrueType/OpenType file; size in logical pixels (multiplied by the display's content scale), kept if absent.

Attributes: recursive

fortran
subroutine set_font(self, font, size, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
fontcharacter(len=*)inFont.
sizereal(kind=real64)inoptionalSize [logical pixels], in (0, 200].
statinteger(kind=int32)outoptionalFIG_ERR_ARGUMENT if it is not a font or the size is wrong.

Call graph

add_fallback_font ​

A fallback font of the program's own, a TrueType/OpenType file: merged into every text font (the bundled ones, 'proggy' and the files of set_font/ig_push_font, loaded already or later) after IBM Plex, the Lucide icons and the bundled fallback, Noto Sans Math, so it gives only the glyphs they all lack; several are asked in the order they are added. Its letters are scaled to the text font's em and stand on its baseline. After init*, between frames (not inside one); a file added already is not added again; it lasts until destroy. At most 13 (Dear ImGui's 16 sources per font). The same in every mode (in remote mode the browser receives the glyphs).

Attributes: recursive

fortran
subroutine add_fallback_font(self, file, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
filecharacter(len=*)inTrueType/OpenType file.
statinteger(kind=int32)outoptionalFIG_ERR_ARGUMENT if it is not a font or 13 are added already, FIG_ERR_STATE before init* or inside a frame.

Call graph

load_style ​

Apply a theme file (the format of the files in themes/: docs, Styles, Theme files), after init*. Sizes in the file are logical pixels; what the file does not set comes from its base.

Attributes: recursive

fortran
subroutine load_style(self, file, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
filecharacter(len=*)inTheme file.
statinteger(kind=int32)outoptionalmalformed (the message gives the line).

Call graph

save_style ​

Write the style in effect as a theme file: its base, background, line colours, and every colour and variable that differs from the base (sizes in logical pixels; colours as 8-bit hex, alphas exact). Changes made by name or in the style editor (ig_show_style_editor) are kept; load_style reads the file back.

Attributes: recursive

fortran
subroutine save_style(self, file, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
filecharacter(len=*)inTheme file to write.
statinteger(kind=int32)outoptional

Call graph

set_docking ​

Docking on (the default since init*) or off: with docking on, a window dragged by its title bar docks into another window or into a dock space (ig_dock_space). After init*.

Attributes: recursive

fortran
subroutine set_docking(self, enabled, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
enabledlogicalinDocking on.
statinteger(kind=int32)outoptional

Call graph

request_frames ​

Draw at least n more frames without waiting for input (e.g. after new data arrived). It raises the count of frames still to draw, never lowers it: concurrent requests keep the largest. Callable from any thread (a task, an OpenMP thread): from another thread than the loop's it also wakes a lazy loop that is waiting, so the first of the frames starts at once.

Attributes: recursive

fortran
subroutine request_frames(self, n)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
ninteger(kind=int32)inFrames.

Call graph

wake ​

The next frame starts without waiting for input or max_wait, from any thread (a FIGURE task, an OpenMP thread, an MPI progress thread): a lazy loop that is waiting stops waiting, in every mode (window: an event; remote: the wait on the network ends; headless: the loop never waits). From the loop's own thread, the next next_frame does not wait. Never refused: a task may call it. Before init* it does nothing.

Attributes: recursive

fortran
subroutine wake(self)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.

Call graph

set_confirm_quit ​

With enabled, the window's close button (and the system's quit) no longer ends next_frame: the request is reported by quit_requested, and the program quits with quit (after asking to save, for example). Callable from any thread (a task included).

Attributes: recursive

fortran
subroutine set_confirm_quit(self, enabled)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
enabledlogicalinAsk first.

Call graph

quit ​

End the loop: the next next_frame returns .false. (in every mode). Callable from any thread (a task included): from another thread than the loop's it also wakes a lazy loop that is waiting, so the loop ends at once.

Attributes: recursive

fortran
subroutine quit(self)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.

Call graph

set_title ​

The window's title, after init: the document being edited and a mark when it has changes, for example. Shown in window mode; in remote and headless modes it is kept (read back by title) and nothing shows it.

Attributes: recursive

fortran
subroutine set_title(self, text, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
textcharacter(len=*)inTitle.
statinteger(kind=int32)outoptionalStatus.

Call graph

open_file_dialog ​

Show the system's dialog to choose a file to open. It does not block: the interface keeps drawing, and the answer is read with file_dialog_result(id, ...) on the following frames. filters: entries 'name|pattern', the pattern being extensions separated by ; ('Input files|input;inp', 'All files|*'). Window mode only: FIG_ERR_STATE in remote and headless modes (FIGURE's own browser, open_file_browser, works there). prefer='figure' opens FIGURE's browser instead (open_file_browser), in every mode, answered the same way; 'system' (default) the system's dialog. Statuses: as the dialog or the browser opened; FIG_ERR_ARGUMENT for another prefer.

Attributes: recursive

fortran
subroutine open_file_dialog(self, id, filters, default_path, stat, prefer)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
idcharacter(len=*)inDialog id (any text, used to read the answer).
filterscharacter(len=*)inoptionalFile type filters.
default_pathcharacter(len=*)inoptionalFolder or file to start from (relative: to the working directory; absent: that directory).
statinteger(kind=int32)outoptionalStatus.
prefercharacter(len=*)inoptional'system' (default) or 'figure': FIGURE's browser.

Call graph

save_file_dialog ​

Show the system's dialog to choose where to save (a new or an existing file); as open_file_dialog (prefer='figure': FIGURE's browser, save_file_browser).

Attributes: recursive

fortran
subroutine save_file_dialog(self, id, filters, default_path, stat, prefer)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
idcharacter(len=*)inDialog id.
filterscharacter(len=*)inoptionalFile type filters.
default_pathcharacter(len=*)inoptionalFolder or file to start from (relative: to the working directory; absent: that directory).
statinteger(kind=int32)outoptionalStatus.
prefercharacter(len=*)inoptional'system' (default) or 'figure': FIGURE's browser.

Call graph

open_folder_dialog ​

Show the system's dialog to choose a folder; as open_file_dialog (prefer='figure': FIGURE's browser, open_file_browser with folders=.true.).

Attributes: recursive

fortran
subroutine open_folder_dialog(self, id, default_path, stat, prefer)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
idcharacter(len=*)inDialog id.
default_pathcharacter(len=*)inoptionalFolder to start from (relative: to the working directory; absent: that directory).
statinteger(kind=int32)outoptionalStatus.
prefercharacter(len=*)inoptional'system' (default) or 'figure': FIGURE's browser.

Call graph

open_file_browser ​

Show FIGURE's file browser to choose a file to open (or, with folders, a folder): a modal drawn by FIGURE in Dear ImGui, in the palette's colours, the same in window, remote and headless modes (in remote mode it lists the files of the machine the program runs on). It does not block: the answer is read with file_dialog_result(id, ...), as a system dialog's, so a program switches between the two by changing this call. The browser lists the folder's entries (folders first, sizes, modification times; sorted by a click on a column's header), filtered by filters (as open_file_dialog's, chosen in a list) with hidden files on request; a path field (Enter goes there, Tab completes), the parent folder, places (home, the working directory, the file systems' roots, the recent folders kept between runs in FIGURE's settings file) and a new folder. Escape or Cancel cancels. A folder that cannot be read is reported in the browser. Statuses: FIG_ERR_STATE before init*, from a task, or for an id with a dialog or a browser still open; FIG_ERR_ARGUMENT for a malformed filter.

Attributes: recursive

fortran
subroutine open_file_browser(self, id, filters, default_path, folders, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
idcharacter(len=*)inDialog id (any text, used to read the answer).
filterscharacter(len=*)inoptionalFile type filters, 'name|pattern' (the first in effect).
default_pathcharacter(len=*)inoptionalFolder to start in, or a file (its folder; the file selected); relative: to the working directory (absent: that directory).
folderslogicalinoptionalChoose a folder instead of a file (default false).
statinteger(kind=int32)outoptionalStatus.

Call graph

save_file_browser ​

Show FIGURE's file browser to choose where to save: a name typed in the folder shown, or an existing file; a file that exists is replaced only after the user says so. As open_file_browser; default_path may name the file to propose (its folder need exist, the file need not).

Attributes: recursive

fortran
subroutine save_file_browser(self, id, filters, default_path, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
idcharacter(len=*)inDialog id.
filterscharacter(len=*)inoptionalFile type filters, 'name|pattern'.
default_pathcharacter(len=*)inoptionalFolder to start in, or the file to propose.
statinteger(kind=int32)outoptionalStatus.

Call graph

file_dialog_result ​

The answer to the dialog or the browser id: done false while it is open; once answered, done true and either path (the file or folder chosen, absolute for the browser) or cancelled true. The answer is given once; then the id is free again, and until the next dialog done is false: poll it every frame. A dialog that failed (Linux without a portal or zenity) gives done true and FIG_ERR_FAILED with the reason.

Attributes: recursive

fortran
subroutine file_dialog_result(self, id, path, done, cancelled, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
idcharacter(len=*)inDialog id.
pathcharacter(len=:)outallocatableChosen path ('' while open or if cancelled).
donelogicaloutThe dialog was answered.
cancelledlogicaloutoptionalThe user cancelled it.
statinteger(kind=int32)outoptionalStatus.

Call graph

save_image ​

Write the rectangle (xmin, ymin)-(xmax, ymax) of the window [logical pixels, as ig_item_rect and test_window_rect give them] as a PNG file, at the screen's resolution, when the current frame is rendered. Ask for it outside the frame in which a menu or popup covers the rectangle (they would be in the picture). The outcome comes once, from image_result. Every mode: a window's pixels are read back from the GPU, headless and remote modes draw the frame with FIGURE's CPU renderer (capture.md). An empty rectangle or file name, FIG_ERR_ARGUMENT; before init*, FIG_ERR_STATE.

Attributes: recursive

fortran
subroutine save_image(self, path, xmin, ymin, xmax, ymax, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
pathcharacter(len=*)inPNG file.
xminreal(kind=real64)inLeft.
yminreal(kind=real64)inTop.
xmaxreal(kind=real64)inRight.
ymaxreal(kind=real64)inBottom.
statinteger(kind=int32)outoptionalStatus.

Call graph

image_result ​

The outcome of save_image, once, after the frame that wrote it: done true and the file path, or FIG_ERR_FAILED with the reason (the file cannot be written). done false before and after: poll it every frame.

Attributes: recursive

fortran
subroutine image_result(self, path, done, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
pathcharacter(len=:)outallocatableThe file ('' until done).
donelogicaloutWritten, or failed.
statinteger(kind=int32)outoptionalStatus.

Call graph

save_layout ​

Write the layout to path: the windows' positions, sizes and docking (the dock nodes and which window is in which), the tables' columns: Dear ImGui's settings, as its ini text, for every window shown in this session and those read before. comment (lines separated by new_line('a')) is written first, each line led by '; ', which load_layout skips: the program's own state (the windows it opens on demand, say) for itself to read back. Any mode. FIG_ERR_FAILED if the file cannot be written.

Attributes: recursive

fortran
subroutine save_layout(self, path, comment, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
pathcharacter(len=*)inFile.
commentcharacter(len=*)inoptionalLines to keep with it.
statinteger(kind=int32)outoptionalStatus.

Call graph

load_layout ​

Read a layout written by save_layout (or an ini file of Dear ImGui), applied before the next frame: the settings in effect are cleared, the file's are read, the dock nodes are rebuilt and the windows that exist take their saved position, size and dock; the others take theirs when they appear. A program that lays out its dock space with ig_dock_layout_begin should not lay it out again: the dock space has a layout again (the same id as when saved). FIG_ERR_FAILED if the file cannot be read, FIG_ERR_ARGUMENT if it holds no layout.

Attributes: recursive

fortran
subroutine load_layout(self, path, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
pathcharacter(len=*)inFile.
statinteger(kind=int32)outoptionalStatus.

Call graph

add_window ​

Register the window name (the name given to ig_begin) with FIGURE's window registry: view_menu lists it as a check item that shows and hides it, ig_begin(name) (without open) gives it a close button that hides it, and the preferences (open_prefs) keep whether it is shown from one run to the next. The program draws it only while window_visible(name) is true. After init*, before or after open_prefs (a window added after takes its kept visibility when added). Statuses: FIG_ERR_ARGUMENT for an empty name or one added already, FIG_ERR_STATE before init* or from a task. The same in every mode.

Attributes: recursive

fortran
subroutine add_window(self, name, visible, closable, in_view_menu, remember, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
namecharacter(len=*)inWindow name, as given to ig_begin.
visiblelogicalinoptionalShown at the first run (default true).
closablelogicalinoptionalA close button (default true).
in_view_menulogicalinoptionalListed in the View menu (default true).
rememberlogicalinoptionalShown or hidden as at the end of the last run (default true).
statinteger(kind=int32)outoptionalStatus.

Call graph

set_window_visible ​

Show or hide the registered window name from the program (a Log window shown when an error arrives). Statuses: FIG_ERR_ARGUMENT for a name not added, FIG_ERR_STATE from a task.

Attributes: recursive

fortran
subroutine set_window_visible(self, name, visible, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
namecharacter(len=*)inWindow name.
visiblelogicalinShown.
statinteger(kind=int32)outoptionalStatus.

Call graph

view_menu ​

The View menu, inside a menu bar (ig_begin_main_menu_bar or ig_begin_menu_bar): a check item per registered window listed in it (its name without the ## part), in the order added; then, with layouts, one item per layout (the current one checked: a click switches to it); then "Reset layout" (reset_layout), shown with layouts or once a dock space was laid out with ig_dock_layout_begin. Each frame, where the menu goes. Statuses: FIG_ERR_STATE with no frame open or from a task. The same in every mode.

Attributes: recursive

fortran
subroutine view_menu(self, label, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
labelcharacter(len=*)inoptionalThe menu's label (default 'View').
statinteger(kind=int32)outoptionalStatus.

Call graph

add_layout ​

Declare the layout name: an arrangement of the dock space the program builds when ig_dock_layout_begin returns true and layout() is name (FIGURE calls nothing of the program's: the builder is the program's code under that test). The first added is current, unless the preferences kept another. windows, the registered windows the layout shows (the other registered ones are hidden when it becomes current); absent, switching to it leaves them as they are. Statuses: FIG_ERR_ARGUMENT for an empty name or one added already, FIG_ERR_STATE before init* or from a task.

Attributes: recursive

fortran
subroutine add_layout(self, name, windows, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
namecharacter(len=*)inLayout name (shown in the View menu).
windowscharacter(len=*)inoptionalThe registered windows it shows (blank-padded).
statinteger(kind=int32)outoptionalStatus.

Call graph

switch_layout ​

Make the layout name current (the View menu does it on a click). The arrangement the user left the current one in is kept; then, if name was arranged by the user earlier in this run (or in the last, by the preferences), that arrangement comes back before the next frame; otherwise each dock space laid out with ig_dock_layout_begin is laid out again: ig_dock_layout_begin returns true on its next call and the program builds layout(). A layout with windows shows those and hides the other registered windows. Statuses: FIG_ERR_ARGUMENT for a layout not added, FIG_ERR_STATE from a task. Between frames or inside one; the same in every mode.

Attributes: recursive

fortran
subroutine switch_layout(self, name, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
namecharacter(len=*)inLayout name.
statinteger(kind=int32)outoptionalStatus.

Call graph

reset_layout ​

Lay the current layout out again (the View menu's "Reset layout"): the user's changes to it are forgotten, each dock space laid out with ig_dock_layout_begin is laid out again on the next frame, and a layout with windows shows those again. Without layouts, the dock spaces are laid out again all the same. Status: FIG_ERR_STATE from a task.

Attributes: recursive

fortran
subroutine reset_layout(self, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
statinteger(kind=int32)outoptionalStatus.

Call graph

open_prefs ​

Keep the program's preferences in a file from now on, and read those of the last run: the values of save_pref, the registered windows' visibility, the current layout and the arrangement of each layout, the style set by set_style and, in window mode, the window's position, size and maximized state. Read now: the style and the window's geometry are applied at once, the arrangement before the next frame; so call it after init* and after the program's own defaults (set_style), before the first frame. Written when something changed, every 30 s of frame time and at destroy, to <file>.tmp first and then renamed over the file: a crash leaves the file of the last save whole. The file: file, or preferences.ini in the platform's folder for the program name (SDL's SDL_GetPrefPath: ~/.local/share/<name>/ on Linux, %APPDATA%\<name>\ on Windows, ~/Library/Application Support/<name>/ on macOS); in headless mode without file none (kept in memory: tests name a file), and during a capture (FIGURE_CAPTURE) nothing is read or written. A file that does not exist yet is not an error. Not kept: a theme file (load_style), the style editor's changes, the colours and variables set by name, the fonts. Statuses: FIG_ERR_ARGUMENT for a name that is not a folder's name (letters, digits, blanks, ., _, -), FIG_ERR_STATE before init*, a second time, or from a task.

Attributes: recursive

fortran
subroutine open_prefs(self, name, file, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
namecharacter(len=*)inThe program's name: its folder of preferences.
filecharacter(len=*)inoptionalThe file instead (relative: to the working directory).
statinteger(kind=int32)outoptionalStatus.

Call graph

save_pref_text ​

Keep the preference key: a text (every character kept, trailing blanks too). In memory until the next save of the file (open_prefs); without open_prefs, for this run. Statuses: FIG_ERR_ARGUMENT for a key that is empty, has a newline or a blank at an end, or starts with [, # or ;; FIG_ERR_STATE before init* or from a task.

Attributes: recursive

fortran
subroutine save_pref_text(self, key, value, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
keycharacter(len=*)inKey.
valuecharacter(len=*)inValue.
statinteger(kind=int32)outoptionalStatus.

Call graph

save_pref_int32 ​

Keep the preference key: an integer (as save_pref of a text, written in decimal).

Attributes: recursive

fortran
subroutine save_pref_int32(self, key, value, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
keycharacter(len=*)inKey.
valueinteger(kind=int32)inValue.
statinteger(kind=int32)outoptionalStatus.

Call graph

save_pref_int64 ​

Keep the preference key: a 64-bit integer (as save_pref of a text, written in decimal).

Attributes: recursive

fortran
subroutine save_pref_int64(self, key, value, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
keycharacter(len=*)inKey.
valueinteger(kind=int64)inValue.
statinteger(kind=int32)outoptionalStatus.

Call graph

save_pref_real32 ​

Keep the preference key: a real (as save_pref of a text, written with 9 significant digits: read back exactly).

Attributes: recursive

fortran
subroutine save_pref_real32(self, key, value, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
keycharacter(len=*)inKey.
valuereal(kind=real32)inValue.
statinteger(kind=int32)outoptionalStatus.

Call graph

save_pref_real64 ​

Keep the preference key: a real (as save_pref of a text, written with 17 significant digits: read back exactly).

Attributes: recursive

fortran
subroutine save_pref_real64(self, key, value, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
keycharacter(len=*)inKey.
valuereal(kind=real64)inValue.
statinteger(kind=int32)outoptionalStatus.

Call graph

save_pref_logical ​

Keep the preference key: a logical (as save_pref of a text, written true or false).

Attributes: recursive

fortran
subroutine save_pref_logical(self, key, value, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
keycharacter(len=*)inKey.
valuelogicalinValue.
statinteger(kind=int32)outoptionalStatus.

Call graph

set_size_limits ​

The least and the greatest size the user can give the window [logical pixels, as init's]; 0, or an absent maximum: no limit. Window mode; in headless and remote modes it does nothing (the display is the test's or the browser's). Statuses: FIG_ERR_ARGUMENT for a negative size or a maximum below its minimum, FIG_ERR_FAILED if the system refuses, FIG_ERR_STATE before init* or from a task.

Attributes: recursive

fortran
subroutine set_size_limits(self, min_width, min_height, max_width, max_height, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
min_widthinteger(kind=int32)inLeast width [logical pixels].
min_heightinteger(kind=int32)inLeast height [logical pixels].
max_widthinteger(kind=int32)inoptionalGreatest width [logical pixels] (default: none).
max_heightinteger(kind=int32)inoptionalGreatest height [logical pixels] (default: none).
statinteger(kind=int32)outoptionalStatus.

Call graph

destroy ​

Close the window and destroy the contexts (safe in any state).

Attributes: recursive

fortran
subroutine destroy(self)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.

Call graph

show_dialog ​

The system's dialog of kind (0 open, 1 save, 2 folder) or, with prefer='figure', FIGURE's browser of that kind.

Attributes: recursive

fortran
subroutine show_dialog(kind, who, id, filters, default_path, prefer, stat)

Arguments

NameTypeIntentAttributesDescription
kindinteger(kind=c_int)inKind.
whocharacter(len=*)inThe entry point, for messages.
idcharacter(len=*)inDialog id.
filterscharacter(len=*)inoptional'name|pattern' entries.
default_pathcharacter(len=*)inoptionalWhere to start.
prefercharacter(len=*)inoptional'system' or 'figure'.
statinteger(kind=int32)outoptionalStatus.

Call graph

show_file_dialog ​

Open a native file dialog of kind (0 open, 1 save, 2 folder).

fortran
subroutine show_file_dialog(kind, id, filters, default_path, stat)

Arguments

NameTypeIntentAttributesDescription
kindinteger(kind=c_int)inKind.
idcharacter(len=*)inDialog id.
filterscharacter(len=*)inoptional'name|pattern' entries.
default_pathcharacter(len=*)inoptionalWhere to start.
statinteger(kind=int32)outoptionalStatus.

Call graph

show_file_browser ​

Open FIGURE's file browser of kind (0 open, 1 save, 2 folder).

fortran
subroutine show_file_browser(kind, id, filters, default_path, stat)

Arguments

NameTypeIntentAttributesDescription
kindinteger(kind=c_int)inKind.
idcharacter(len=*)inDialog id.
filterscharacter(len=*)inoptional'name|pattern' entries.
default_pathcharacter(len=*)inoptionalWhere to start.
statinteger(kind=int32)outoptionalStatus.

Call graph

Functions ​

frame_options ​

Give the frame options to the native layer, before init: FIG_ERR_ARGUMENT for an unknown value.

Returns: integer(kind=c_int)

fortran
function frame_options(decorations, buttons) result(status)

Arguments

NameTypeIntentAttributesDescription
decorationscharacter(len=*)inoptional'native' or 'figure'.
buttonscharacter(len=*)inoptional'right' or 'left'.

Call graph

next_frame ​

Render the open frame (if any), then process input and open the next; .false. when the user quits. The usage errors of the frame just ended (a wrong end, a scope left open, a drawing call with no frame open: set_checks) are reported here: FIG_ERR_STATE with every message, one per line, in figure_last_error; the scopes left open have been closed and the next frame is open, so the loop can go on. In mode 'recover' they are shown in a notification instead and the status is FIG_OK. See errors.md, "Pairing and frames".

Attributes: recursive

Returns: logical

fortran
function next_frame(self, stat) result(running)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
statinteger(kind=int32)outoptionalStatus.

Call graph

quit_requested ​

The user asked to quit (the window's close button) since the last call: true once per request. Only with set_confirm_quit(.true.); otherwise the request ends next_frame at once. Callable from any thread (a task included): one caller gets each request.

Attributes: recursive

Returns: logical

fortran
function quit_requested(self) result(requested)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.

Call graph

dropped ​

The files and folders dropped on the window since the last frame (SDL's drop events), and where: true on the frame after the drop only, with paths the absolute paths (UTF-8, blank-padded to the longest; folders as folders, without a trailing separator) and (x, y) the point of the drop [pixels], the coordinates of ig_item_rect and of the mouse, so that the program can tell which window or region received it. Several files dropped at once come together, at one point. False, with paths empty, on every other frame; also before init* and from a task. Window mode: the system's drag and drop; headless mode: only the drops of test_drop; remote mode: none (a browser gives a page the dropped files' contents, not paths on the server: the page refuses them), but those of test_drop. Status: FIG_ERR_STATE before init* and from a task (a task does not draw: the task's status becomes FIG_ERR_STATE too); without stat, the result is .false. and nothing stops.

Attributes: recursive

Returns: logical

fortran
function dropped(self, paths, x, y, stat) result(any_dropped)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.
pathscharacter(len=:)outallocatablePaths dropped.
xreal(kind=real64)outoptionalAbscissa of the drop [pixels].
yreal(kind=real64)outoptionalOrdinate of the drop [pixels].
statinteger(kind=int32)outoptionalStatus.

Call graph

title ​

The window's title: the one given to init or the last set_title ('' before init, and in headless and remote modes until set_title).

Attributes: recursive

Returns: character(len=:)

fortran
function title(self) result(text)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.

Call graph

window_visible ​

True while the registered window name is shown: draw it (ig_begin/ig_end) only then. Hidden by its close button, by the View menu, by a layout that does not show it, or by set_window_visible. Statuses: FIG_ERR_ARGUMENT for a name not added (.false.), FIG_ERR_STATE from a task.

Attributes: recursive

Returns: logical

fortran
function window_visible(self, name, stat) result(visible)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.
namecharacter(len=*)inWindow name.
statinteger(kind=int32)outoptionalStatus.

Call graph

layout ​

The current layout's name ('' before the first add_layout): the one to build when ig_dock_layout_begin returns true. '' from a task.

Attributes: recursive

Returns: character(len=:)

fortran
function layout(self) result(name)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.

Call graph

prefs_file ​

The file open_prefs keeps the preferences in ('' before it, in memory only, or from a task).

Attributes: recursive

Returns: character(len=:)

fortran
function prefs_file(self) result(path)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.

Call graph

real_text ​

The shortest text of value that reads back to it: scientific notation with 1 to digits + 1 significant digits, its exponent without padding (7.0E-1, 1.0000000000000001E-1); Infinity, NaN as written. With value_32, read back as a 32-bit real.

Attributes: recursive

Returns: character(len=:)

fortran
function real_text(value, digits, value_32) result(text)

Arguments

NameTypeIntentAttributesDescription
valuereal(kind=real64)inValue.
digitsinteger(kind=int32)inMost digits after the point.
value_32real(kind=real32)inoptionalThe 32-bit value, when it is one.

Call graph

pref_text ​

The text of the preference key, and whether it is kept.

Attributes: recursive

Returns: character(len=:)

fortran
function pref_text(key, found, stat) result(text)

Arguments

NameTypeIntentAttributesDescription
keycharacter(len=*)inKey.
foundlogicaloutKept.
statinteger(kind=int32)outoptionalStatus.

Call graph

load_pref_text ​

The preference key into value: true when it is kept (value takes it, blank-padded or cut to its length); false when it is not, and value takes default if present, else stays as it is. Statuses: as save_pref's.

Attributes: recursive

Returns: logical

fortran
function load_pref_text(self, key, value, default, stat) result(found)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.
keycharacter(len=*)inKey.
valuecharacter(len=*)inoutValue.
defaultcharacter(len=*)inoptionalValue when not kept.
statinteger(kind=int32)outoptionalStatus.

Call graph

load_pref_int32 ​

The preference key into value as an integer: true when it is kept and is one; otherwise false, and value takes default if present, else stays as it is (a text edited into something else counts as not kept).

Attributes: recursive

Returns: logical

fortran
function load_pref_int32(self, key, value, default, stat) result(found)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.
keycharacter(len=*)inKey.
valueinteger(kind=int32)inoutValue.
defaultinteger(kind=int32)inoptionalValue when not kept.
statinteger(kind=int32)outoptionalStatus.

Call graph

load_pref_int64 ​

The preference key into value as a 64-bit integer: as load_pref of an integer.

Attributes: recursive

Returns: logical

fortran
function load_pref_int64(self, key, value, default, stat) result(found)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.
keycharacter(len=*)inKey.
valueinteger(kind=int64)inoutValue.
defaultinteger(kind=int64)inoptionalValue when not kept.
statinteger(kind=int32)outoptionalStatus.

Call graph

load_pref_real32 ​

The preference key into value as a real: as load_pref of an integer.

Attributes: recursive

Returns: logical

fortran
function load_pref_real32(self, key, value, default, stat) result(found)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.
keycharacter(len=*)inKey.
valuereal(kind=real32)inoutValue.
defaultreal(kind=real32)inoptionalValue when not kept.
statinteger(kind=int32)outoptionalStatus.

Call graph

load_pref_real64 ​

The preference key into value as a real: as load_pref of an integer.

Attributes: recursive

Returns: logical

fortran
function load_pref_real64(self, key, value, default, stat) result(found)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.
keycharacter(len=*)inKey.
valuereal(kind=real64)inoutValue.
defaultreal(kind=real64)inoptionalValue when not kept.
statinteger(kind=int32)outoptionalStatus.

Call graph

load_pref_logical ​

The preference key into value as a logical (true or false): as load_pref of an integer.

Attributes: recursive

Returns: logical

fortran
function load_pref_logical(self, key, value, default, stat) result(found)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.
keycharacter(len=*)inKey.
valuelogicalinoutValue.
defaultlogicalinoptionalValue when not kept.
statinteger(kind=int32)outoptionalStatus.

Call graph

message_box ​

Ask the user in a box: a modal drawn by FIGURE after the program's windows, centred, with title, text (wrapped) and a row of buttons (default 'OK'). Polled: call it every frame while waiting (a call opens the box id if it is not open; the texts of later calls replace its own): 0 while the box is open, then once the number of the button chosen (from 1), after which the box is gone and the id free. The box stays open until answered, called or not. Enter chooses the first button, Escape the last. Several boxes at once: each opened over the ones before, the newest on top, answered from the top down. A box waits, not drawn, while a popup of the program's (a menu, a modal, a file browser) is open: Dear ImGui keeps one popup per level. Statuses: FIG_ERR_ARGUMENT for an empty id or every button label empty, FIG_ERR_STATE before init* or from a task. The same in every mode.

Attributes: recursive

Returns: integer(kind=int32)

fortran
function message_box(self, id, title, text, buttons, stat) result(answer)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inoutApplication.
idcharacter(len=*)inId (any text: the box's own).
titlecharacter(len=*)inTitle.
textcharacter(len=*)inText (UTF-8).
buttonscharacter(len=*)inoptionalButton labels (blank-padded; default 'OK').
statinteger(kind=int32)outoptionalStatus.

Call graph

content_scale ​

Display content scale (1 standard, 2 on most high-DPI displays). Callable from any thread (a task included).

Attributes: recursive

Returns: real(kind=real64)

fortran
function content_scale(self) result(scale)

Arguments

NameTypeIntentAttributesDescription
selfclass(app_object)inApplication.

Call graph

opt ​

An optional string, or '' when absent (the native layer takes a length of 0 as not given).

Attributes: pure

Returns: character(len=:)

fortran
function opt(s) result(v)

Arguments

NameTypeIntentAttributesDescription
scharacter(len=*)inoptionalString.

Call graph

flag ​

An optional logical as 0 or 1, default when absent.

Attributes: pure

Returns: integer(kind=c_int)

fortran
function flag(value, default) result(f)

Arguments

NameTypeIntentAttributesDescription
valuelogicalinoptionalValue.
defaultlogicalinValue when absent.

Call graph

opt_len ​

The length of an optional name without its trailing blanks (a padded array's element), 0 when absent.

Attributes: pure

Returns: integer(kind=c_int)

fortran
function opt_len(s) result(n)

Arguments

NameTypeIntentAttributesDescription
scharacter(len=*)inoptionalString.

Call graph

Released under the MIT licence.