Skip to content

figure_imgui ​

figure_imgui, Dear ImGui widgets with Fortran arguments.

Every drawing procedure of this module refuses a call from a task (FIG_ERR_STATE): see processes.md; and a call with no frame open, a usage error (FIG_ERR_STATE, <procedure>: no frame open). Every begin/end and push/pop pair registers in the scope record of the frame, which checks each end before Dear ImGui sees it: a wrong end is refused and reported by app%next_frame (app%set_checks; errors.md, "Pairing and frames").

Immediate mode: call the widgets every frame; each returns what happened this frame (ig_button is true on the frame it is clicked, ig_checkbox is true when it changed the value). Values are ordinary Fortran variables, updated in place: no handles, no callbacks, no target requirements (the C bool* of a checkbox is a local copy, written back).

Source: src/lib/figure_imgui.F90

Dependencies

Contents ​

Derived Types ​

text_buffer_object ​

Text of any length, edited by ig_input_text_multiline: a file shown or edited as text, notes, a read-only view. The text is kept by FIGURE's native layer, which grows it while the user types or pastes (no capacity to choose, no copy per frame); set replaces it, text returns a copy. Lines end with LF (set turns CRLF into LF). Usable before init* and from a task (it draws nothing). Not to be copied: the copy would share the text, and the first of the two to end would take it away from the other.

Components

NameTypeAttributesDescription
idinteger(kind=c_int)Native handle (0: no text yet, an empty one).

Type-Bound Procedures

NameAttributesDescription
setpass(self)Replace the text.
textpass(self)A copy of the text.
lengthpass(self)Its length [bytes].

item_status_object ​

What happened to an item, as ig_last_item found it right after the item was drawn: a snapshot, a plain value the program keeps (later items do not change it). The event states (activated, edited, deactivated, deactivated_after_edit, toggled_open, clicked, double_clicked) are true on one frame only, the frame of the event; the others (hovered, active, focused, visible) last as long as the condition. Which widgets report which states: widgets.md, "What happened to an item".

Components

NameTypeAttributesDescription
hoveredlogicalThe pointer is over the item, and no other item is held.
activelogicalHeld (a button pressed, a slider dragged) or being edited.
focusedlogicalIt has the keyboard focus (keyboard navigation's cursor).
visiblelogicalNot clipped: inside its window or region's visible area.
activatedlogicalIt became active on this frame.
editedlogicalIt changed its value on this frame.
deactivatedlogicalIt stopped being active on this frame.
deactivated_after_editlogicalIt stopped being active on this frame, its value changed meanwhile.
toggled_openlogicalA tree node or header opened or closed on this frame.
clickedlogicalClicked on this frame, per button: left, right, middle.
double_clickedlogicalDouble-clicked on this frame, per button: left, right, middle.
rectreal(kind=real64)x, y (top left), width, height [pixels].

Interfaces ​

ig_em ​

A length of x em [pixels]: x times the current font size, so that a size given in lines of text follows the font and the display's scale.

Module procedures: ig_em_r64, ig_em_i32

Subroutines ​

ig_end ​

End the window opened by ig_begin or ig_begin_side_bar (whatever it returned). Refused (FIG_ERR_STATE, reported by app%next_frame) when the innermost open scope is not a window: errors.md, "Pairing and frames".

Attributes: recursive

fortran
subroutine ig_end()

Call graph

ig_set_next_window ​

Position (and size) of the next window [pixels]: on first use only, or every frame if always.

Attributes: recursive

fortran
subroutine ig_set_next_window(x, y, width, height, always)

Arguments

NameTypeIntentAttributesDescription
xreal(kind=real64)inLeft [pixels].
yreal(kind=real64)inTop [pixels].
widthreal(kind=real64)inoptionalWidth [pixels].
heightreal(kind=real64)inoptionalHeight [pixels].
alwayslogicalinoptionalEnforce every frame (default: first use only).

Call graph

ig_align_text_to_frame_padding ​

The text that follows on this line is lowered to the text of framed widgets (fields, buttons): a label or a value beside fields, in a table row of fields.

Attributes: recursive

fortran
subroutine ig_align_text_to_frame_padding()

Call graph

ig_set_clipboard ​

Put text (UTF-8, trailing blanks included: pass trim of a padded variable) on the clipboard, as a copy in a field does. Window mode: the system's clipboard (SDL's). Headless mode: a clipboard of the program's own. Remote mode: the program's own on the server, also written to the browser's clipboard where the browser allows it (a page reached as https or localhost, and in a few browsers only right after a click or a key). Status: FIG_ERR_STATE before init* or from a task (stat optional: absent, error stop with the message).

Attributes: recursive

fortran
subroutine ig_set_clipboard(text, stat)

Arguments

NameTypeIntentAttributesDescription
textcharacter(len=*)inText.
statinteger(kind=int32)outoptionalStatus.

Call graph

text_buffer_set ​

Replace the text with text (UTF-8, lines ended by LF or CRLF; trailing blanks are part of it: pass trim of a padded line). A field being edited shows the new text at once, its undo history kept. A NUL byte ends the text. Status: FIG_ERR_ARGUMENT for a text of 2 GiB or more (stat optional: absent, error stop with the message).

Attributes: recursive

fortran
subroutine text_buffer_set(self, text, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(text_buffer_object)inoutBuffer.
textcharacter(len=*)inNew text.
statinteger(kind=int32)outoptionalStatus.

Call graph

text_buffer_final ​

The buffer ends: its text is released.

Attributes: recursive

fortran
subroutine text_buffer_final(self)

Arguments

NameTypeIntentAttributesDescription
selftype(text_buffer_object)inoutBuffer.

Call graph

ig_tooltip ​

A tooltip on the previous widget: text shows while the pointer rests on it (after Dear ImGui's usual delay).

Attributes: recursive

fortran
subroutine ig_tooltip(text)

Arguments

NameTypeIntentAttributesDescription
textcharacter(len=*)inText.

Call graph

ig_end_tooltip ​

End a tooltip (only after ig_begin_tooltip or ig_begin_item_tooltip returned true). A wrong end (after a false begin, or with another scope innermost) is refused and reported (FIG_ERR_STATE; errors.md, "Pairing and frames").

Attributes: recursive

fortran
subroutine ig_end_tooltip()

Call graph

A link that opens url when clicked (Dear ImGui's TextLinkOpenURL): a window opens it with the system's handler (SDL_OpenURL: the browser, or the program a file's type is given to); remote mode sends it to the page, which opens it in a new tab of the browser (where the browser allows pop-ups); headless mode opens nothing (test_opened_url reads it). The pointer resting on it shows the URL; a right click offers "Copy Link". FIGURE does not check the URL: pass a link of your own, not text a user typed. No frame open or a task: refused (FIG_ERR_STATE).

Attributes: recursive

fortran
subroutine ig_text_link_url(label, url)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLabel (also its id).
urlcharacter(len=*)inThe address, e.g. 'https://...'.

Call graph

ig_set_next_item_width ​

Width of the next widget's field [pixels]; negative: up to that distance from the window's right edge.

Attributes: recursive

fortran
subroutine ig_set_next_item_width(width)

Arguments

NameTypeIntentAttributesDescription
widthreal(kind=real64)inWidth [pixels].

Call graph

ig_push_item_width ​

Width of the fields of every widget that follows in the current window [pixels] (Dear ImGui's PushItemWidth), until ig_pop_item_width; always paired, the pop in the same window and scope (a pop closes the innermost scope, as ig_pop_id). Negative: up to that distance from the right edge of the window or region; 0: the window's default. ig_set_next_item_width still sets the next widget's alone. No frame open or a task: nothing done (a usage error, reported by app%next_frame). The same in window, headless and remote mode.

Attributes: recursive

fortran
subroutine ig_push_item_width(width)

Arguments

NameTypeIntentAttributesDescription
widthreal(kind=real64)inWidth [pixels]; < 0: up to that distance from the right edge; 0: the default.

Call graph

ig_pop_item_width ​

Back to the width of the fields before the last ig_push_item_width (Dear ImGui's PopItemWidth).

Attributes: recursive

fortran
subroutine ig_pop_item_width()

Call graph

ig_text ​

Plain text (no formatting: compose it with Fortran internal writes).

Attributes: recursive

fortran
subroutine ig_text(text)

Arguments

NameTypeIntentAttributesDescription
textcharacter(len=*)inText.

Call graph

ig_same_line ​

Put the next item on the same line as the previous one; with offset, at that distance [pixels] from the window's left edge (aligned columns of labels and fields).

Attributes: recursive

fortran
subroutine ig_same_line(offset)

Arguments

NameTypeIntentAttributesDescription
offsetreal(kind=real64)inoptionalDistance from the window's left edge [pixels].

Call graph

ig_text_wrapped ​

Text wrapped at the right edge of the window or region (help text, long messages).

Attributes: recursive

fortran
subroutine ig_text_wrapped(text)

Arguments

NameTypeIntentAttributesDescription
textcharacter(len=*)inText.

Call graph

ig_text_disabled ​

Text in the style's disabled colour (a default value, a hint, something that does not apply).

Attributes: recursive

fortran
subroutine ig_text_disabled(text)

Arguments

NameTypeIntentAttributesDescription
textcharacter(len=*)inText.

Call graph

ig_text_colored ​

Text in color ([r, g, b] or [r, g, b, a] in [0, 1]); pair a colour with a mark or a word (an error marker), so that it does not rest on colour alone.

Attributes: recursive

fortran
subroutine ig_text_colored(text, color)

Arguments

NameTypeIntentAttributesDescription
textcharacter(len=*)inText.
colorreal(kind=real64)in[r, g, b] or [r, g, b, a].

Call graph

ig_progress_bar ​

A progress bar (ProgressBar), fraction of it filled, in [0, 1] (clamped); fraction < 0 gives an indeterminate bar, a band sliding along it (animated by FIGURE with the frame clock: draw it every frame). label is written over it (default: the percentage; none for an indeterminate bar); width [pixels] (default: the width left; negative: up to that distance from the right edge). The same in every mode.

Attributes: recursive

fortran
subroutine ig_progress_bar(fraction, label, width)

Arguments

NameTypeIntentAttributesDescription
fractionreal(kind=real64)inDone, in [0, 1]; < 0: indeterminate.
labelcharacter(len=*)inoptionalText over the bar.
widthreal(kind=real64)inoptionalWidth [pixels].

Call graph

ig_separator ​

Horizontal separator.

Attributes: recursive

fortran
subroutine ig_separator()

Call graph

ig_separator_text ​

A horizontal separator with label written in it, at its left (Dear ImGui's SeparatorText): the title of a part of a form. The text before ## is shown. No frame open or a task: nothing drawn (a usage error, reported by app%next_frame). The same in window, headless and remote mode.

Attributes: recursive

fortran
subroutine ig_separator_text(label)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inText of the separator.

Call graph

ig_available ​

The space left in the current window or region from where the next item goes [pixels] (Dear ImGui's GetContentRegionAvail): to the right edge of its content (width) and to its bottom (height); in a table cell, to the cell's right edge. A side bar or a child region drawn beside takes its width out of it. No frame open or a task: zeros (a usage error, reported by app%next_frame).

Attributes: recursive

fortran
subroutine ig_available(width, height)

Arguments

NameTypeIntentAttributesDescription
widthreal(kind=real64)outWidth left [pixels].
heightreal(kind=real64)outHeight left [pixels].

Call graph

ig_spacing ​

A vertical gap of the style's item spacing before the next item (Dear ImGui's Spacing).

Attributes: recursive

fortran
subroutine ig_spacing()

Call graph

ig_dummy ​

An empty item width x height pixels (Dear ImGui's Dummy): a gap of a given size, a place kept for something drawn later; it counts for ig_same_line, groups and the window's size like any item.

Attributes: recursive

fortran
subroutine ig_dummy(width, height)

Arguments

NameTypeIntentAttributesDescription
widthreal(kind=real64)inWidth [pixels].
heightreal(kind=real64)inHeight [pixels].

Call graph

ig_new_line ​

End the line (after ig_same_line), or add an empty line of text's height (Dear ImGui's NewLine).

Attributes: recursive

fortran
subroutine ig_new_line()

Call graph

ig_indent ​

Move the left edge of the lines that follow right by width pixels (default, or 0: the style's indent spacing), until ig_unindent with the same width (Dear ImGui's Indent). Not a scope: the program keeps the two balanced (a window's indent is reset when it begins).

Attributes: recursive

fortran
subroutine ig_indent(width)

Arguments

NameTypeIntentAttributesDescription
widthreal(kind=real64)inoptionalIndent [pixels] (default: the style's indent spacing).

Call graph

ig_unindent ​

Move the left edge of the lines that follow back left by width pixels (default, or 0: the style's indent spacing) (Dear ImGui's Unindent).

Attributes: recursive

fortran
subroutine ig_unindent(width)

Arguments

NameTypeIntentAttributesDescription
widthreal(kind=real64)inoptionalIndent removed [pixels] (default: the style's indent spacing).

Call graph

ig_show_demo_window ​

The Dear ImGui demo window (a live catalogue of every widget).

Attributes: recursive

fortran
subroutine ig_show_demo_window(open)

Arguments

NameTypeIntentAttributesDescription
openlogicalinoutoptionalWindow open (close button).

Call graph

ig_item_rect ​

Screen rectangle of the last item [pixels] (tests, custom layout).

Attributes: recursive

fortran
subroutine ig_item_rect(xmin, ymin, xmax, ymax)

Arguments

NameTypeIntentAttributesDescription
xminreal(kind=real64)outLeft.
yminreal(kind=real64)outTop.
xmaxreal(kind=real64)outRight.
ymaxreal(kind=real64)outBottom.

Call graph

ig_scroll_here ​

Scroll the current window or region so that the line drawn last (the last item's line) is at ratio of its visible height: 0 top, 0.5 centre (default), 1 bottom (Dear ImGui's SetScrollHereY; axis='x': SetScrollHereX, the last item at ratio of the visible width). Call it after the item, inside the window or region that scrolls. The scroll moves when that window or region is begun on the next frame: the item is in place one frame later. A ratio outside [0, 1] or an unknown axis: nothing done, FIG_ERR_ARGUMENT in stat (or error stop without it); no frame open or a task: FIG_ERR_STATE. The same in window, headless and remote mode.

Attributes: recursive

fortran
subroutine ig_scroll_here(ratio, axis, stat)

Arguments

NameTypeIntentAttributesDescription
ratioreal(kind=real64)inoptionalWhere the line goes, in [0, 1] of the visible height (width).
axischaracter(len=*)inoptional'y' (default) or 'x'.
statinteger(kind=int32)outoptionalStatus.

Call graph

ig_get_scroll ​

The scroll of the current window or region [pixels] (Dear ImGui's GetScrollY, GetScrollMaxY, GetScrollX, GetScrollMaxX): y from 0 (top) to ymax (bottom; 0: nothing to scroll), x from 0 (left) to xmax. The values of the last layout: a scroll asked for on this frame is not in them yet. No frame open or a task: zeros (a usage error, reported by app%next_frame). The same in window, headless and remote mode.

Attributes: recursive

fortran
subroutine ig_get_scroll(y, ymax, x, xmax)

Arguments

NameTypeIntentAttributesDescription
yreal(kind=real64)outVertical scroll [pixels].
ymaxreal(kind=real64)outLargest vertical scroll [pixels].
xreal(kind=real64)outoptionalHorizontal scroll [pixels].
xmaxreal(kind=real64)outoptionalLargest horizontal scroll [pixels].

Call graph

ig_set_scroll ​

Scroll the current window or region to y (and/or x) [pixels] (Dear ImGui's SetScrollY, SetScrollX): clamped to [0, the largest scroll] when applied, on the next frame (one frame late, as ig_scroll_here). An absent coordinate is left as it is. No frame open or a task: nothing done (a usage error, reported by app%next_frame). The same in window, headless and remote mode.

Attributes: recursive

fortran
subroutine ig_set_scroll(y, x)

Arguments

NameTypeIntentAttributesDescription
yreal(kind=real64)inoptionalVertical scroll [pixels].
xreal(kind=real64)inoptionalHorizontal scroll [pixels].

Call graph

ig_scroll_to_pos ​

Scroll the current window or region so that the point pos [pixels] of its content is at ratio of its visible height: 0 top, 0.5 centre (default), 1 bottom (Dear ImGui's SetScrollFromPosY; axis='x': SetScrollFromPosX and the width). pos is measured from the top (left) of the content, where its first item starts, whatever the scroll is now: row i of a list of rows h pixels apart starts at (i - 1) * h. It reaches a row that is not drawn on this frame (a list clipper's). Applied on the next frame, as ig_scroll_here. A ratio outside [0, 1] or an unknown axis: nothing done, FIG_ERR_ARGUMENT in stat (or error stop without it); no frame open or a task: FIG_ERR_STATE. The same in window, headless and remote mode.

Attributes: recursive

fortran
subroutine ig_scroll_to_pos(pos, ratio, axis, stat)

Arguments

NameTypeIntentAttributesDescription
posreal(kind=real64)inPoint of the content [pixels from its top (left)].
ratioreal(kind=real64)inoptionalWhere it goes, in [0, 1] of the visible height (width).
axischaracter(len=*)inoptional'y' (default) or 'x'.
statinteger(kind=int32)outoptionalStatus.

Call graph

ig_focus_here ​

Give the keyboard focus to the next item (Dear ImGui's SetKeyboardFocusHere): call it before the item, on one frame (the frame a dialog opens, a button asks for it), not on every frame. A text or number field is then edited as if clicked: typed keys go into it, from the next frame. offset 1 is the item after the next, 2 the one after that; -1 is the item drawn last. The window or region is scrolled to show the item. An offset below -1: nothing done, FIG_ERR_ARGUMENT in stat (or error stop without it); no frame open or a task: FIG_ERR_STATE. The same in window, headless and remote mode.

Attributes: recursive

fortran
subroutine ig_focus_here(offset, stat)

Arguments

NameTypeIntentAttributesDescription
offsetinteger(kind=int32)inoptionalWhich item: 0 the next (default), 1 the one after, -1 the last.
statinteger(kind=int32)outoptionalStatus.

Call graph

ig_default_focus ​

Make the item drawn last the one that has the keyboard focus when its window appears (Dear ImGui's SetItemDefaultFocus): a dialog's safe button, the field a form starts from. Call it after the item; it acts on the frame the window (a modal, a popup, a window opened by the program) appears, and does nothing on the others, so it may be called on every frame. The item is focused, not activated: enter or space presses it (keyboard navigation), a field is edited after enter. No frame open or a task: nothing done (a usage error, reported by app%next_frame). The same in window, headless and remote mode.

Attributes: recursive

fortran
subroutine ig_default_focus()

Call graph

ig_image ​

A texture, pixel row 1 at the top (screen and image-file convention), width x height pixels (default: the texture's size).

Attributes: recursive

fortran
subroutine ig_image(tex, width, height)

Arguments

NameTypeIntentAttributesDescription
textype(texture_object)inTexture.
widthreal(kind=real64)inoptionalWidth [pixels].
heightreal(kind=real64)inoptionalHeight [pixels].

Call graph

take_payload ​

The payload delivered last, n characters, into payload (reallocated).

Attributes: recursive

fortran
subroutine take_payload(n, payload)

Arguments

NameTypeIntentAttributesDescription
ninteger(kind=c_int)inIts length.
payloadcharacter(len=:)inoutallocatableThe payload.

Call graph

Functions ​

ig_begin ​

Begin a window; always pair with ig_end. With open, the window has a close button that sets it false. Without open, a window registered with app%add_window (closable, the default) has the close button, which hides it: app%window_visible(name) turns false. flags combine ImGuiWindowFlags_* with ior (NoTitleBar, NoResize, NoMove, AlwaysAutoResize, NoBackground, NoDecoration, NoDocking, ...).

Attributes: recursive

Returns: logical

fortran
function ig_begin(name, open, flags) result(visible)

Arguments

NameTypeIntentAttributesDescription
namecharacter(len=*)inWindow name (unique id and title).
openlogicalinoutoptionalWindow open.
flagsinteger(kind=int32)inoptionalImGuiWindowFlags_* (default none).

Call graph

ig_begin_side_bar ​

Begin a bar along one side of the display: a toolbar, a status bar. side is 'left', 'right', 'top' or 'bottom'; size its width (left, right) or height (top, bottom) [pixels]. It is a window without title bar, not movable, not resizable, not dockable, which the work area leaves out: a dock space (ig_dock_space) and the main menu bar's neighbours fill the rest. Declare it every frame, after the main menu bar and before the dock space; always pair with ig_end. An unknown side is taken as 'left'.

Attributes: recursive

Returns: logical

fortran
function ig_begin_side_bar(name, side, size) result(visible)

Arguments

NameTypeIntentAttributesDescription
namecharacter(len=*)inWindow name (unique id).
sidecharacter(len=*)inleft, right, top, bottom.
sizereal(kind=real64)inWidth or height [pixels].

Call graph

ig_focus_window ​

Bring window name forward and give it the keyboard (a docked window: its tab is shown). Not while a popup or a modal is open, since focusing another window would close it: then nothing happens and the result is false; ask again on a later frame. A window not drawn yet (this frame or before) is not found: ask after its ig_begin.

Attributes: recursive

Returns: logical

fortran
function ig_focus_window(name) result(focused)

Arguments

NameTypeIntentAttributesDescription
namecharacter(len=*)inWindow name (as given to ig_begin, or its ###id part).

Call graph

ig_button ​

A button; true on the frame it is clicked.

Attributes: recursive

Returns: logical

fortran
function ig_button(label, width, height) result(pressed)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLabel.
widthreal(kind=real64)inoptionalWidth [pixels] (default: fit the label).
heightreal(kind=real64)inoptionalHeight [pixels] (default: fit the label).

Call graph

ig_tool_button ​

A workspace button, as Fusion 360's: icon (an ICON_*) above label, larger than it, on a framed, rounded button that shades under the pointer. selected: framed and tinted in the accent colour, the icon drawn in it (accent[r, g, b] in [0, 1]; default: the style's CheckMark colour). width, height [pixels]: default as wide as the label (at least 4.6 font sizes) and tall enough for the icon (1.8 font sizes) above the label. The text before ## is shown, all of label is the id. True on the frame it is clicked; ig_tooltip and ig_item_rect apply to it as to any widget.

Attributes: recursive

Returns: logical

fortran
function ig_tool_button(label, icon, width, height, selected, accent) result(clicked)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLabel (also its id).
iconcharacter(len=*)inIcon (UTF-8: an ICON_* constant).
widthreal(kind=real64)inoptionalWidth [pixels].
heightreal(kind=real64)inoptionalHeight [pixels].
selectedlogicalinoptionalThe one shown (default false).
accentreal(kind=real64)inoptionalAccent colour.

Call graph

ig_text_size ​

The size a text takes in the current font [pixels]: width and height (the text before ## when it is a label): buttons of one width, a column as wide as its longest value.

Attributes: recursive

Returns: real(kind=real64)

fortran
function ig_text_size(text) result(extent)

Arguments

NameTypeIntentAttributesDescription
textcharacter(len=*)inText (UTF-8).

Call graph

ig_checkbox ​

A check box bound to value; true when the user toggled it.

Attributes: recursive

Returns: logical

fortran
function ig_checkbox(label, value) result(changed)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLabel.
valuelogicalinoutValue.

Call graph

ig_input_text ​

A text field bound to value; true when the user edited it. The text can be as long as value (its length is the field's capacity); trailing blanks are not part of the text (Fortran pads with them). hint is shown while the field is empty; flags combine ImGuiInputTextFlags_* with ior (CharsNoBlank, CharsDecimal, CharsScientific, ReadOnly, EnterReturnsTrue, ...).

Attributes: recursive

Returns: logical

fortran
function ig_input_text(label, value, hint, flags) result(changed)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLabel.
valuecharacter(len=*)inoutText.
hintcharacter(len=*)inoptionalShown while the field is empty.
flagsinteger(kind=int32)inoptionalImGuiInputTextFlags_* (default none).

Call graph

ig_input_text_multiline ​

A multi-line text field (InputTextMultiline) over buffer; true on the frame the user edited the text. Enter inserts a newline; the field scrolls when the text is longer than it. Keys (cmd for ctrl on macOS): ctrl+z undoes, ctrl+y or ctrl+shift+z redoes, ctrl+a selects all, ctrl+c, ctrl+x and ctrl+v copy, cut and paste. width, height [pixels]: absent or 0, the item width and 8 lines; negative, up to that distance from the region's right or bottom edge. read_only: the text can be selected and copied, not changed. tab_input: Tab inserts a tab character (default: it moves to the next widget). flags add ImGuiInputTextFlags_* with ior (WordWrap, NoUndoRedo, ...). The same in every mode; from a task it draws nothing and returns false (the task's status becomes FIG_ERR_STATE).

Attributes: recursive

Returns: logical

fortran
function ig_input_text_multiline(label, buffer, width, height, read_only, tab_input, flags) result(changed)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLabel ('##text': none shown).
buffertype(text_buffer_object)inoutThe text.
widthreal(kind=real64)inoptionalWidth [pixels].
heightreal(kind=real64)inoptionalHeight [pixels].
read_onlylogicalinoptionalSelection and copy only (default false).
tab_inputlogicalinoptionalTab inserts a tab (default false).
flagsinteger(kind=int32)inoptionalMore ImGuiInputTextFlags_* (default none).

Call graph

ig_get_clipboard ​

The clipboard's text (UTF-8), as a paste in a field reads it: the system's in window mode, the program's own in headless mode; in remote mode the program's own, which a paste in the page (ctrl+v, cmd+v) sets from the browser's clipboard first. '' before init*, for an empty clipboard, or from a task.

Attributes: recursive

Returns: character(len=:)

fortran
function ig_get_clipboard() result(text)

Call graph

text_buffer_text ​

A copy of the text ('' before any set or edit).

Attributes: recursive

Returns: character(len=:)

fortran
function text_buffer_text(self) result(text)

Arguments

NameTypeIntentAttributesDescription
selfclass(text_buffer_object)inBuffer.

Call graph

text_buffer_length ​

The length of the text [bytes] (UTF-8: a character outside ASCII takes 2 to 4).

Attributes: recursive

Returns: integer(kind=int64)

fortran
function text_buffer_length(self) result(length)

Arguments

NameTypeIntentAttributesDescription
selfclass(text_buffer_object)inBuffer.

Call graph

ig_color_edit ​

A colour editor (ColorEdit4) bound to rgba, components in [0, 1]: a swatch that opens a picker (a saturation-value square and a hue bar) when clicked, and one field per component, dragged or typed (0-255). A rgba of 3 components is RGB; of 4, RGBA, with the alpha shown unless alpha=.false. (then rgba(4) is left alone). True on the frames the user changes the colour; rgba is written only then (Dear ImGui edits single precision: an untouched colour keeps its double precision bits). Right-click on the swatch: Dear ImGui's options (RGB, HSV or hexadecimal fields, copy as text). Statuses: FIG_ERR_ARGUMENT for a size other than 3 or 4, FIG_ERR_STATE from a task. The same in every mode.

Attributes: recursive

Returns: logical

fortran
function ig_color_edit(label, rgba, alpha, stat) result(changed)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLabel (also the id; '##id' hides it).
rgbareal(kind=real64)inoutColour, RGB or RGBA in [0, 1].
alphalogicalinoptionalShow and edit the alpha (default: when size(rgba) is 4).
statinteger(kind=int32)outoptionalStatus.

Call graph

ig_color_picker ​

A colour picker drawn in place (ColorPicker4), bound to rgba, components in [0, 1]: a saturation-value square and a hue bar (or, wheel=.true., a hue wheel around a saturation-value triangle), an alpha bar for a rgba of 4 components, a preview of the colour, and below, unless inputs=.false., the fields of the components (RGB, HSV or hexadecimal). A rgba of 3 components is RGB; of 4, RGBA, with the alpha bar unless alpha=.false. (then rgba(4) is left alone). True on the frames the user changes the colour; rgba is written only then (Dear ImGui edits single precision). wheel absent: the hue bar, or the form the user chose in the picker's right-click menu; given, that form, the menu's choice ignored. The width is the item width (ig_push_item_width); the height follows it. Statuses: FIG_ERR_ARGUMENT for a size other than 3 or 4, FIG_ERR_STATE from a task. The same in every mode.

Attributes: recursive

Returns: logical

fortran
function ig_color_picker(label, rgba, alpha, wheel, inputs, stat) result(changed)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLabel (also the id; '##id' hides it).
rgbareal(kind=real64)inoutColour, RGB or RGBA in [0, 1].
alphalogicalinoptionalShow and edit the alpha (default: when size(rgba) is 4).
wheellogicalinoptionalA hue wheel and a triangle (.true.) or a hue bar (.false.).
inputslogicalinoptionalThe fields of the components below (default .true.).
statinteger(kind=int32)outoptionalStatus.

Call graph

ig_combo ​

A drop-down list of items; current is the index of the one chosen (1 to size(items); any other value shows none chosen). True on the frame the user picks an item (current is then its index).

Attributes: recursive

Returns: logical

fortran
function ig_combo(label, current, items) result(changed)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLabel.
currentinteger(kind=int32)inoutIndex of the chosen item.
itemscharacter(len=*)inItems (trailing blanks are not shown).

Call graph

ig_begin_tooltip ​

Begin a tooltip with any content (Dear ImGui's BeginTooltip): a window that follows the pointer, drawn this frame whatever is hovered; declare its content (text, a table, a plot), then ig_end_tooltip. Call it on the frames it must show, e.g. after ig_last_item() reported the item hovered. True in every frame (Dear ImGui's begin cannot fail today), but ig_end_tooltip only after true, as for every "after true" pair. No frame open or a task: false, refused (FIG_ERR_STATE). The same in window, headless and remote mode.

Attributes: recursive

Returns: logical

fortran
function ig_begin_tooltip() result(shown)

Call graph

ig_begin_item_tooltip ​

Begin a tooltip on the item drawn just before (Dear ImGui's BeginItemTooltip): true while the pointer rests on it, after Dear ImGui's tooltip delay (ig_tooltip's: still for 0.15 s, the style's HoverStationaryDelay, and hovered for 0.15 s, HoverDelayShort); declare the content, then ig_end_tooltip only after true. No frame open or a task: false, refused (FIG_ERR_STATE). The same in window, headless and remote mode.

Attributes: recursive

Returns: logical

fortran
function ig_begin_item_tooltip() result(shown)

Call graph

Text drawn as a link (Dear ImGui's TextLink: the style's TextLink colour, underlined, a hand pointer over it); true on the frame it is clicked. The text before ## is shown, all of label is the id. No frame open or a task: false, refused (FIG_ERR_STATE). The same in window, headless and remote mode.

Attributes: recursive

Returns: logical

fortran
function ig_text_link(label) result(clicked)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLabel (also its id).

Call graph

ig_selectable ​

A line of a list, highlighted when selected; true on the frame it is clicked (the program then updates what is selected: the line does not change selected itself). With index (from 1), the line is item index of the multi-selection open (ig_begin_multi_select): clicks, shift and ctrl clicks, ctrl+a and box-selection update the selection object, and selected is its is_selected(index). Statuses (only with index): FIG_ERR_STATE with no multi-selection open, FIG_ERR_ARGUMENT for an index outside the selection's items.

Attributes: recursive

Returns: logical

fortran
function ig_selectable(label, selected, index, stat) result(clicked)

Arguments

NameTypeIntentAttributesDescription
labelcharacter(len=*)inLabel (also its id).
selectedlogicalinHighlighted.
indexinteger(kind=int32)inoptionalThe item in the multi-selection open (from 1).
statinteger(kind=int32)outoptionalStatus.

Call graph

ig_drag_source ​

Make the last item a source of drag and drop: pressed and dragged, it carries payload (text: an id, a name, a path) under the type type, shown under the pointer as preview (default: the payload itself). Call it right after the item, every frame. Only a target of the same type (ig_drop_target, ip_drop_target) receives the payload. Items without an id (ig_text) can be sources too. Statuses: FIG_ERR_ARGUMENT for a type of no or more than 32 characters, or one starting with _ (Dear ImGui's own); FIG_ERR_STATE outside a frame or from a task.

Attributes: recursive

Returns: logical

fortran
function ig_drag_source(type, payload, preview, stat) result(dragging)

Arguments

NameTypeIntentAttributesDescription
typecharacter(len=*)inType of the payload (1 to 32 characters).
payloadcharacter(len=*)inPayload carried.
previewcharacter(len=*)inoptionalText under the pointer (default: the payload).
statinteger(kind=int32)outoptionalStatus.

Call graph

ig_drop_target ​

Make the last item a target of drag and drop for payloads of type type: true on the frame one is dropped on it, payload then holding it (as ig_drag_source gave it). While a payload of the type is dragged over the item, Dear ImGui outlines it. Call it right after the item, every frame. Statuses: as ig_drag_source.

Attributes: recursive

Returns: logical

fortran
function ig_drop_target(type, payload, stat) result(dropped)

Arguments

NameTypeIntentAttributesDescription
typecharacter(len=*)inType accepted (1 to 32 characters).
payloadcharacter(len=:)inoutallocatableThe payload dropped (unchanged otherwise).
statinteger(kind=int32)outoptionalStatus.

Call graph

ig_dragging ​

True while a payload of type type is being dragged (anywhere): a program can show its drop zones then.

Attributes: recursive

Returns: logical

fortran
function ig_dragging(type) result(dragging)

Arguments

NameTypeIntentAttributesDescription
typecharacter(len=*)inType.

Call graph

ig_font_size ​

The size of the current font [pixels] (Dear ImGui's GetFontSize): the size set by app%set_font (or pushed by ig_push_font) times the display's content scale (app%content_scale()), the height of a line of text without spacing. The unit of ig_em. No frame open or a task: 0 (a usage error, reported by app%next_frame). The same in window, headless and remote mode (headless and remote: content scale 1).

Attributes: recursive

Returns: real(kind=real64)

fortran
function ig_font_size() result(size_px)

Call graph

ig_line_height ​

The height of a line of text [pixels] (Dear ImGui's GetTextLineHeight): the font size; with spacing, plus the style's vertical item spacing, the distance between two lines of text (GetTextLineHeightWithSpacing). No frame open or a task: 0 (a usage error, reported by app%next_frame).

Attributes: recursive

Returns: real(kind=real64)

fortran
function ig_line_height(spacing) result(height)

Arguments

NameTypeIntentAttributesDescription
spacinglogicalinoptionalAdd the spacing below the line (default false).

Call graph

ig_frame_height ​

The height of a framed widget (a button, a field, a combo) [pixels] (Dear ImGui's GetFrameHeight): the font size plus twice the style's vertical frame padding; with spacing, plus the vertical item spacing, the distance between two rows of fields (GetFrameHeightWithSpacing). No frame open or a task: 0 (a usage error).

Attributes: recursive

Returns: real(kind=real64)

fortran
function ig_frame_height(spacing) result(height)

Arguments

NameTypeIntentAttributesDescription
spacinglogicalinoptionalAdd the spacing below the widget (default false).

Call graph

ig_em_r64 ​

x em [pixels]: x times the current font size (ig_font_size). No frame open or a task: 0 (a usage error).

Attributes: recursive

Returns: real(kind=real64)

fortran
function ig_em_r64(x) result(length)

Arguments

NameTypeIntentAttributesDescription
xreal(kind=real64)inLength [em].

Call graph

ig_em_i32 ​

x em [pixels], x an integer: x times the current font size. No frame open or a task: 0 (a usage error).

Attributes: recursive

Returns: real(kind=real64)

fortran
function ig_em_i32(x) result(length)

Arguments

NameTypeIntentAttributesDescription
xinteger(kind=int32)inLength [em].

Call graph

ig_splitter ​

A bar between two panes that the user drags to share the space between them: sizes(1) and sizes(2) are the panes' widths (side by side, the default) or heights (vertical: one above the other) [pixels], changed by the drag (their sum kept, neither below min_size); true on the frames they change. Call it between the two panes, at the cursor: side by side, after the first pane and ig_same_line(), then ig_same_line() again before the second; one above the other, between them. The bar is the style's item spacing thick (Dear ImGui's SplitterBehavior) and runs to the end of the region (give the panes the region's other extent: 0 for a child fills it). id names it in the window (a path finds it by it). Three panes: two splitters, each with its pair (sizes(1:2), sizes(2:3)). Statuses: FIG_ERR_ARGUMENT when sizes is not two values, FIG_ERR_STATE with no frame open or from a task. The same in every mode.

Attributes: recursive

Returns: logical

fortran
function ig_splitter(id, sizes, vertical, min_size, stat) result(changed)

Arguments

NameTypeIntentAttributesDescription
idcharacter(len=*)inId, unique in the window.
sizesreal(kind=real64)inoutThe two panes' sizes [pixels].
verticallogicalinoptionalThe panes one above the other (default: side by side).
min_sizereal(kind=real64)inoptionalA pane's least size [pixels] (default: the frame height).
statinteger(kind=int32)outoptionalStatus.

Call graph

ig_last_item ​

What happened to the item drawn last (Dear ImGui's IsItem*, IsMouseDoubleClicked, GetItemRect*), in one call: hovered, active, focused, visible, activated, edited, deactivated, deactivated_after_edit, toggled_open, clicked and double_clicked per button, its rectangle. Call it right after the item: the next item drawn replaces "the last item", the snapshot does not change. Event states are true on one frame. The same in window, headless and remote mode. No frame open or a task: all false (a usage error, reported by app%next_frame).

Attributes: recursive

Returns: type(item_status_object)

fortran
function ig_last_item() result(s)

Call graph

ig_item_hovered ​

True while the pointer is over the item drawn last (Dear ImGui's IsItemHovered), and no other item is held. delay: 'none' (default) at once; 'short' (0.15 s) and 'normal' (0.40 s) once the pointer has been over the item that long (Dear ImGui's ImGuiHoveredFlags_DelayShort/DelayNormal). The time counts only on frames that make a delayed call, so call it every frame; it is shared between items (moving to a neighbour keeps it) and cleared 0.25 s after the last delayed call over an item. An unknown delay: false, FIG_ERR_ARGUMENT in stat (or error stop without it); no frame open or a task: FIG_ERR_STATE. The same in window, headless and remote mode.

Attributes: recursive

Returns: logical

fortran
function ig_item_hovered(delay, stat) result(hovered)

Arguments

NameTypeIntentAttributesDescription
delaycharacter(len=*)inoptional'none' (default), 'short' or 'normal'.
statinteger(kind=int32)outoptionalStatus.

Call graph

ig_any_item_hovered ​

True while the pointer is over any item (Dear ImGui's IsAnyItemHovered): a click there goes to a widget, not to the window's background. No frame open or a task: false (a usage error, reported by app%next_frame).

Attributes: recursive

Returns: logical

fortran
function ig_any_item_hovered() result(hovered)

Call graph

ig_any_item_active ​

True while any item is active (Dear ImGui's IsAnyItemActive): a text field edited, a slider dragged, a button held. No frame open or a task: false (a usage error, reported by app%next_frame).

Attributes: recursive

Returns: logical

fortran
function ig_any_item_active() result(active)

Call graph

scroll_arguments ​

Check the ratio and axis of a scroll call: their values, or false with FIG_ERR_ARGUMENT reported.

Attributes: recursive

Returns: logical

fortran
function scroll_arguments(name, ratio, axis, r, a, stat) result(ok)

Arguments

NameTypeIntentAttributesDescription
namecharacter(len=*)inThe calling procedure.
ratioreal(kind=real64)inoptionalRatio, in [0, 1] (default 0.5).
axischaracter(len=*)inoptional'y' (default) or 'x'.
rreal(kind=real64)outThe ratio.
ainteger(kind=int32)outThe axis: 1 x, 2 y.
statinteger(kind=int32)outoptionalStatus.

Call graph

item_index_refused ​

Give the next item its index (from 1) in the multi-selection open; true, reported, when none is open (FIG_ERR_STATE) or the index is outside its items (FIG_ERR_ARGUMENT).

Attributes: recursive

Returns: logical

fortran
function item_index_refused(who, index, stat) result(refused)

Arguments

NameTypeIntentAttributesDescription
whocharacter(len=*)inThe procedure.
indexinteger(kind=int32)inThe item, from 1.
statinteger(kind=int32)outoptionalStatus.

Call graph

Released under the MIT licence.