Skip to content

figure_markdown ​

figure_markdown, Markdown in the window: a text at the cursor (ig_markdown) and documents (markdown_view_object).

The renderer is imgui_rich_md (pthom, MIT, vendored in third_party/imgui_rich_md with md4c, its parser) with FIGURE's glue (native/figure_markdown.cpp): it draws through Dear ImGui only, so window, headless and remote modes show the same pixels. Text in IBM Plex Sans (regular, bold, italic, bold italic: headings are larger), code spans and blocks in IBM Plex Mono, with the Lucide icons and the fallback fonts as everywhere else; tables, lists, quotes, task lists, GitHub's admonitions (> [!NOTE]), collapsible sections (<details>), images from PNG and JPEG files. No LaTeX, no image from a URL. Links are reported, never opened: the call that draws a text returns true on the frame one of its links is clicked, and gives its URL (polled, no callback); a link to a heading of the same text scrolls to it.

fortran
 type(markdown_view_object)    :: help
 character(len=:), allocatable :: url
 call help%init()
 call help%load('help/solver.md')
 ... every frame, inside a window:
 if (help%draw('help', url)) call follow(url)   ! the program decides: another page, a section, a browser

Source: src/lib/figure_markdown.F90

Dependencies

Contents ​

Derived Types ​

markdown_view_object ​

A Markdown document: its text kept by FIGURE, drawn in a scroll area of its own with a table of contents beside it (from three headings) and a search (ctrl+f, or find). view%init, view%set_text or view%load, then view%draw every frame. Not to be copied (the copy would share the view); destroy releases it.

Components

NameTypeAttributesDescription
handleinteger(kind=c_int)Native handle (0: none).

Type-Bound Procedures

NameAttributesDescription
initpass(self)Create the view.
destroypass(self)Release it.
is_initializedpass(self)Whether it exists.
set_textpass(self)Replace the text.
loadpass(self)Read the text from a file.
textpass(self)The text.
drawpass(self)Draw the document as a widget.
findpass(self)Search a text, or end the search.
matchespass(self)The matches of the search.
current_matchpass(self)The current match.
scroll_topass(self)Scroll to a heading.

Interfaces ​

fig_markdown ​

fig_markdown_view_create ​

fig_markdown_view_set_text ​

fig_markdown_view_load ​

fig_markdown_view_text ​

fig_markdown_view_find ​

fig_markdown_view_scroll_to ​

fig_markdown_view_info ​

fig_markdown_view_draw ​

fig_markdown_view_destroy ​

Subroutines ​

view_init ​

Create the view (an existing one is destroyed first), empty. With toc (default true) a table of contents beside the text once it has three headings or more (a narrow view shows it as a line above the text); with search (default true) the find bar (ctrl+f, cmd+f on macOS, or "/" while the view has the focus; enter goes to the next match, escape closes it). Statuses: FIG_ERR_STATE from a task. Data only: before app%init* too.

Attributes: recursive

fortran
subroutine view_init(self, toc, search, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inoutView.
toclogicalinoptionalA table of contents (default true).
searchlogicalinoptionalA search (default true).
statinteger(kind=int32)outoptionalStatus.

Call graph

view_destroy ​

Release the view (safe in any state).

Attributes: recursive

fortran
subroutine view_destroy(self)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inoutView.

Call graph

view_set_text ​

Replace the text with text (Markdown, UTF-8): drawn from the next draw, its scroll and search kept. Statuses: FIG_ERR_STATE before init and from a task.

Attributes: recursive

fortran
subroutine view_set_text(self, text, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inoutView.
textcharacter(len=*)inMarkdown.
statinteger(kind=int32)outoptionalStatus.

Call graph

view_load ​

Replace the text with the content of the file path (UTF-8 name and content), keeping the scroll and the search as set_text does. Its images are read from paths relative to the working directory, not to the file. Statuses: FIG_ERR_ARGUMENT for an empty name, FIG_ERR_FAILED if the file cannot be read (the text is kept); FIG_ERR_STATE before init and from a task.

Attributes: recursive

fortran
subroutine view_load(self, path, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inoutView.
pathcharacter(len=*)inFile.
statinteger(kind=int32)outoptionalStatus.

Call graph

view_find ​

Search text from the next draw (as the find bar does: any case, the matches highlighted, the first one below the top of the view made current and scrolled to); '' ends the search and closes the bar. Statuses: FIG_ERR_ARGUMENT for a text over 255 bytes or of more than one line; FIG_ERR_STATE before init and from a task.

Attributes: recursive

fortran
subroutine view_find(self, text, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inoutView.
textcharacter(len=*)inText searched.
statinteger(kind=int32)outoptionalStatus.

Call graph

view_scroll_to ​

Scroll to a heading from the next draw (over a few frames, as a click in the table of contents): heading its text ('Boundary conditions') or its anchor after # ('#boundary-conditions', GitHub's: lower case, blanks as -, punctuation dropped; a repeated title's second is -1). A heading the text does not have: nothing happens. Statuses: FIG_ERR_ARGUMENT for an empty heading; FIG_ERR_STATE before init and from a task.

Attributes: recursive

fortran
subroutine view_scroll_to(self, heading, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inoutView.
headingcharacter(len=*)inIts text, or # and its anchor.
statinteger(kind=int32)outoptionalStatus.

Call graph

Functions ​

ig_markdown ​

Draw text (Markdown, UTF-8, lines ended by LF or CR LF) at the cursor, inside a window, as wide as the window and as tall as it needs (the window scrolls). True on the frame one of its links is clicked: its URL in link ('' on the other frames); nothing is opened. A link to a heading of the same text ([units](#units)) scrolls the window there instead, and is not reported; one to a heading it does not have is ('#units'). The text can be selected with the mouse and copied (ctrl+c; a right click: Copy, Copy as Markdown, Copy Link). Statuses: FIG_ERR_STATE with no frame open and from a task; FIG_ERR_FAILED if the fonts cannot be loaded. The same in every mode.

Attributes: recursive

Returns: logical

fortran
function ig_markdown(text, link, stat) result(clicked)

Arguments

NameTypeIntentAttributesDescription
textcharacter(len=*)inMarkdown.
linkcharacter(len=:)outallocatable, optionalThe URL of the link clicked.
statinteger(kind=int32)outoptionalStatus.

Call graph

view_is_initialized ​

Whether the view exists.

Attributes: pure

Returns: logical

fortran
function view_is_initialized(self) result(yes)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inView.

view_text ​

The text ('' before init and from a task).

Attributes: recursive

Returns: character(len=:)

fortran
function view_text(self) result(t)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inView.

Call graph

view_draw ​

Draw the document as a widget at the cursor, inside a window, width x height pixels (0: the available region; negative: up to that distance from its edge): its text in a scroll area, the table of contents beside it, the find bar over it while searching. True on the frame one of its links is clicked, its URL in link ('' on the other frames); nothing is opened. A link to one of its headings scrolls there instead ([units](#units)), and is not reported. Statuses: FIG_ERR_ARGUMENT for an empty id; FIG_ERR_STATE before init, with no frame open, from a task; FIG_ERR_FAILED if the fonts cannot be loaded. The same in every mode.

Attributes: recursive

Returns: logical

fortran
function view_draw(self, id, link, width, height, stat) result(clicked)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inoutView.
idcharacter(len=*)inWidget id (unique in the window).
linkcharacter(len=:)outallocatable, optionalThe URL of the link clicked.
widthreal(kind=real64)inoptionalWidth [pixels] (default 0: the available width).
heightreal(kind=real64)inoptionalHeight [pixels] (default 0: the available height).
statinteger(kind=int32)outoptionalStatus.

Call graph

view_matches ​

The matches of the search at the last draw (0 with no search, before init and from a task).

Attributes: recursive

Returns: integer(kind=int32)

fortran
function view_matches(self) result(n)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inView.

Call graph

view_current_match ​

The current match of the search at the last draw, from 1 (0 with none, before init and from a task).

Attributes: recursive

Returns: integer(kind=int32)

fortran
function view_current_match(self) result(k)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inView.

Call graph

alive ​

True when the view exists and the caller is on the main thread; else the refusal (FIG_ERR_STATE), silent for a query (quiet: its default value is the answer).

Attributes: recursive

Returns: logical

fortran
function alive(self, name, stat, quiet) result(ok)

Arguments

NameTypeIntentAttributesDescription
selfclass(markdown_view_object)inView.
namecharacter(len=*)inThe method.
statinteger(kind=int32)outoptionalStatus.
quietlogicalinoptionalA query: no failure before init.

Call graph

The URL of the last link clicked.

Attributes: recursive

Returns: character(len=:)

fortran
function clicked_link() result(url)

Call graph

Released under the MIT licence.