19. Mistakes reported, keys that respect the focus
Part three makes the studio of part two a finished application: mistakes reported, keys and fields that behave, layouts and settings kept, help, and a test of its picture. This chapter starts with two things a user notices only when they go wrong: a mistake in the program's begin/end pairs, which used to abort the studio inside Dear ImGui, and keys that fired wherever the user was typing.
The whole program: tut19_checks.F90. It is chapter 18's studio with the changes below; tut19_checks --test DIR tests it, and the documentation's build runs that test (at the end of the page).
What this chapter adds to chapter 18's program, tut18_remote.F90:
report_usage: A usage error of the last frame, as a notification (in the Messages panel too); the same report is not repeated on every frame of the bug- changed:
draw_input,draw_menus,draw_panels,draw_result,draw_run,frames,self_test
A mistake reported, not a crash
FIGURE keeps a record of the scopes a frame opens, ig_begin to ig_end, ig_tree_node to ig_tree_pop, and checks every end against it before Dear ImGui sees it (Pairing and frames). A wrong end is refused, the frame goes on, and the next next_frame reports it: with stat, as a status the program decides about; without stat, by stopping with the message. The studio passes stat:
do while (app%next_frame(stat=stat)) ! with stat: a usage error is reported, the studio goes on
if (stat /= FIG_OK) call report_usage()
call draw_studio()
enddoif (figure_last_error() /= last_report) call app%notify(figure_last_error(), kind='error', seconds=0.0_real64)
last_report = figure_last_error() ! one line per error, naming the Fortran callsstat /= FIG_OKafter a frame with a usage error (FIG_ERR_STATE);figure_last_error()holds one line per error, each naming the Fortran call:ig_end_tab: no ig_begin_tab is open (no scope is open).- A bug in a panel repeats on every frame: the studio shows the report once, as a notification that stays until clicked (
seconds=0). FIGURE keeps the last 100 notifications (app%notifications, Notifications), which chapter 16's Messages panel lists: the report is there too, with the run's own messages. - This is mode
'report', the default.app%set_checks('abort')stops at the faulty call itself, the line to look at in a debugger; in'recover'a wrong end first closes the scopes opened after its own, then ends its own, and FIGURE notifies by itself (The three modes).
Before v0.4.0 the same mistake ended the program with an assertion inside imgui.cpp that named no Fortran call.
The test fails on any mistake
A usage error does not stop the studio, so a test must look for it. The test's frames(n) draws n frames as the main loop does (ended once next_frame says the studio ends), counts in usage_errors every frame that reports a usage error, and prints the report; the test ends with check(usage_errors == 0, ...):
do k = 1_int32, n
if (.not. app%next_frame(stat=stat)) then
ended = .true.
return
endif
if (stat /= FIG_OK) then ! a usage error in the frame before: the test says which
usage_errors = usage_errors + 1_int32
write(output_unit, '(A)') figure_last_error()
endif
call draw_studio()
enddoAnd it checks that a mistake is reported, with one made on purpose, in the test only:
if (app%next_frame(stat=stat)) then ! a frame with a mistake in it
call draw_studio()
call ig_end_tab() ! a stray end: no tab is open here
endif
if (app%next_frame(stat=stat)) call draw_studio() ! the next frame reports it, and the studio goes on
call check(stat == FIG_ERR_STATE .and. index(figure_last_error(), 'ig_end_tab: no ig_begin_tab is open') > 0, &
'a stray ig_end_tab is reported by the next frame, naming the call')
write(output_unit, '(A)') ' '//figure_last_error()Keys that respect the focus
In part two every ig_shortcut fired wherever the user was. From v0.4.0 a chord is routed: the default scope, 'focused', fires a call made inside a window only while that window (or a region of it) has the keyboard focus, and never while a text field is being edited with a key the field uses (Shortcuts). The application's keys of chapter 9, ctrl+o, ctrl+s, ctrl+q, f1, f5 and shift+f5, are called outside every window: they keep firing wherever the focus is. The panels' keys move into the panels.
The Result panel's arrows. Left and right move the probe line one node; repeat=.true. keeps moving it while the key is held. Inside draw_result, they fire only while Result has the focus: in the title field, right moves the field's cursor, and the probe line stays.
if (ig_shortcut('left', repeat=.true.)) probe_x = max(0.0_real64, probe_x - flx / (size(field, 1) - 1)) ! a node
if (ig_shortcut('right', repeat=.true.)) probe_x = min(flx, probe_x + flx / (size(field, 1) - 1)) ! left, rightUndo in the Input panel. ctrl+z takes back a form edit while Input has the focus. In the text of heat.inp, a multi-line field, ctrl+z is the field's own undo: a text field keeps the chords it uses itself, whatever the scope.
if (ig_shortcut('ctrl+z')) then ! focused: only while Input, or a region of it, has the focus
if (form_shown) call undo() ! (in the text, ctrl+z is the text field's own undo)
endifA button that owns F5. ig_set_next_item_shortcut gives the next item a chord: F5 presses the Run button as a click would, and the button's tooltip shows the chord. scope='global' keeps it working wherever the focus is; while the button is disabled (a run going on, a problem in the input) it is not pressed. The application's own F5, outside every window, stays for when the Run panel is closed or behind another tab: while the button is drawn, its 'global' route takes the chord before the 'focused' call outside the windows, and one press starts one run.
call ig_set_next_item_shortcut('f5', scope='global') ! the button owns F5, wherever the focus is; its tooltip says so
if (ig_button(ICON_PLAY//' Run')) call start_run()The calls are made every frame, whatever the program expects: Dear ImGui gives a chord, on the frame it arrives, to the call that best matches where the user is, and a call made only now and then has no route.
One more fix that the focus asked for. Part two brought the Result panel forward when a field had been read (show_result). The field is read by a task, and its end can come while the user types in a field: the panel took the focus, and the edit was lost. Chapter 19 waits until no item is active (laid_out is true on the frame the layout gave the focus to Input itself):
if (show_result .and. .not. laid_out .and. .not. ig_any_item_active()) then ! not while the user types or drags
show_result = .not. ig_focus_window('Result') ! a result read comes forward (not while a popup is open)
endifig_any_item_active() is true while some item is held or edited (What happened to an item); chapter 20 uses the rest of that family.
The test
$ ./tut19_checks --test tut19-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] typing edits the title, 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] an input with the body out of the plate is refused
[ok] and accepted once corrected
[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
17 of 17 checks passedright is pressed with test_key('right') after the field's task brought Result forward, then again with the title field clicked: the probe line moves the first time only. The stray ig_end_tab is reported with the message above; every other frame of the test is clean.
What you learned
next_frame(stat) reports the frame's usage errors by the names of the Fortran calls; a notification shows them once; a test counts them. Keys are routed: 'focused' inside a panel, application keys outside every window, a button that owns its chord with ig_set_next_item_shortcut, 'global' for a key that works everywhere. Reference: Pairing and frames, Shortcuts.
Run it: build it as chapter 7 shows (with tut12_heat beside it), then ./tut19_checks --examples /tmp/studio --case /tmp/studio/plate.
Next: 20. Fields, lists and sizes: a field that commits when it is left, the keyboard focus sent to the field a problem names, and sizes in em.