Skip to content

8. The studio's own window ​

Part two of the tutorial builds one application, chapter by chapter: a small solver studio, which opens a case, edits its input, runs a solver, follows its residuals and shows the field it computed. Each chapter's program is the previous one with something added; the page shows what is new, and links the whole program.

The studio starts with its window. A desktop program's frame (the title bar, its buttons, the edges that resize it) is normally the system's: GNOME's, KDE's, Windows', macOS', or Weston's under WSLg, each with its own colours and buttons, and under X forwarding the frame of the machine that shows the window. With decorations='figure' FIGURE draws the frame itself, in the colours of the studio's palette, with the menus inside the title bar: the studio looks the same wherever it runs.

docs/examples/src/tut08_window.F90

The whole program: tut08_window.F90.

What this chapter adds: the studio's first program, tut08_window.F90, its procedures:

  • open_window: Open the studio's window, its frame drawn by FIGURE
  • draw_studio: One frame of the studio
  • frame_map: Draw the studio headless, with the same frame, and print what each point of its window does
  • frames: Draw n frames of the studio
  • print_map: One character per cell of 8 x 6 pixels
  • mark: The map's character for the point (x, y)
  • in_part: The point (x, y) is in a part of the title bar

The window ​

fortran
call app%init('FIGURE studio', 960_int32, 600_int32, decorations='figure', buttons=side) ! FIGURE draws the frame
call app%set_icon(ICON_FLAME, stat=stat)          ! the task bar's icon, and the title bar's
if (stat /= FIG_OK) write(output_unit, '(A)') 'no window icon here: '//figure_last_error() ! the bar keeps its own
call app%set_confirm_quit(.true.)                 ! the close button asks the program first
  • decorations='figure' opens the window without the system's frame (borderless, still resizable) and draws a title bar on top of it: the window's icon, the program's menus, the title centred, and the minimize, maximize (restore) and close buttons. The system's frame stays the default (decorations='native').
  • buttons=side: 'right' or 'left'. The studio passes its optional argument along, so when side is absent the buttons are on the platform's side: on the left on macOS, on the right elsewhere.
  • app%set_icon(ICON_FLAME) is the window's icon in the task bar or the dock, and the bar's, in the palette's accent. Any of the bundled icons will do, or an RGBA image of your own.
  • stat=stat keeps the program going where the system has no window icons (a Wayland compositor without the xdg-toplevel-icon protocol, SDL's offscreen driver): set_icon then returns FIG_ERR_FAILED with SDL's reason in figure_last_error(), and the bar shows the icon all the same. Without stat the program would stop there (known issues). When a call fails has the rule; chapter 16 comes back to stat.
  • app%set_confirm_quit(.true.): the close button no longer ends the program; it asks the program first (below).

The menus inside the title bar ​

fortran
if (ig_begin_main_menu_bar()) then                ! inside the title bar, after the icon
   if (ig_begin_menu('File')) then
      if (ig_menu_item('Quit')) ask_quit = .true.  ! the same question as the close button, asked below
      call ig_end_menu()
   endif
   call ig_end_main_menu_bar()
endif

The program declares its menus as it would for the system's frame, with ig_begin_main_menu_bar (Dear ImGui's BeginMainMenuBar); FIGURE puts them into the title bar, after the icon. The title moves right when the menus reach the centre. Chapter 9 fills the menus.

A question before the window closes ​

fortran
if (app%quit_requested() .or. ask_quit) then      ! the close button was clicked, or File > Quit
   call ig_open_popup('Quit the studio?')        ! here, outside the menu: the popup's id is the modal's
   ask_quit = .false.
endif
if (ig_begin_popup_modal('Quit the studio?')) then
   asking = .true.
   call ig_text('The studio closes.')
   if (ig_button('Quit')) call app%quit()         ! the next next_frame returns .false.
   call ig_same_line()
   if (ig_button('Cancel')) call ig_close_current_popup()
   call ig_end_popup()
endif
  • app%quit_requested() is .true. once per click on the close button (or Alt+F4, or the dock's Quit).
  • The question is a modal popup (Popups and modals): ig_open_popup once, on the event; ig_begin_popup_modal every frame, which is .true. while it is open. FIGURE's app%message_box asks such a question in one call (Message boxes); the studio draws its own, to learn popups.
  • app%quit() ends the loop below: the next next_frame returns .false..
  • File > Quit asks the same question, but it does not open the popup from inside the menu: a popup's name is scoped by the window it is opened in, and inside the menu it would name another popup than the modal declared at the top level. The menu item sets ask_quit; the popup is opened next to the modal.
fortran
do while (app%next_frame())                          ! .false. once the user confirmed the quit
   call draw_studio()
enddo
call app%destroy()

What the frame does ​

The system still moves and resizes the window; it asks the program, point by point, what the window is there (SDL_SetWindowHitTest), and FIGURE answers from the last frame drawn:

  • the empty part of the bar, the title and the icon drag the window;
  • a double-click there maximizes it, and another restores it;
  • the edges (6 pixels, times the display's content scale) and the corners (twice that along each side) resize it; a maximized window has none;
  • the buttons and the menus are the program's, like everything below the bar.

The buttons can go on the left, as on macOS, with buttons='left' (here tut08_window --left):

The same title bar with the buttons on the left: close, hovered and red, then minimize and maximize, then the flame icon and the File menu; the title stays centred
docs/examples/src/tut08_window.F90, run as tut08_window --left

What the system's frame does and this one does not (Windows 11's snap layouts, macOS' full-screen button, the window menu) is listed in the known issues.

The frame without a display ​

Moving and resizing are the system's, so the recording above cannot show them. A headless run can: it draws the same frame on a virtual display, without a window, and figure_testing asks the frame what each point does. The studio does this when started as tut08_window --frame-map:

fortran
call app%init_headless(int(W, int32), int(H, int32), decorations='figure', buttons='right') ! the bar, no window
call app%set_confirm_quit(.true.)
call frames(3_int32)
call print_map()
call test_frame_rect('bar', r(1), r(2), r(3), r(4))
call test_click(0.5_real64 * (r(1) + r(3)), 0.5_real64 * (r(2) + r(4)))   ! a double-click on the bar
call test_click(0.5_real64 * (r(1) + r(3)), 0.5_real64 * (r(2) + r(4)))
call frames(10_int32)
call test_frame_state(minimized, maximized)
write(output_unit, '(A,L1,A,A)') 'double-click on the bar: maximized ', maximized, &
                                 ', the top-left corner: ', test_frame_hit(1.0_real64, 1.0_real64)
call test_frame_rect('close', r(1), r(2), r(3), r(4))
call test_click(0.5_real64 * (r(1) + r(3)), 0.5_real64 * (r(2) + r(4)))   ! the close button
call frames(6_int32)
write(output_unit, '(A,L1)') 'close: the question is shown ', asking
call app%destroy()
text
$ ./tut08_window --frame-map
/^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\\
/MMMM==========================================_____####XXX\
<MMMM==========================================_____####XXX>
<..........................................................>
<..........................................................>
<..........................................................>
<..........................................................>
<..........................................................>
<..........................................................>
<..........................................................>
\........................................................../
\vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv//
= drags the window   < > ^ v / \ resize it   M menus   _ # X the buttons   . the program
double-click on the bar: maximized T, the top-left corner: client
close: the question is shown T
  • init_headless(..., decorations='figure') draws the bar as in a window; the buttons' actions are recorded as state, and close is a quit request, as in a window.
  • test_frame_hit(x, y) gives the hit test's answer at a point: 'drag', 'client' (the program's), or a resize edge or corner. The map prints one character per cell of 8 x 6 pixels: the bar drags (=), the edges and corners resize, the menus (M) and the three buttons (_ # X) are the program's.
  • test_frame_rect(part, ...) gives a part of the bar ('bar', 'menus', 'close', ...) to aim at: test_click twice on the bar is a double-click, and test_frame_state reports the window maximized; the top-left corner is then no longer a resize corner. A click on close opens the studio's question.

Chapter 17 tests the whole studio this way. The recordings of this tutorial are made in a capture (Screenshots and videos): the frame is drawn in the window's back buffer with the rest, so it is in every picture.

What you learned

A window whose frame FIGURE draws: the icon, the title, the buttons on the platform's side, the menus inside the bar; what the bar and the edges do; the close button asking first; and the frame checked without a display. Reference: The window's frame, Ask before quitting, Icons, Headless testing.

Run it: build it as chapter 7 shows, then ./tut08_window.

Next: 9. The application's shell: menus with shortcuts, docked panels, looks and palettes.

Released under the MIT licence.