figure_app
figure_app, the application: window, frame loop and lazy redraw.
The whole life of a FIGURE program is one loop:
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
- app_object
- init
- init_headless
- set_icon_image
- set_icon_glyph
- init_remote
- set_checks
- set_lazy
- set_style
- palette_color
- notify
- notifications
- set_font
- add_fallback_font
- load_style
- save_style
- set_docking
- request_frames
- wake
- set_confirm_quit
- quit
- set_title
- open_file_dialog
- save_file_dialog
- open_folder_dialog
- open_file_browser
- save_file_browser
- file_dialog_result
- save_image
- image_result
- save_layout
- load_layout
- add_window
- set_window_visible
- view_menu
- add_layout
- switch_layout
- reset_layout
- open_prefs
- save_pref_text
- save_pref_int32
- save_pref_int64
- save_pref_real32
- save_pref_real64
- save_pref_logical
- set_size_limits
- destroy
- show_dialog
- show_file_dialog
- show_file_browser
- frame_options
- next_frame
- quit_requested
- dropped
- title
- window_visible
- layout
- prefs_file
- real_text
- pref_text
- load_pref_text
- load_pref_int32
- load_pref_int64
- load_pref_real32
- load_pref_real64
- load_pref_logical
- message_box
- content_scale
- opt
- flag
- opt_len
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
| Name | Type | Attributes | Description |
|---|---|---|---|
in_frame | logical | A frame is open. |
Type-Bound Procedures
| Name | Attributes | Description |
|---|---|---|
init | pass(self) | Open the window. |
init_headless | pass(self) | Contexts only, no window (tests). |
init_remote | pass(self) | The UI in a web browser (no window, display or GPU). |
next_frame | pass(self) | Close the current frame, open the next; false on quit. |
set_checks | pass(self) | What a usage error does: 'abort', 'report' (default), 'recover'. |
set_lazy | pass(self) | Lazy redraw on/off, longest sleep. |
set_style | pass(self) | The style: a name, or a look and a palette. |
palette_color | pass(self) | The colour of a palette role in effect. |
set_docking | pass(self) | Docking on (the default) or off. |
set_font | pass(self) | The default font and its size. |
add_fallback_font | pass(self) | A font for the glyphs the text fonts lack. |
load_style | pass(self) | A theme file. |
save_style | pass(self) | The style in effect, as a theme file. |
request_frames | pass(self) | Redraw without waiting for input. |
wake | pass(self) | Start the next frame at once (from any thread). |
set_confirm_quit | pass(self) | Report a quit request instead of quitting. |
quit_requested | pass(self) | The user asked to quit (once per request). |
dropped | pass(self) | The files and folders dropped on the window this frame. |
quit | pass(self) | End the loop at the next frame. |
set_title | pass(self) | The window's title, after init. |
title | pass(self) | The window's title. |
open_file_dialog | pass(self) | The system's dialog to choose a file to open. |
save_file_dialog | pass(self) | The system's dialog to choose where to save. |
open_folder_dialog | pass(self) | The system's dialog to choose a folder. |
open_file_browser | pass(self) | FIGURE's browser to choose a file (or a folder) to open. |
save_file_browser | pass(self) | FIGURE's browser to choose where to save. |
file_dialog_result | pass(self) | The answer to a dialog or a browser, once given. |
save_image | pass(self) | A rectangle of the window as a PNG file, after this frame. |
image_result | pass(self) | The outcome of save_image, once. |
save_layout | pass(self) | The arrangement of the windows (docking included) to a file. |
load_layout | pass(self) | An arrangement from a file, applied before the next frame. |
notify | pass(self) | Tell the user something, in a notification. |
notifications | pass(self) | The notifications kept (the last 100). |
add_window | pass(self) | Register a window: the View menu, its close button, kept hidden. |
window_visible | pass(self) | A registered window is shown. |
set_window_visible | pass(self) | Show or hide a registered window. |
view_menu | pass(self) | The View menu: the windows, the layouts, Reset layout. |
add_layout | pass(self) | Declare a named layout. |
switch_layout | pass(self) | Make a layout current: laid out again, or as the user left it. |
reset_layout | pass(self) | Lay the current layout out again. |
layout | pass(self) | The current layout's name: the one to build. |
open_prefs | pass(self) | Read the preferences from the program's file, kept there from now on. |
prefs_file | pass(self) | The preferences' file. |
save_pref_logical | pass(self) | Keep the preference key: a logical (as save_pref of a text, written true or false). |
save_pref_real64 | pass(self) | Keep the preference key: a real (as save_pref of a text, written with 17 significant digits: read back exactly). |
save_pref_real32 | pass(self) | Keep the preference key: a real (as save_pref of a text, written with 9 significant digits: read back exactly). |
save_pref_int64 | pass(self) | Keep the preference key: a 64-bit integer (as save_pref of a text, written in decimal). |
save_pref_int32 | pass(self) | Keep the preference key: an integer (as save_pref of a text, written in decimal). |
save_pref_text | pass(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_pref | Keep a preference. Generic: save_pref_text, save_pref_int32, save_pref_int64 | |
save_pref | Keep a preference. Generic: save_pref_real32, save_pref_real64, save_pref_logical | |
load_pref_logical | pass(self) | The preference key into value as a logical (true or false): as load_pref of an integer. |
load_pref_real64 | pass(self) | The preference key into value as a real: as load_pref of an integer. |
load_pref_real32 | pass(self) | The preference key into value as a real: as load_pref of an integer. |
load_pref_int64 | pass(self) | The preference key into value as a 64-bit integer: as load_pref of an integer. |
load_pref_int32 | pass(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_text | pass(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_pref | A preference kept, or a default. Generic: load_pref_text, load_pref_int32, load_pref_int64 | |
load_pref | A preference kept, or a default. Generic: load_pref_real32, load_pref_real64, load_pref_logical | |
message_box | pass(self) | A question in a box: 0 while open, then the button chosen. |
set_size_limits | pass(self) | The window's least and greatest size. |
content_scale | pass(self) | Display content scale. |
destroy | pass(self) | Close everything. |
set_icon_image | pass(self) | The window's icon from an image. |
set_icon_glyph | pass(self) | The window's icon from an ICON_*. |
set_icon | The 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
subroutine init(self, title, width, height, vsync, stat, ini_file, decorations, buttons)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
title | character(len=*) | in | Window title. | |
width | integer(kind=int32) | in | Width [logical pixels]. | |
height | integer(kind=int32) | in | Height [logical pixels]. | |
vsync | logical | in | optional | Synchronize with the display (default true). |
stat | integer(kind=int32) | out | optional | FIG_ERR_ARGUMENT for a wrong size or option. |
ini_file | character(len=*) | in | optional | File keeping the window layout (default: none). |
decorations | character(len=*) | in | optional | The window's frame: 'native' (default) or 'figure'. |
buttons | character(len=*) | in | optional | With '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
subroutine init_headless(self, width, height, stat, decorations, buttons)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
width | integer(kind=int32) | in | Width [pixels]. | |
height | integer(kind=int32) | in | Height [pixels]. | |
stat | integer(kind=int32) | out | optional | Status: FIG_ERR_ARGUMENT for a wrong size or option. |
decorations | character(len=*) | in | optional | 'native' (default: no bar) or 'figure'. |
buttons | character(len=*) | in | optional | With '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
subroutine set_icon_image(self, image, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
image | integer(kind=int8) | in | contiguous, target | Pixels. |
stat | integer(kind=int32) | out | optional | modes, 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
subroutine set_icon_glyph(self, icon, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
icon | character(len=*) | in | One ICON_* constant. | |
stat | integer(kind=int32) | out | optional | FIG_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
subroutine init_remote(self, port, host, width, height, port_used, quiet, max_fps, compress, lossy, token, url, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
port | integer(kind=int32) | in | optional | Port (default 8080; 0: any free port). |
host | character(len=*) | in | optional | Address to listen on (default 127.0.0.1). |
width | integer(kind=int32) | in | optional | Display width until the browser's [pixels] (default 1280). |
height | integer(kind=int32) | in | optional | Display height until the browser's [pixels] (default 800). |
port_used | integer(kind=int32) | out | optional | The port listened on (useful with port 0). |
quiet | logical | in | optional | Do not print the address to open (default false). |
max_fps | real(kind=real64) | in | optional | Most frames per second (default 60; 0: no cap). |
compress | character(len=*) | in | optional | Deflate frames and textures: 'auto', 'always', 'never'. |
lossy | logical | in | optional | Changing images as JPEG, exact when still (default true). |
token | character(len=*) | in | optional | Access token (default: random; '': none). |
url | character(len=*) | out | optional | The address to open, with the token (blank-padded). |
stat | integer(kind=int32) | out | optional | Status. |
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 atnext_framefor 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 nextnext_framereturnsFIG_ERR_STATEwith every message (without itsstat:error stop, as any failure);'recover': as'report', but an end whose scope is open further down first closes the scopes opened after it, andnext_frameshows the messages in a notification (figure_last_errorhas them) and returnsFIG_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
subroutine set_checks(self, mode, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
mode | character(len=*) | in | 'abort', 'report' or 'recover'. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine set_lazy(self, enabled, max_wait)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
enabled | logical | in | Lazy redraw on. | |
max_wait | real(kind=real64) | in | optional | Longest 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
subroutine set_style(self, name, lines, stat, look, palette, auto_dark, auto_light)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
name | character(len=*) | in | optional | Style name. |
lines | character(len=*) | in | optional | Line palette: 'okabe-ito' (default: the style's own). |
stat | integer(kind=int32) | out | optional | palette, a palette below the contrast rule, or no argument. |
look | character(len=*) | in | optional | Look: the geometry (rounding, padding, spacing, borders). |
palette | character(len=*) | in | optional | Palette: the colours, or 'auto'. |
auto_dark | character(len=*) | in | optional | Palette of 'auto' on a dark system (default 'seal'). |
auto_light | character(len=*) | in | optional | Palette 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
subroutine palette_color(self, role, rgba, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
role | character(len=*) | in | Role name. | |
rgba | real(kind=real64) | out | Colour, components in [0, 1]. | |
stat | integer(kind=int32) | out | optional | Status: 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
subroutine notify(self, text, kind, seconds, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
text | character(len=*) | in | What to tell (UTF-8; wrapped). | |
kind | character(len=*) | in | optional | 'info', 'success', 'warning' or 'error'. |
seconds | real(kind=real64) | in | optional | Time shown [s] (default 5; <= 0: until clicked). |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine notifications(self, list, kinds, shown)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. | |
list | character(len=:) | out | allocatable | Texts. |
kinds | character(len=7) | out | allocatable, optional | Kinds. |
shown | logical | out | allocatable, optional | Still 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
subroutine set_font(self, font, size, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
font | character(len=*) | in | Font. | |
size | real(kind=real64) | in | optional | Size [logical pixels], in (0, 200]. |
stat | integer(kind=int32) | out | optional | FIG_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
subroutine add_fallback_font(self, file, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
file | character(len=*) | in | TrueType/OpenType file. | |
stat | integer(kind=int32) | out | optional | FIG_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
subroutine load_style(self, file, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
file | character(len=*) | in | Theme file. | |
stat | integer(kind=int32) | out | optional | malformed (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
subroutine save_style(self, file, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
file | character(len=*) | in | Theme file to write. | |
stat | integer(kind=int32) | out | optional |
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
subroutine set_docking(self, enabled, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
enabled | logical | in | Docking on. | |
stat | integer(kind=int32) | out | optional |
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
subroutine request_frames(self, n)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
n | integer(kind=int32) | in | Frames. |
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
subroutine wake(self)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. |
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
subroutine set_confirm_quit(self, enabled)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
enabled | logical | in | Ask 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
subroutine quit(self)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. |
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
subroutine set_title(self, text, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
text | character(len=*) | in | Title. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine open_file_dialog(self, id, filters, default_path, stat, prefer)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
id | character(len=*) | in | Dialog id (any text, used to read the answer). | |
filters | character(len=*) | in | optional | File type filters. |
default_path | character(len=*) | in | optional | Folder or file to start from (relative: to the working directory; absent: that directory). |
stat | integer(kind=int32) | out | optional | Status. |
prefer | character(len=*) | in | optional | '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
subroutine save_file_dialog(self, id, filters, default_path, stat, prefer)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
id | character(len=*) | in | Dialog id. | |
filters | character(len=*) | in | optional | File type filters. |
default_path | character(len=*) | in | optional | Folder or file to start from (relative: to the working directory; absent: that directory). |
stat | integer(kind=int32) | out | optional | Status. |
prefer | character(len=*) | in | optional | '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
subroutine open_folder_dialog(self, id, default_path, stat, prefer)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
id | character(len=*) | in | Dialog id. | |
default_path | character(len=*) | in | optional | Folder to start from (relative: to the working directory; absent: that directory). |
stat | integer(kind=int32) | out | optional | Status. |
prefer | character(len=*) | in | optional | '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
subroutine open_file_browser(self, id, filters, default_path, folders, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
id | character(len=*) | in | Dialog id (any text, used to read the answer). | |
filters | character(len=*) | in | optional | File type filters, 'name|pattern' (the first in effect). |
default_path | character(len=*) | in | optional | Folder to start in, or a file (its folder; the file selected); relative: to the working directory (absent: that directory). |
folders | logical | in | optional | Choose a folder instead of a file (default false). |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine save_file_browser(self, id, filters, default_path, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
id | character(len=*) | in | Dialog id. | |
filters | character(len=*) | in | optional | File type filters, 'name|pattern'. |
default_path | character(len=*) | in | optional | Folder to start in, or the file to propose. |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine file_dialog_result(self, id, path, done, cancelled, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
id | character(len=*) | in | Dialog id. | |
path | character(len=:) | out | allocatable | Chosen path ('' while open or if cancelled). |
done | logical | out | The dialog was answered. | |
cancelled | logical | out | optional | The user cancelled it. |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine save_image(self, path, xmin, ymin, xmax, ymax, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
path | character(len=*) | in | PNG file. | |
xmin | real(kind=real64) | in | Left. | |
ymin | real(kind=real64) | in | Top. | |
xmax | real(kind=real64) | in | Right. | |
ymax | real(kind=real64) | in | Bottom. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine image_result(self, path, done, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
path | character(len=:) | out | allocatable | The file ('' until done). |
done | logical | out | Written, or failed. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine save_layout(self, path, comment, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
path | character(len=*) | in | File. | |
comment | character(len=*) | in | optional | Lines to keep with it. |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine load_layout(self, path, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
path | character(len=*) | in | File. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine add_window(self, name, visible, closable, in_view_menu, remember, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
name | character(len=*) | in | Window name, as given to ig_begin. | |
visible | logical | in | optional | Shown at the first run (default true). |
closable | logical | in | optional | A close button (default true). |
in_view_menu | logical | in | optional | Listed in the View menu (default true). |
remember | logical | in | optional | Shown or hidden as at the end of the last run (default true). |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine set_window_visible(self, name, visible, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
name | character(len=*) | in | Window name. | |
visible | logical | in | Shown. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine view_menu(self, label, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
label | character(len=*) | in | optional | The menu's label (default 'View'). |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine add_layout(self, name, windows, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
name | character(len=*) | in | Layout name (shown in the View menu). | |
windows | character(len=*) | in | optional | The registered windows it shows (blank-padded). |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine switch_layout(self, name, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
name | character(len=*) | in | Layout name. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine reset_layout(self, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine open_prefs(self, name, file, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
name | character(len=*) | in | The program's name: its folder of preferences. | |
file | character(len=*) | in | optional | The file instead (relative: to the working directory). |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine save_pref_text(self, key, value, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
key | character(len=*) | in | Key. | |
value | character(len=*) | in | Value. | |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
save_pref_int32
Keep the preference key: an integer (as save_pref of a text, written in decimal).
Attributes: recursive
subroutine save_pref_int32(self, key, value, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
key | character(len=*) | in | Key. | |
value | integer(kind=int32) | in | Value. | |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
save_pref_int64
Keep the preference key: a 64-bit integer (as save_pref of a text, written in decimal).
Attributes: recursive
subroutine save_pref_int64(self, key, value, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
key | character(len=*) | in | Key. | |
value | integer(kind=int64) | in | Value. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine save_pref_real32(self, key, value, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
key | character(len=*) | in | Key. | |
value | real(kind=real32) | in | Value. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine save_pref_real64(self, key, value, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
key | character(len=*) | in | Key. | |
value | real(kind=real64) | in | Value. | |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
save_pref_logical
Keep the preference key: a logical (as save_pref of a text, written true or false).
Attributes: recursive
subroutine save_pref_logical(self, key, value, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
key | character(len=*) | in | Key. | |
value | logical | in | Value. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine set_size_limits(self, min_width, min_height, max_width, max_height, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
min_width | integer(kind=int32) | in | Least width [logical pixels]. | |
min_height | integer(kind=int32) | in | Least height [logical pixels]. | |
max_width | integer(kind=int32) | in | optional | Greatest width [logical pixels] (default: none). |
max_height | integer(kind=int32) | in | optional | Greatest height [logical pixels] (default: none). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
destroy
Close the window and destroy the contexts (safe in any state).
Attributes: recursive
subroutine destroy(self)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. |
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
subroutine show_dialog(kind, who, id, filters, default_path, prefer, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
kind | integer(kind=c_int) | in | Kind. | |
who | character(len=*) | in | The entry point, for messages. | |
id | character(len=*) | in | Dialog id. | |
filters | character(len=*) | in | optional | 'name|pattern' entries. |
default_path | character(len=*) | in | optional | Where to start. |
prefer | character(len=*) | in | optional | 'system' or 'figure'. |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
show_file_dialog
Open a native file dialog of kind (0 open, 1 save, 2 folder).
subroutine show_file_dialog(kind, id, filters, default_path, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
kind | integer(kind=c_int) | in | Kind. | |
id | character(len=*) | in | Dialog id. | |
filters | character(len=*) | in | optional | 'name|pattern' entries. |
default_path | character(len=*) | in | optional | Where to start. |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
show_file_browser
Open FIGURE's file browser of kind (0 open, 1 save, 2 folder).
subroutine show_file_browser(kind, id, filters, default_path, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
kind | integer(kind=c_int) | in | Kind. | |
id | character(len=*) | in | Dialog id. | |
filters | character(len=*) | in | optional | 'name|pattern' entries. |
default_path | character(len=*) | in | optional | Where to start. |
stat | integer(kind=int32) | out | optional | Status. |
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)
function frame_options(decorations, buttons) result(status)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
decorations | character(len=*) | in | optional | 'native' or 'figure'. |
buttons | character(len=*) | in | optional | '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
function next_frame(self, stat) result(running)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
stat | integer(kind=int32) | out | optional | Status. |
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
function quit_requested(self) result(requested)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. |
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
function dropped(self, paths, x, y, stat) result(any_dropped)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. | |
paths | character(len=:) | out | allocatable | Paths dropped. |
x | real(kind=real64) | out | optional | Abscissa of the drop [pixels]. |
y | real(kind=real64) | out | optional | Ordinate of the drop [pixels]. |
stat | integer(kind=int32) | out | optional | Status. |
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=:)
function title(self) result(text)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. |
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
function window_visible(self, name, stat) result(visible)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. | |
name | character(len=*) | in | Window name. | |
stat | integer(kind=int32) | out | optional | Status. |
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=:)
function layout(self) result(name)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. |
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=:)
function prefs_file(self) result(path)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. |
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=:)
function real_text(value, digits, value_32) result(text)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
value | real(kind=real64) | in | Value. | |
digits | integer(kind=int32) | in | Most digits after the point. | |
value_32 | real(kind=real32) | in | optional | The 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=:)
function pref_text(key, found, stat) result(text)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
key | character(len=*) | in | Key. | |
found | logical | out | Kept. | |
stat | integer(kind=int32) | out | optional | Status. |
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
function load_pref_text(self, key, value, default, stat) result(found)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. | |
key | character(len=*) | in | Key. | |
value | character(len=*) | inout | Value. | |
default | character(len=*) | in | optional | Value when not kept. |
stat | integer(kind=int32) | out | optional | Status. |
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
function load_pref_int32(self, key, value, default, stat) result(found)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. | |
key | character(len=*) | in | Key. | |
value | integer(kind=int32) | inout | Value. | |
default | integer(kind=int32) | in | optional | Value when not kept. |
stat | integer(kind=int32) | out | optional | Status. |
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
function load_pref_int64(self, key, value, default, stat) result(found)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. | |
key | character(len=*) | in | Key. | |
value | integer(kind=int64) | inout | Value. | |
default | integer(kind=int64) | in | optional | Value when not kept. |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
load_pref_real32
The preference key into value as a real: as load_pref of an integer.
Attributes: recursive
Returns: logical
function load_pref_real32(self, key, value, default, stat) result(found)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. | |
key | character(len=*) | in | Key. | |
value | real(kind=real32) | inout | Value. | |
default | real(kind=real32) | in | optional | Value when not kept. |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
load_pref_real64
The preference key into value as a real: as load_pref of an integer.
Attributes: recursive
Returns: logical
function load_pref_real64(self, key, value, default, stat) result(found)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. | |
key | character(len=*) | in | Key. | |
value | real(kind=real64) | inout | Value. | |
default | real(kind=real64) | in | optional | Value when not kept. |
stat | integer(kind=int32) | out | optional | Status. |
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
function load_pref_logical(self, key, value, default, stat) result(found)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. | |
key | character(len=*) | in | Key. | |
value | logical | inout | Value. | |
default | logical | in | optional | Value when not kept. |
stat | integer(kind=int32) | out | optional | Status. |
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)
function message_box(self, id, title, text, buttons, stat) result(answer)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | inout | Application. | |
id | character(len=*) | in | Id (any text: the box's own). | |
title | character(len=*) | in | Title. | |
text | character(len=*) | in | Text (UTF-8). | |
buttons | character(len=*) | in | optional | Button labels (blank-padded; default 'OK'). |
stat | integer(kind=int32) | out | optional | Status. |
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)
function content_scale(self) result(scale)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(app_object) | in | Application. |
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=:)
function opt(s) result(v)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
s | character(len=*) | in | optional | String. |
Call graph
flag
An optional logical as 0 or 1, default when absent.
Attributes: pure
Returns: integer(kind=c_int)
function flag(value, default) result(f)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
value | logical | in | optional | Value. |
default | logical | in | Value 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)
function opt_len(s) result(n)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
s | character(len=*) | in | optional | String. |
Call graph