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.
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 browserSource: src/lib/figure_markdown.F90
Dependencies
Contents
- markdown_view_object
- fig_markdown
- fig_markdown_link
- 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
- view_init
- view_destroy
- view_set_text
- view_load
- view_find
- view_scroll_to
- ig_markdown
- view_is_initialized
- view_text
- view_draw
- view_matches
- view_current_match
- alive
- clicked_link
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
| Name | Type | Attributes | Description |
|---|---|---|---|
handle | integer(kind=c_int) | Native handle (0: none). |
Type-Bound Procedures
| Name | Attributes | Description |
|---|---|---|
init | pass(self) | Create the view. |
destroy | pass(self) | Release it. |
is_initialized | pass(self) | Whether it exists. |
set_text | pass(self) | Replace the text. |
load | pass(self) | Read the text from a file. |
text | pass(self) | The text. |
draw | pass(self) | Draw the document as a widget. |
find | pass(self) | Search a text, or end the search. |
matches | pass(self) | The matches of the search. |
current_match | pass(self) | The current match. |
scroll_to | pass(self) | Scroll to a heading. |
Interfaces
fig_markdown
fig_markdown_link
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
subroutine view_init(self, toc, search, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | inout | View. | |
toc | logical | in | optional | A table of contents (default true). |
search | logical | in | optional | A search (default true). |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
view_destroy
Release the view (safe in any state).
Attributes: recursive
subroutine view_destroy(self)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | inout | View. |
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
subroutine view_set_text(self, text, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | inout | View. | |
text | character(len=*) | in | Markdown. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine view_load(self, path, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | inout | View. | |
path | character(len=*) | in | File. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine view_find(self, text, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | inout | View. | |
text | character(len=*) | in | Text searched. | |
stat | integer(kind=int32) | out | optional | Status. |
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
subroutine view_scroll_to(self, heading, stat)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | inout | View. | |
heading | character(len=*) | in | Its text, or # and its anchor. | |
stat | integer(kind=int32) | out | optional | Status. |
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
function ig_markdown(text, link, stat) result(clicked)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
text | character(len=*) | in | Markdown. | |
link | character(len=:) | out | allocatable, optional | The URL of the link clicked. |
stat | integer(kind=int32) | out | optional | Status. |
Call graph
view_is_initialized
Whether the view exists.
Attributes: pure
Returns: logical
function view_is_initialized(self) result(yes)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | in | View. |
view_text
The text ('' before init and from a task).
Attributes: recursive
Returns: character(len=:)
function view_text(self) result(t)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | in | View. |
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
function view_draw(self, id, link, width, height, stat) result(clicked)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | inout | View. | |
id | character(len=*) | in | Widget id (unique in the window). | |
link | character(len=:) | out | allocatable, optional | The URL of the link clicked. |
width | real(kind=real64) | in | optional | Width [pixels] (default 0: the available width). |
height | real(kind=real64) | in | optional | Height [pixels] (default 0: the available height). |
stat | integer(kind=int32) | out | optional | Status. |
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)
function view_matches(self) result(n)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | in | View. |
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)
function view_current_match(self) result(k)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | in | View. |
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
function alive(self, name, stat, quiet) result(ok)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
self | class(markdown_view_object) | in | View. | |
name | character(len=*) | in | The method. | |
stat | integer(kind=int32) | out | optional | Status. |
quiet | logical | in | optional | A query: no failure before init. |
Call graph
clicked_link
The URL of the last link clicked.
Attributes: recursive
Returns: character(len=:)
function clicked_link() result(url)Call graph