Skip to content

25. The input in an editor, the help in Markdown ​

The input's text, until now a plain multi-line field, becomes a code editor: the namelist highlighted, its names completed, and each mistake marked on its line as the user types, so that Apply is not a guess. And the studio gets its help, written in Markdown and drawn by FIGURE, whose links show a section of the input.

docs/examples/src/tut25_editor.F90, run as tut25_editor --examples /tmp/figure-studio --case /tmp/figure-studio/plate

The whole program: tut25_editor.F90, chapter 24's studio with the changes below.

What this chapter adds to chapter 24's program, tut24_windows.F90:

  • draw_help: The help
  • show_help: The help shown, scrolled to heading ('' where it was)
  • set_source: The text of the editor, from the input; checked (a text written by the program has no mistake)
  • validate: Mark the text's mistakes on their lines
  • mark_names: Mark each name assigned in the text (name =) that the namelist &heat has not; strings and comments skipped
  • lower: text in lower case
  • line_of: The line of text where name is first followed by "=" (or the line of "&heat"); 0 if none
  • read_text: Read a text as the input file
  • help_text: The studio's help, in Markdown
  • changed: apply_text, draw_form, draw_input, draw_menus, draw_panels, draw_source, open_case, register_windows, self_test, undo

The editor ​

source, a text_buffer_object since chapter 11, is now a code_editor_object, created after app%init with the language of its text and the words its completion offers (Code editor):

fortran
call source%init(code_language('fortran'))       ! a namelist is Fortran: names, strings, numbers, ! comments
call source%set_completions(NAMES)                ! typing "tol" offers "tolerance"
call help%init()                                  ! a table of contents and a find bar
call help%set_text(help_text())
  • The language. A namelist is Fortran: code_language('fortran') colours its names, strings, numbers and ! comments. FIGURE ships 'fortran' and 'input' (key = value files) besides the editor's own languages.
  • Completion. set_completions(NAMES): typing tol offers tolerance; Tab or Enter takes it.
  • One text, two edits. The form still writes the text with case_text; set_source puts it in the editor, which forgets its own undo history and marks: the program's text has no mistake.

The editor is one widget, drawn where the multi-line field was; it is true on the frame the user changed the text:

fortran
if (source%draw('heat.inp', height=-ig_frame_height())) then ! the user changed the text: check it again
   text_edited = .true.
   call validate()
endif
call source%cursor(line, column)
write(where, '(A,I0,A,I0)') 'line ', line, ', column ', column
call ig_text_disabled(trim(where))

height=-ig_frame_height() leaves one line below it for the cursor's position, source%cursor(line, column).

Mistakes marked on their lines ​

Chapter 11's Apply read the text and, on a mistake, said so in a notification. The editor marks the line instead, on each change:

fortran
call source%clear_marks()
text_errors = 0_int32
text = source%text()
call mark_names(text)                             ! a mark per unknown name, on its line
if (text_errors > 0_int32) return
call read_text(text, new, stat, msg)
if (stat /= 0) then                               ! a value that does not read: the run time says which
   call source%mark(max(1_int32, line_of(text, '&heat')), 'error', msg)
   text_errors = 1_int32
   return
endif
list = problems(new)
ids = problem_ids(new)
do k = 1_int32, size(list, kind=int32)            ! the input reads: what the solver would refuse
   call source%mark(max(1_int32, line_of(text, trim(NAME_OF(ids(k))))), 'error', trim(list(k)))
   text_errors = text_errors + 1_int32
enddo
  • source%mark(line, 'error', message) tints the line and its number and puts an icon beside the number, so the colour is not the only sign; the pointer over the line shows the message. 'warning' and 'info' are the other severities (Marks).
  • clear_marks first: the marks are the program's, and stay until it changes them.
  • Three checks, in order: a name the namelist has not (mark_names, a small scan that skips strings and comments), then the run time's message when the namelist does not read, then the input's own checks of chapter 19 (problems), each on the line of the name it is about.

Apply is enabled when the text was edited and no line is marked; the bar above the editor says which. Ctrl+Z in the editor is its own undo, as it was for the field.

The help ​

The help is a page of Markdown, held by a markdown_view_object: headings, tables, code and links, with a table of contents (a drop-down of its headings, at the top) and a find bar (Markdown). The studio writes its text in the program (help%load(path) reads a file instead):

fortran
text = '# The studio'//LF//LF// &
   'A **case** is a folder holding its input, `heat.inp`. Open one with *File > Open case* (ctrl+o), or drop '// &
   'its folder on the window; run the solver with *Run > Run* (F5).'//LF//LF// &
   '# The input'//LF//LF// &
   '`heat.inp` is the namelist `&heat`: `name = value` items, `!` comments. Edit it in the form or as text: '// &
   'the text marks each mistake on its line, and *Apply* waits until none is left.'//LF//LF// &
   '## Grid'//LF//LF//'| name | meaning | unit |'//LF//'|---|---|---|'//LF// &
   '| `nx`, `ny` | grid nodes along x and y, at least 3 | |'//LF// &
   '| `lx`, `ly` | the plate''s width and height | m |'//LF//LF//'[The grid in the input](form:1)'//LF//LF// &
   '## Boundaries'//LF//LF//'| name | meaning | unit |'//LF//'|---|---|---|'//LF// &
   '| `bc_kind` | west, east, south, north: `''fixed''` or `''insulated''` | |'//LF// &
   '| `bc_value` | the fixed sides'' temperatures | C |'//LF//LF// &
   'Not every side insulated: the temperature would not be determined.'//LF//LF// &
   '[The boundaries in the input](form:2)'//LF//LF// &
   '## Body'//LF//LF//'| name | meaning | unit |'//LF//'|---|---|---|'//LF// &
   '| `body_x`, `body_y` | the body''s centre | m |'//LF//'| `body_r` | its radius, inside the plate | m |'//LF// &
   '| `body_t` | its temperature | C |'//LF//LF//'[The body in the input](form:3)'//LF//LF// &
   '## Solver'//LF//LF//'| name | meaning | unit |'//LF//'|---|---|---|'//LF// &
   '| `omega` | over-relaxation factor, in (0, 2): 1 is Gauss-Seidel | |'//LF// &
   '| `tolerance` | the residual to reach | C |'//LF//'| `max_iter` | iterations at most | |'//LF//LF// &
   '[The solver in the input](form:4)'//LF//LF// &
   '# Keys'//LF//LF//'| key | does |'//LF//'|---|---|'//LF//'| ctrl+o | open a case |'//LF// &
   '| ctrl+s | save the input |'//LF//'| ctrl+z | undo an edit of the form |'//LF//'| F5, shift+F5 | run, stop |'// &
   LF//'| F1 | this help |'//LF

It is a registered window (chapter 24), floating, in no layout; Help > Help and F1 show it, and the link above the input's tree shows it at the section in front with help%scroll_to(heading):

fortran
if (ig_text_link(ICON_BOOK_OPEN//' Help on '//trim(SECTIONS(section)))) call show_help(trim(SECTIONS(section)))
fortran
if (ig_begin('Help')) then
   if (help%draw('page', link)) then              ! a link clicked: the program decides what it opens
      if (index(link, 'form:') == 1) then          ! the studio's own: form:N, a section of the input, chosen in its tree
         read(link(6:), *) n
         section = n
         call app%set_window_visible('Input', .true.)
         if (ig_focus_window('Input')) continue
      endif
   endif
endif
call ig_end()

help%draw is true on the frame a link is clicked, with its URL: FIGURE opens nothing, the program decides. The studio's links are its own, form:N, the section N of the input. About keeps its menu item, without the F1 it had.

The test ​

fortran
call test_item_click('heat.inp')                  ! the text's tab, in the Input panel
call settle()
call source%goto(line_of(source%text(), 'omega'), 3_int32, focus=.true.) ! the cursor on "omega"
call frames(3_int32)
call check(source%find('omega', whole_word=.true.), 'the editor finds "omega" in the text')
call test_type('omgea')                           ! a typo over the selection, as the user types it
call frames(4_int32)
call check(source%mark_of(line_of(source%text(), 'omgea')) == 'error' .and. text_errors == 1_int32 .and. &
           text_edited, 'a name the namelist has not is marked on its line; Apply waits')
if (source%replace('omgea', 'omega', whole_word=.true.) == 1_int32) call validate() ! find and replace, one undo
call frames(4_int32)
call check(text_errors == 0_int32 .and. index(source%text(), 'omega =') > 0, 'the name corrected, no line is marked')
call test_item_click('Form')                      ! the form in front again
call settle()
call test_key('f1')                               ! the help
call frames(4_int32)
call help%find('omega')
call frames(3_int32)
call check(app%window_visible('Help') .and. help%matches() > 0, 'F1 shows the help; it finds "omega"')
call help%find('')
call app%set_window_visible('Help', .false.)
call frames(2_int32)

The test clicks the text's tab by its label with test_item_click('heat.inp'), selects omega with source%find and types over it, as the user would; source%mark_of(line) reads the mark back. It corrects the name with source%replace, the editor's find and replace, which is one step of its undo history.

text
$ ./tut25_editor --test tut25-cases
[ok]     the title bar holds the studio's menus
[ok]     the title drags the window
[ok]     ctrl+o shows the file browser on the example cases
[ok]     Choose opens the case, the window's title says which
[ok]     escape leaves the title as it was, unedited
[ok]     enter commits the title, one undo step, and the window's title marks it unsaved
[ok]     a drop asks before discarding the edit
[ok]     Discard opens the dropped case
[ok]     F5 runs the solver to convergence
[ok]     the task reads the field the solver wrote
[ok]     right moves the probe line while Result has the focus
[ok]     and not while the title field is edited
[ok]     nor while another panel has the focus
[ok]     the run's snapshots are listed; a frame with nothing changed colours nothing
[ok]     playing steps through the snapshots, each coloured once
[ok]     the pointer over the monitor reads iteration 111: residual  3.91E-05, mean 20.615 C
[ok]     the averaging window spans the run: its mean is the mean of every iteration
[ok]     two runs in the table, sorted by iterations on a click of its header
[ok]     a second click reverses the order
[ok]     a right click on a run opens its menu
[ok]     View > Analysis: Input hidden, Messages shown beside Run
[ok]     the 3-D view docked on the right of the result
[ok]     View > Input shows the panel the layout hid
[ok]     View > Setup gives back the input's layout
[ok]     the editor finds "omega" in the text
[ok]     a name the namelist has not is marked on its line; Apply waits
[ok]     the name corrected, no line is marked
[ok]     F1 shows the help; it finds "omega"
[ok]     a click on a problem shows the Body section, the radius in keys
[ok]     a click on the sketch's east side chooses it
[ok]     an input with the body out of the plate is refused
[ok]     and accepted once corrected
[ok]     larger text: one em is 19 pixels, the bar 5 em
[ok]     a stray ig_end_tab is reported by the next frame, naming the call
         ig_end_tab: no ig_begin_tab is open (no scope is open)
[ok]     no other frame of the test had a usage error
[ok]     the title bar's close button ends the studio
36 of 36 checks passed

What you learned

code_editor_object: init with code_language, set_completions, draw, mark and clear_marks, find, replace and mark_of; markdown_view_object: set_text, draw with the link clicked, scroll_to, find and matches. Reference: Code editor, Markdown.

Run it: build it as chapter 7 shows (with tut22_heat beside it), then ./tut25_editor --examples /tmp/studio --case /tmp/studio/plate.

Next: 26. A clip plane by hand, the studio as a picture: a plane the user places in the 3-D view, and the studio tested by paths and by its picture.

Released under the MIT licence.