Skip to content

20. Fields, lists and sizes ​

Three habits of a finished application: a field that commits its value when the user leaves it, not at every key; a message about a problem that takes the user to the field it names; and sizes that follow the font, so that a larger font gives a larger studio, not a cramped one.

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

The whole program: tut20_layout.F90, chapter 19's studio with the changes below.

What this chapter adds to chapter 19's program, tut19_checks.F90:

  • problem_ids: The checks of problems that fail, in the same order
  • take_keys: Before a field
  • set_text_size: The default font at 15 pixels, or at 19 with View > Larger text
  • changed: draw_case, draw_checks, draw_dialogs, draw_form, draw_input, draw_menus, draw_result, draw_run, draw_status, draw_studio, draw_tools, section_node, self_test

A field that commits when it is left ​

Chapter 10's title field set edited and the window's title at every key, and escape, which gives the field back its text, still left the star in the title. ig_last_item() tells what happened to the item drawn last, in one item_status_object (What happened to an item): activated on the frame the field takes the keys, deactivated_after_edit on the frame it is left after a change (enter, tab, a click elsewhere).

fortran
if (ig_input_text('title', inp%title)) continue    ! the field edits the variable as the user types
call centre_of_last(title_at)                     ! for the test: where a user would click
last = ig_last_item()                             ! what happened to the field, in one snapshot
if (last%activated) title_before = inp%title       ! it took the keys: the title as it was
if (last%deactivated_after_edit .and. inp%title /= title_before) then ! left after an edit: commit it
   before = inp
   before%title = title_before
   call push_undo(before)                         ! one undo step for the whole edit, not one per key
   edited = .true.
   call show_title()
endif
  • The variable still follows every key (the field edits inp%title in place); what waits for the field to be left is what the studio does with it: the star, the window's title, and one undo step for the whole edit.
  • Escape gives the field back the text it had when it took the keys, and leaves it: inp%title equals title_before, so nothing is committed.
  • ig_last_item() describes the item drawn last: call it right after the field, before another widget.

The test checks both ways out of the field:

fortran
call test_click(title_at(1), title_at(2))         ! the title field, where the user clicks it
call frames(5_int32)
call test_type(' X')
call test_key('escape')                           ! leaves the field as it was
call frames(6_int32)
call check(trim(inp%title) == 'Heated plate' .and. .not. edited, 'escape leaves the title as it was, unedited')

A problem that takes you to its field ​

Chapter 16 listed the input's problems above the tree. Now each is a link (ig_text_link, drawn in the palette's error colour, with its [!!] mark): a click shows the problem's section, scrolls the tree to it and gives its field the keyboard.

fortran
do k = 1_int32, size(list, kind=int32)            ! a mark with the colour: never colour alone
   if (ig_text_link('[!!] '//trim(list(k)))) then ! a click: the section, scrolled to, its field given the keys
      section = SECTION_OF(ids(k))
      reveal = section
      focus_on = ids(k)
   endif
   if (k == 1_int32) call centre_of_last(problem_at)
enddo

The form gives the keys to the field right before drawing it:

fortran
if (focus_on /= check) return
call ig_focus_here()                              ! the next item takes the keys; applied on the next frame
focus_on = 0_int32

and the tree scrolls its node into view as it draws it:

fortran
if (reveal == n) then                             ! picked from a problem: the node scrolls into view
   call ig_scroll_here()                          ! its line to the centre of the region, on the next frame
   reveal = 0_int32
endif

In the video the plate's size is the problem and its lx field takes the keys; the test makes the body's radius too large and checks the radius field. ig_focus_here() gives the next item the keyboard focus, as a click would: a field is edited at once, its text selected. ig_scroll_here() scrolls the window or region drawn in so that the line of the item drawn last is at its centre. Both take effect on the next frame (Scrolling and focus). The test clicks the problem and checks the radius field has the keys: ig_last_item()%focused.

Sizes in em ​

Every size of part two was in pixels, chosen for the default font of 15 pixels: the side bar 76, the tree 170, the log 380. With a larger font the labels outgrew them. A size in em is a number of font sizes: ig_em(5) is 75 pixels at 15, 95 at 19 (Layout). The studio's sizes are all in em now:

fortran
bar_px = ig_em(5)                                 ! 5 em: 75 pixels at 15, 95 at 19
if (ig_begin_side_bar('tools', 'left', bar_px)) then
   do k = 1_int32, size(PANELS, kind=int32)
      if (ig_tool_button(trim(PANELS(k)), trim(ICONS(k)), width=ig_em(4), selected=current == k)) then
         current = k
         shown(k) = .true.
         if (ig_focus_window(trim(PANELS(k)))) continue
      endif
      call ig_tooltip('Show the '//trim(PANELS(k))//' panel')
   enddo
endif
call ig_end()

The status bar is one row of widgets high, ig_frame_height(), and a margin. View > Larger text sets the font to 19 pixels, and the next frame lays out everything again:

fortran
call app%set_font('plex-sans', merge(19.0_real64, 15.0_real64, large_text)) ! from the next frame on

The About box's Close button sits at its right edge, wherever the text makes the box end:

fortran
call ig_align_begin('close', 'right')          ! the button at the right edge: its width from the last frame
if (ig_button('Close')) call ig_close_current_popup()
call ig_align_end()

ig_align_begin(id, 'right') starts a group placed from its width in the previous frame: on the first frame a group is drawn where it starts and placed the frame after (FIGURE asks for that frame by itself). The Case panel's parameters have a title, ig_separator_text('Parameters').

The test ​

text
$ ./tut20_layout --test tut20-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]     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
20 of 20 checks passed

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

What you learned

ig_last_item() and its activated and deactivated_after_edit: commit on leave, one undo step per edit; ig_text_link for a message that acts; ig_focus_here and ig_scroll_here to take the user to an item; sizes in em with ig_em and ig_frame_height, a font changed at run time, ig_align_begin for a right-aligned button. Reference: What happened to an item, Scrolling and focus, Layout.

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

Next: 21. Tables that act: context menus on the boundaries, a sortable list of runs, numbers with drag boxes and radio buttons.

Released under the MIT licence.