Skip to content

11. The input editor ​

Chapter 10 opened a case; its Input panel now edits the case's input. A tree lists the input's sections; a form edits the section chosen, with numeric fields, sliders, drop-down lists and a table; the same input is shown as the text of heat.inp, in the monospace font, where it can be edited too. Edit > Undo takes back the form's edits.

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

The whole program: tut11_input.F90. From this chapter on, --case DIR opens a case at the start.

What this chapter adds to chapter 10's program, tut10_case.F90:

  • draw_input: The Input panel
  • section_node: A section as a leaf of the tree
  • draw_form: The form of the section chosen in the tree; an edit marks the case edited and can be undone
  • draw_source: The input file as text, in the monospace font
  • apply_text: Read the text as the input; on a mistake, say where, and keep the text for the user to correct
  • push_undo: Keep state for Undo; the oldest goes when the history is full
  • undo: Take back the last edit of the form
  • read_input: Read the namelist &heat from the open unit u
  • case_text: A case's input as the namelist &heat, one group of parameters per line
  • changed: draw_menus, draw_panels, open_case, read_case, save_case, write_case

A tree of the sections ​

fortran
if (ig_begin_child('sections', width=170.0_real64, border=.true.)) then
   if (ig_tree_node(ICON_FILE_PEN//' '//INPUT_FILE, default_open=.true.)) then
      call section_node(1_int32)
      if (ig_tree_node('Boundaries', default_open=.true., selected=section == 2_int32, span_full_width=.true., &
                       clicked=clicked)) then
         do k = 1_int32, size(SIDES, kind=int32)  ! the sides: leaves, each choosing the table
            if (ig_tree_node(trim(SIDES(k)), leaf=.true., span_full_width=.true., clicked=side_clicked)) &
               call ig_tree_pop()
            if (side_clicked) section = 2_int32
         enddo
         call ig_tree_pop()
      endif
      if (clicked) section = 2_int32               ! the label, not the arrow
      call section_node(3_int32)
      call section_node(4_int32)
      call ig_tree_pop()
   endif
endif
call ig_end_child()
  • The tree is in a child region of its own (ig_begin_child, 170 pixels wide, framed); the form goes beside it.
  • Beside the tree, a tab bar (ig_begin_tab_bar('views')) holds two tabs, Form and heat.inp (ig_begin_tab): only the selected tab's content is drawn, and ig_end_tab and ig_end_tab_bar follow only a begin that returned .true. (Groups: headers, tabs, tables).
  • ig_tree_node(label, default_open=, selected=, leaf=, span_full_width=, clicked=) is .true. while the node is open: its children are drawn, then ig_tree_pop() closes it, only after a .true.. A leaf has no arrow and no children (Trees).
  • clicked tells a click on the label from a click on the arrow: the arrow opens and closes, the label chooses the section. The sides are leaves of Boundaries; a click on any of them shows the table.

Forms and a table ​

fortran
select case (section)
case (1_int32)                                     ! numeric fields: integers with +/- buttons, reals with a format
   if (ig_input('nx', inp%nx, step=1_int32)) changing = .true.
   if (ig_input('ny', inp%ny, step=1_int32)) changing = .true.
   if (ig_input('lx [m]', inp%lx, format='%.3f')) changing = .true.
   if (ig_input('ly [m]', inp%ly, format='%.3f')) changing = .true.
   inp%nx = max(inp%nx, 3_int32)                   ! the solver needs an interior
   inp%ny = max(inp%ny, 3_int32)
case (3_int32)                                     ! sliders: the body stays inside the plate
   if (ig_slider('x [m]', inp%body_x, 0.0_real64, inp%lx)) changing = .true.
   if (ig_slider('y [m]', inp%body_y, 0.0_real64, inp%ly)) changing = .true.
   if (ig_slider('radius [m]', inp%body_r, 0.01_real64, 0.5_real64 * min(inp%lx, inp%ly))) changing = .true.
   inp%body_x = 0.001_real64 * nint(1000.0_real64 * inp%body_x) ! a slider gives any real: millimetres here
   inp%body_y = 0.001_real64 * nint(1000.0_real64 * inp%body_y)
   inp%body_r = 0.001_real64 * nint(1000.0_real64 * inp%body_r)
   if (ig_input('temperature [C]', inp%body_t, format='%.1f')) changing = .true.
case (4_int32)
   if (ig_slider('omega', inp%omega, 1.0_real64, 1.95_real64)) changing = .true.
   inp%omega = 0.01_real64 * nint(100.0_real64 * inp%omega)       ! two decimals
   call ig_tooltip('Over-relaxation: 1 is Gauss-Seidel, close to 2 converges faster or not at all')
   if (ig_input('tolerance', inp%tolerance, format='%.1e')) changing = .true.
   if (ig_input('iterations at most', inp%max_iter, step=100_int32)) changing = .true.
end select

Each widget is bound to a component of inp, the case's input, and edits it in place; it returns .true. on the frame it changes it (Widgets):

  • ig_input(label, value, step=) for an integer, with + and - buttons; ig_input(label, value, format=) for a real, shown with a C format ('%.3f', '%.1e').
  • ig_slider(label, value, vmin, vmax) for a value in a range: the body stays inside the plate. A slider gives any real, so the studio rounds the value to the input file's precision.
  • ig_tooltip explains the widget under the pointer.
fortran
if (section == 2_int32) then
   if (ig_begin_table('boundaries', 3_int32)) then
      call ig_table_setup_column('side', width=70.0_real64)
      call ig_table_setup_column('condition', width=140.0_real64)
      call ig_table_setup_column('temperature [C]')
      call ig_table_headers_row()
      do k = 1_int32, size(SIDES, kind=int32)
         call ig_push_id(k)                        ! the same widgets in every row: an id scope per row
         call ig_table_next_row()
         call ig_table_next_column()
         call ig_text(trim(SIDES(k)))
         call ig_table_next_column()
         kind = merge(1_int32, 2_int32, inp%bc_kind(k) == KINDS(1))
         call ig_set_next_item_width(-1.0_real64)
         if (ig_combo('##kind', kind, KINDS)) then
            inp%bc_kind(k) = KINDS(kind)
            changing = .true.
         endif
         call ig_table_next_column()
         call ig_begin_disabled(kind == 2_int32)   ! an insulated side has no temperature
         call ig_set_next_item_width(-1.0_real64)
         if (ig_input('##value', inp%bc_value(k), format='%.1f')) changing = .true.
         call ig_end_disabled()
         call ig_pop_id()
      enddo
      call ig_end_table()
   endif
endif
  • ig_begin_table(id, columns) and ig_end_table(), paired; ig_table_setup_column names each column, with a fixed width or a share of the rest, and ig_table_headers_row draws the names.
  • Every row repeats the same widgets with the same labels: ig_push_id(k) and ig_pop_id() give each row its own id scope, and the labels start with ##, so that nothing is shown beside the field.
  • ig_combo(label, current, items) is a drop-down list of KINDS; current is the index chosen.
  • ig_begin_disabled(kind == 2) greys the temperature out on an insulated side: it does not apply there.
  • ig_set_next_item_width(-1) makes the next widget fill its cell.

Undo ​

fortran
if (changing) then
   if (.not. was_changing) call push_undo(before) ! one Undo per edit, not per frame of it
   edited = .true.
   call show_title()
   call source%set(case_text(inp))                ! the text follows the form
   text_edited = .false.
endif
was_changing = changing
fortran
if (ig_begin_menu('Edit')) then
   if (ig_menu_item(ICON_UNDO//' Undo', shortcut='Ctrl+Z', enabled=nhistory > 0_int32)) call undo()
   call ig_end_menu()
endif

The form keeps the input as it was before each edit. An edit lasts several frames (a slider dragged, a number typed), so the studio keeps the state only on the first frame of a change: one Undo per edit. Edit > Undo and ctrl+z bring the last one back. In the text (below), ctrl+z is the text field's own undo: the studio reads ctrl+z only while the form is shown.

The input as text ​

fortran
call ig_begin_disabled(.not. text_edited)
if (ig_button(ICON_CHECK//' Apply')) call apply_text()
call ig_end_disabled()
call ig_same_line()
if (text_edited) then
   call ig_text('(!) the text is not applied yet')
else
   call ig_text_disabled('the input, as heat.inp will hold it')
endif
call ig_push_font('plex-mono')                     ! columns line up: every character as wide
if (ig_input_text_multiline('##source', source, width=-1.0_real64, height=-1.0_real64)) text_edited = .true.
call ig_pop_font()
  • ig_input_text_multiline(label, buffer) edits a text of any length, kept in a text_buffer_object (Multi-line text): Enter starts a new line, ctrl+z and ctrl+y undo and redo, ctrl+c and ctrl+v copy and paste. width=-1 and height=-1 fill the space left.
  • ig_push_font('plex-mono') and ig_pop_font() draw it in IBM Plex Mono, the bundled monospace font, so that the input's columns line up (Fonts).
  • source%set(case_text(inp)) replaces the text whenever the form changes the input: the form and the text show the same input.
fortran
text = source%text()
open(newunit=u, status='scratch', action='readwrite') ! a namelist is read from a file: the text into one
first = 1_int32
do while (first <= len(text))
   last = index(text(first:), char(10)) + first - 1_int32
   if (last < first) last = len(text) + 1_int32   ! the last line, without a line feed
   write(u, '(A)') text(first:last - 1_int32)
   first = last + 1_int32
enddo
rewind(u)
call read_input(u, new, stat, msg)
close(u)
if (stat /= 0) then
   call app%notify(INPUT_FILE//' does not read: '//msg, kind='error') ! the text stays, to be corrected
   return
endif
call push_undo(inp)
inp = new
edited = .true.
text_edited = .false.
call show_title()

Apply reads the text as the namelist: Fortran reads a namelist from a file, so the text goes to a scratch file, line by line, and read_input reads it back from there. A text that does not read leaves the input as it was, and a notification gives the run time's message; the text stays, to be corrected.

What you learned

A tree with leaves and clickable labels; numeric fields, sliders, drop-down lists and tooltips bound to Fortran variables; a table with a row per item and an id scope per row; greyed-out widgets; an undo of the form's edits; a multi-line text field in the monospace font, read back as a namelist. Reference: Widgets, Trees, Multi-line text, Fonts.

Run it: build it as chapter 7 shows, then ./tut11_input --examples /tmp/studio --case /tmp/studio/plate.

Next: 12. Running the solver: the solver as a process, its log, a live plot of its residuals.

Released under the MIT licence.