Skip to content

10. The case ​

The studio works on a case: a folder with an input file, heat.inp, read by the studio and, from chapter 12, by the solver. This chapter opens a case, from FIGURE's file browser, from the system's dialog, or from a folder dropped on the window; it shows the case's title in the window's title, and asks before an open or a quit loses an edit.

The input file is a Fortran namelist, which both programs read with one statement:

text
&heat
  title = 'Heated plate'
  nx = 48, ny = 32, lx = 1.500, ly = 1.000
  bc_kind = 'fixed', 'insulated', 'fixed', 'fixed'  ! west, east, south, north
  bc_value = 100.000, 0.000, 20.000, 20.000
  body_x = 0.900, body_y = 0.500, body_r = 0.150, body_t = 0.000
  omega = 1.800, tolerance = 1.0E-06, max_iter = 4000
/

A plate of lx by ly metres, held at fixed temperatures or insulated on its four sides, with a round body at body_t inside it; the solver computes the steady temperature on an nx by ny grid. tut10_case --examples DIR writes two such cases, plate and channel, into DIR and starts the browser there.

docs/examples/src/tut10_case.F90, run as tut10_case --examples /tmp/figure-studio

The whole program: tut10_case.F90.

What this chapter adds to chapter 9's program, tut09_shell.F90:

  • browse_case: FIGURE's file browser, choosing a folder
  • take_answers: The answers that arrive on this frame
  • request: Open a case or quit, after asking whether to discard the changes if there are some
  • go_on: Do what was requested
  • open_case: Read the case of folder dir; a folder without an input file is not a case
  • save_case: Write the input back to the case's file
  • show_title: The window's title
  • add_recent: Put dir first in the recent cases
  • draw_case: The Case panel
  • case_folder: The case folder of a dropped path
  • read_case: Read a case's input, the namelist &heat of file
  • write_case: Write a case's input as the namelist &heat, one group of parameters per line
  • num: A number as the input file shows it
  • write_examples: Two example cases in folder, all modified on 2026-10-15 at fixed times (figure_set_file_time), for the pictures
  • date_cases: Every example case of folder and its input modified on 2026-10-15 at 09:10, local time, for the pictures
  • changed: draw_dialogs, draw_menus, draw_panels, draw_studio, open_window

Choosing a folder ​

fortran
if (ig_begin_menu('File')) then
   if (ig_menu_item(ICON_FOLDER_OPEN//' Open case...', shortcut='Ctrl+O')) call browse_case()
   if (ig_menu_item('Open case with the system''s dialog...')) then
      call app%open_folder_dialog('case', default_path=start_dir, stat=stat)
      if (stat /= FIG_OK) call browse_case()      ! no desktop (remote mode): FIGURE's browser
   endif
   if (ig_begin_menu(ICON_HISTORY//' Recent cases', enabled=nrecent > 0_int32)) then
      do k = 1_int32, nrecent
         if (ig_menu_item(trim(recent(k)))) call request('open', trim(recent(k)))
      enddo
      call ig_end_menu()
   endif
   if (ig_menu_item(ICON_SAVE//' Save', shortcut='Ctrl+S', enabled=edited)) call save_case()
   call ig_separator()
   if (ig_menu_item(ICON_POWER_SQUARE//' Quit', shortcut='Ctrl+Q')) ask_quit = .true.
   call ig_end_menu()
endif
fortran
call app%open_file_browser('case', default_path=start_dir, folders=.true.) ! answered on a later frame

Two kinds of dialog choose a file or a folder, and both answer through the same call (File dialogs):

  • FIGURE's file browser (app%open_file_browser), drawn by FIGURE as a modal over the program: the same in a window, in remote mode (chapter 18) and in a headless test (chapter 17). folders=.true. chooses a folder: files are shown dimmed, and Choose takes the selected folder or the one shown. The places on the left include the recent folders, which FIGURE keeps between runs.
  • The system's dialog (app%open_folder_dialog), the desktop's own. It needs a desktop: in remote and headless modes it is refused at once with FIG_ERR_STATE, and the studio opens the browser instead.

Neither blocks the program: the window keeps drawing, and the answer comes on a later frame.

Answers and drops ​

fortran
call app%file_dialog_result('case', chosen, done, cancelled, stat=stat) ! the browser's or the system's dialog
if (done .and. .not. cancelled) then
   if (stat == FIG_OK) then
      call request('open', chosen)
   else
      call app%notify(figure_last_error(), kind='error')                 ! the dialog could not be shown
   endif
endif
if (app%dropped(paths)) call request('open', case_folder(trim(paths(1)))) ! a case folder, or its heat.inp
  • app%file_dialog_result('case', path, done, cancelled, stat), every frame, is done once, on the frame the user answered, whichever kind of dialog was opened with the id 'case'. A system dialog that could not be shown answers with a failure in stat; the studio shows figure_last_error() in a notification (When a call fails).
  • app%dropped(paths) is .true. on the frame after files or folders were dropped on the window, with their absolute paths (Drops). The studio takes the first: a case folder, or a heat.inp, whose folder is the case.
  • Both go through request, which opens the case only if nothing is lost.

The case and its title ​

fortran
subroutine read_case(file, c, stat, msg)
!< Read a case's input, the namelist `&heat` of `file`.
character(len=*),              intent(in)  :: file        !< Input file.
type(case_t),                  intent(out) :: c           !< Its input (defaults where the file is silent).
integer(int32),                intent(out) :: stat        !< Status: 0 read.
character(len=:), allocatable, intent(out) :: msg         !< What went wrong.
character(len=64)                          :: title       !< Namelist copies of the components.
integer(int32)                             :: nx, ny, max_iter
real(real64)                               :: lx, ly, bc_value(4), body_x, body_y, body_r, body_t, omega, tolerance
character(len=12)                          :: bc_kind(4)
character(len=256)                         :: iomsg       !< The run time's message.
integer(int32)                             :: u           !< Unit.
namelist /heat/ title, nx, ny, lx, ly, bc_kind, bc_value, body_x, body_y, body_r, body_t, omega, tolerance, max_iter

title = c%title; nx = c%nx; ny = c%ny; lx = c%lx; ly = c%ly; bc_kind = c%bc_kind; bc_value = c%bc_value
body_x = c%body_x; body_y = c%body_y; body_r = c%body_r; body_t = c%body_t
omega = c%omega; tolerance = c%tolerance; max_iter = c%max_iter
msg = ''
open(newunit=u, file=file, status='old', action='read', iostat=stat, iomsg=iomsg)
if (stat /= 0) then
   msg = 'no '//INPUT_FILE//' in '//file(:max(0, len(file) - len(INPUT_FILE) - 1))
   return
endif
read(u, nml=heat, iostat=stat, iomsg=iomsg)
close(u)
if (stat /= 0) then
   msg = file//': '//trim(iomsg)
   return
endif
c = case_t(title, nx, ny, lx, ly, bc_kind, bc_value, body_x, body_y, body_r, body_t, omega, tolerance, max_iter)
endsubroutine read_case

read_case fills the namelist's variables with the defaults, reads the group &heat, and returns the run time's message (iomsg) when the file is missing or wrong: a folder that is not a case is reported in a notification, and the open case stays. Chapter 16 makes these messages the studio's error handling.

fortran
if (len(case_dir) == 0) then
   call ig_text_disabled('No case open.')
   call ig_text_wrapped('Open one with File > Open case, or drop its folder (or its heat.inp) on the window.')
   if (ig_button(ICON_FOLDER_OPEN//' Open case...')) call browse_case()
   return
endif
call ig_text(ICON_FOLDER//' '//case_dir)
if (ig_input_text('title', inp%title)) then        ! the field edits the variable in place
   edited = .true.
   call show_title()
endif
write(line, '(A,I0,A,I0,5A)') 'grid ', inp%nx, ' x ', inp%ny, ', plate ', num(inp%lx), ' m x ', num(inp%ly), ' m'
call ig_text(trim(line))
write(line, '(A,F0.2,A,ES7.1,A,I0)') 'omega ', inp%omega, ', tolerance ', inp%tolerance, ', at most ', inp%max_iter
call ig_text(trim(line))
call ig_begin_disabled(.not. edited)
if (ig_button(ICON_SAVE//' Save')) call save_case()
call ig_end_disabled()

ig_input_text('title', inp%title) edits the character variable in place, up to its length; it is .true. on the frame the text changes, and the studio marks the case as edited. The Save button is greyed out (ig_begin_disabled) while there is nothing to save.

fortran
if (edited) then                                  ! in the bar drawn by FIGURE, and the task bar's
   call app%set_title('* '//trim(inp%title)//' - FIGURE studio')
else
   call app%set_title(trim(inp%title)//' - FIGURE studio')
endif

app%set_title changes the window's title: in the bar FIGURE draws, and in the task bar. The star tells the user there are unsaved changes (The window's title).

Asking before discarding changes ​

fortran
pending_action = action
pending_dir = ''
if (present(dir)) pending_dir = dir
if (edited) then
   ask_discard = .true.                           ! the question is opened at the top level, in draw_dialogs
else
   call go_on()
endif
fortran
if (app%quit_requested() .or. ask_quit) then      ! the close button, File > Quit or ctrl+q
   ask_quit = .false.
   call request('quit')                           ! nothing to lose: quit at once
endif
if (ask_discard) then
   call ig_open_popup('Discard changes?')
   ask_discard = .false.
endif
if (ig_begin_popup_modal('Discard changes?')) then
   call ig_text('"'//trim(inp%title)//'" has unsaved changes.')
   if (ig_button(ICON_SAVE//' Save')) then
      call save_case()
      call ig_close_current_popup()
      call go_on()
   endif
   call ig_same_line()
   if (ig_button('Discard')) then
      call ig_close_current_popup()
      call go_on()
   endif
   call ig_same_line()
   if (ig_button('Cancel')) then
      pending_action = ''
      call ig_close_current_popup()
   endif
   call ig_end_popup()
endif
  • Opening another case and quitting both go through request: with no unsaved change it acts at once (the studio quits without a question now: there is nothing to lose); with one, it remembers the action and asks.
  • The question is a modal with three answers: Save, then go on; Discard, go on; Cancel, nothing happens. app%message_box would ask it in one call, with three buttons (chapter 8). The close button, File > Quit and ctrl+q all reach it, since app%set_confirm_quit(.true.) turns the close button into a request (Ask before quitting).
  • The recent cases, in File > Recent cases, are the studio's own list, for this session; the browser's recent folders are FIGURE's, kept between runs.

What you learned

A folder chosen with FIGURE's file browser or the system's dialog, the answer read on a later frame; folders and files dropped on the window; a namelist read with its error message; the window's title marking unsaved changes; and one question before an open or a quit discards them. Reference: File dialogs, FIGURE's file browser, Drops, Ask before quitting, Notifications.

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

Next: 11. The input editor: a tree of the input's sections, forms, a table, the input as text, undo.

Released under the MIT licence.