Skip to content

21. Tables that act ​

A table of part two showed values; in this chapter the studio's tables answer the user. The Run panel keeps the session's runs in a table that sorts by the column clicked, with a menu and a picture of each run's residuals on its row; the boundaries' table gets radio buttons and a menu per side; the body's centre and the tolerance get the number widgets made for them.

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

The whole program: tut21_tables.F90, chapter 20's studio with the changes below.

What this chapter adds to chapter 20's program, tut20_layout.F90:

  • add_run: The run that just ended, added to the session's runs; the table keeps its order
  • sort_runs: Sort the permutation order by column sort_key (sort_down
  • draw_runs: The Runs tab
  • run_menu: The context menu and the tooltip of run k's row, on the item just drawn
  • remove_run: Remove run k from the session's list
  • changed: draw_form, draw_run, follow_run, self_test

The session's runs ​

When a run ends, follow_run adds it to runs, an array of run_t: its number, the case's title, the iterations, the last residual, the outcome and its residual history. The Run panel has two tabs now, in a tab bar as chapter 11's Input panel (Groups: headers, tabs, tables): This run (the log and the live plot of chapter 12) and Runs:

fortran
if (ig_begin_table('runs', 5_int32, flags=ior(ImGuiTableFlags_RowBg, ImGuiTableFlags_BordersInnerV), &
                   freeze_rows=1_int32, sortable=.true.)) then ! the header stays in view; the rows scroll
   call ig_table_setup_column('run', width=ig_em(3), default_sort=.true.)
   call ig_table_setup_column('case', stretch=1.0_real64)
   call ig_table_setup_column('residual', width=ig_em(6))
   call ig_table_setup_column('outcome', width=ig_em(7))
   call ig_table_setup_column('iterations', width=ig_em(6))
   if (ig_table_sort(sort_key, sort_down)) call sort_runs() ! a header clicked: the program sorts its rows
   call ig_table_headers_row()
   call centre_of_last(header_at)                 ! the last header, iterations: for the test
   do r = 1_int32, size(order, kind=int32)
      k = order(r)
      call ig_push_id(runs(k)%number)             ! each row's menu has its own id
      call ig_table_next_row()
      if (runs(k)%outcome /= 'converged') call ig_table_row_color([red(1:3), 0.25_real64]) ! with a mark below
      call ig_table_next_column()
      write(text, '(I0)') runs(k)%number
      if (ig_selectable(trim(text), k == picked_run)) picked_run = k
      if (r == 1_int32) call centre_of_last(row_at)
      call run_menu(k, remove)
      call ig_table_next_column()
      call ig_text(trim(runs(k)%title))
      call ig_table_next_column()
      write(text, '(ES9.2)') runs(k)%residual
      call ig_text(trim(text))
      call ig_table_next_column()
      call ig_text(trim(merge('     ', '[!!] ', runs(k)%outcome == 'converged'))//trim(runs(k)%outcome))
      call ig_table_next_column()
      write(text, '(I0)') runs(k)%iterations
      call ig_text(trim(text))
      call ig_pop_id()
   enddo
   call ig_end_table()
endif
  • A frozen header. freeze_rows=1 keeps the header row in view while the rows scroll: a table with a frozen row scrolls by itself, in the height left in the tab (Tables).
  • Sorting is the program's. sortable=.true. makes the headers clickable; ig_table_sort(key, descending) is true on the frame the user asks a new order (and on the first frame, with the default_sort column), and gives the column and the direction. FIGURE does not move the rows: the studio sorts a permutation, order, and draws the rows in that order. A run added later takes its place by the same sort.
  • Colour with a mark. A run that did not converge has its row shaded in the palette's error colour, and its outcome reads [!!] stopped or [!!] failed: the colour is never the only sign.
  • A selectable per row. The run's number is drawn with ig_selectable(label, selected), a line of a list: highlighted while selected, .true. on the frame it is clicked. The program keeps the choice, picked_run (Lists and regions).
  • Each row's widgets are in an id scope of the run's number (ig_push_id), so that the rows' menus and selectables are told apart.

A menu and a picture on each row ​

fortran
if (ig_begin_popup_context('run')) then            ! a right click on the row
   write(text, '(ES12.5)') runs(k)%residual
   if (ig_menu_item('Copy the residual')) call ig_set_clipboard(trim(adjustl(text)))
   if (ig_menu_item('Remove from the list')) remove = k
   call ig_end_popup()
endif
if (ig_begin_item_tooltip()) then                  ! the pointer rests on the row: its residuals
   if (ip_begin_plot('##history', width=ig_em(18), height=ig_em(10))) then
      call ip_setup_axes('iteration', 'residual', yscale='log')
      call ip_line('residual', runs(k)%it, runs(k)%res)
      call ip_end_plot()
   endif
   call ig_end_tooltip()
endif

ig_begin_popup_context(id) opens a menu on a right click over the item drawn just before it, here the row's selectable; it is a popup, closed with ig_end_popup after a true begin (Context menus). The row is removed after the table is drawn, not while: the loop draws the list as it was at the start of the frame. ig_begin_item_tooltip() opens a tooltip when the pointer rests on the same item, and a tooltip can hold anything: a plot of the run's residuals (Tooltips).

Choices in the boundaries' table ​

fortran
if (ig_radio('fixed', kind, 1_int32)) changing = .true. ! a click sets kind to the button's value
call ig_same_line()
if (ig_radio('insulated', kind, 2_int32)) changing = .true.
inp%bc_kind(k) = KINDS(kind)

ig_radio(label, current, value) is a button of a group sharing current: a click sets current = value, and the button whose value equals current is drawn chosen (Choices). Two radio buttons show both conditions at once, where chapter 11's drop-down list hid one. The side's name has a menu of its own:

fortran
if (ig_selectable(trim(SIDES(k)), .false.)) continue
if (ig_begin_popup_context('side')) then  ! a right click on the side's name
   if (ig_menu_item('Every side as this one')) then
      inp%bc_kind = inp%bc_kind(k)
      inp%bc_value = inp%bc_value(k)
      changing = .true.
   endif
   if (ig_menu_item('Insulated', enabled=inp%bc_kind(k) /= KINDS(2))) then
      inp%bc_kind(k) = KINDS(2)
      changing = .true.
   endif
   call ig_end_popup()
endif

Numbers ​

The body's centre is one widget of two numbers, a drag box per component: drag a box (0.002 m per pixel), or double-click it and type (Numbers):

fortran
centre = [inp%body_x, inp%body_y]
if (ig_drag('centre x, y [m]', centre, speed=0.002_real64, vmin=0.0_real64, vmax=max(inp%lx, inp%ly), &
            format='%.3f')) then                ! one box per component, dragged or typed
   inp%body_x = centre(1)
   inp%body_y = centre(2)
   changing = .true.
endif

The tolerance goes from 10⁻¹⁰ to 10⁻², eight decades: on a linear slider every value below 10⁻³ would be in its first pixel. scale='log' gives each decade the same length:

fortran
if (ig_slider('tolerance', inp%tolerance, 1.0e-10_real64, 1.0e-2_real64, format='%.1e', scale='log')) &
   changing = .true.                            ! a decade per equal stretch of the slider

The formats are checked against the value's kind before Dear ImGui uses them: '%d' for a real is refused with FIG_ERR_ARGUMENT (Formats).

The test ​

Two runs, the second with a smaller omega, each waited for until its field is read (the Result panel comes forward then, at a moment of the task's: a click before it could land on a panel about to be covered); the Runs tab clicked, the iterations' header clicked twice, a right click on a row:

fortran
inp%omega = 1.5_real64                            ! a second run, slower to converge (the edit saved by F5)
edited = .true.
call test_key('f5')
call frames(3_int32)
do k = 1_int32, 1000000_int32
   if (.not. started) exit
   call frames(1_int32)
enddo
do k = 1_int32, 1000000_int32                     ! and its field read: the Result panel comes forward with it,
   if (size(field) > 0) exit                      ! at a time of the task's, not of the test's
   call frames(1_int32)
enddo
call test_click(runs_tab_at(1), runs_tab_at(2))   ! the Runs tab
call frames(6_int32)
call test_click(header_at(1), header_at(2))       ! the iterations' header: fewest first
call frames(6_int32)
call check(size(runs) == 2 .and. runs(order(1))%iterations < runs(order(2))%iterations .and. order(1) == 1, &
           'two runs in the table, sorted by iterations on a click of its header')
call test_click(header_at(1), header_at(2))       ! again: most first
call frames(6_int32)
call check(order(1) == 2 .and. sort_down, 'a second click reverses the order')
call test_click(row_at(1), row_at(2), button='right') ! a right click on the first row
call frames(6_int32)
call test_popup_rect(r(1), r(2), r(3), r(4), found)
call check(found, 'a right click on a run opens its menu')
call test_key('escape')
call frames(4_int32)
text
$ ./tut21_tables --test tut21-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]     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]     a click on a problem shows the Body section, the radius in keys
[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
23 of 23 checks passed

(The ig_end_tab line is the report of chapter 19's deliberate mistake.)

What you learned

A table with a frozen header that the user sorts and the program orders; a row coloured with a mark; a context menu and a tooltip holding a plot on a row; radio buttons; a drag box of two numbers; a slider on a log scale. Reference: Tables, Context menus, Tooltips, Numbers, Choices.

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

Next: 22. A sketch and a monitor: the plate drawn on a canvas, and the residuals with the solver's mean temperature on a second axis, a readout and an averaging window.

Released under the MIT licence.