Skip to content

Menus, popups and shortcuts ​

docs/examples/src/cb_menu.F90: the File menu, its shortcut and a check-mark item
fortran
if (ig_begin_main_menu_bar()) then
   if (ig_begin_menu('File')) then
      if (ig_menu_item('Save', shortcut='Ctrl+S', enabled=edited)) call save()
      if (ig_menu_item('Autosave', selected=autosave)) continue
      call ig_separator()
      if (ig_menu_item('Quit')) running = .false.
      call ig_end_menu()
   endif
   call ig_end_main_menu_bar()
endif
if (ig_shortcut('ctrl+s') .and. edited) call save()     ! every frame, outside the menu
ProcedureNotes
ig_begin_main_menu_bar() → logical, ig_end_main_menu_bar()The bar along the top of the display; with decorations='figure', inside the window's title bar (Frame loop).
ig_begin_menu_bar() → logical, ig_end_menu_bar()A window's own bar: the window needs ImGuiWindowFlags_MenuBar in its ig_begin.
ig_begin_menu(label [, enabled]) → logical, ig_end_menu()A menu of a bar, or a submenu of a menu; .true. while open.
ig_menu_item(label [, shortcut] [, selected] [, enabled]) → logical.true. on the frame the item is picked; the menu closes.

ig_begin_main_menu_bar ... ig_end_main_menu_bar is the bar of the display, ig_begin_menu ... ig_end_menu a menu in it, ig_menu_item an entry. Each end follows only a begin that returned .true. (Dear ImGui's rule for menus, as for tabs and tables; windows differ: ig_end follows every ig_begin).

A window's own bar is ig_begin_menu_bar ... ig_end_menu_bar, inside a window begun with ImGuiWindowFlags_MenuBar; it holds menus, or items straight in the bar:

fortran
if (ig_begin('Case', flags=ImGuiWindowFlags_MenuBar)) then     ! the window has a bar of its own
   if (ig_begin_menu_bar()) then
      if (ig_menu_item('Reload')) continue                  ! an item in the bar, or a menu (ig_begin_menu)
      call ig_end_menu_bar()                                ! only after a true ig_begin_menu_bar
   endif
   call ig_text('the case')
endif
call ig_end()
  • shortcut is text shown on the right of the item, nothing more: the keys are read by ig_shortcut.
  • With selected, the item shows a check mark when .true., and picking it toggles the variable.
  • A disabled item (enabled=.false.) is greyed out and cannot be picked; a disabled menu cannot be opened.

Shortcuts ​

docs/examples/src/cb_shortcuts.F90: the same chord in two panels, keys held by a text field, a global key owned by a button
ProcedureNotes
ig_shortcut(keys [, scope] [, repeat] [, stat]) → logical.true. on the frame the chord keys is pressed and routed to this call.
ig_set_next_item_shortcut(keys [, scope] [, stat])The next item owns the chord: the chord presses it, and its tooltip shows the chord.

(Dear ImGui's Shortcut and SetNextItemShortcut, with the ImGuiInputFlags_Route* flags and ImGuiInputFlags_Repeat.)

fortran
if (ig_shortcut('down')) call did('down: next block', sel + 1_int32) ! this window, not while a field is edited
if (ig_shortcut('up')) call did('up: previous block', sel - 1_int32)
if (ig_shortcut('ctrl+s')) call did('ctrl+s: the blocks saved')     ! only when this window has the focus

keys is a chord: modifiers and one key, joined by +: 'ctrl+s', 'ctrl+shift+z', 'f5', 'escape', 'down'. The names are those of test_key:

  • keys: a to z, 0 to 9, f1 to f12, enter, tab, backspace, delete, escape, space, left, right, up, down, home, end, pageup, pagedown;
  • modifiers: ctrl, shift, alt, super.

Other keys (f13 and up, the keypad, punctuation) have no name: a chord with one is refused (FIG_ERR_ARGUMENT).

Routing. A chord goes to one place. Every routed call ('focused', 'global', 'item') asks for the chord with a scope; Dear ImGui gives the chord, on the next frame, to the window (or the item) whose call matches best where the user is, and only the calls made there return .true.. So the calls are made every frame, whether or not the program expects the key: a call made only now and then has no route on the frame the key arrives. The order of the calls in a frame does not matter, except between two 'global' calls (below). 'always' is not routed (Dear ImGui's IsKeyChordPressed): every call of the chord fires, wherever it is made and whatever has the focus.

scopeWho receives the chordTwo calls of one chordWhile a text field is edited
'focused' (default)The window the call is made in, while it has the keyboard focus, or a window inside it (a child region) does and does not take the chord itself. Outside every window (after the last ig_end, the place of an application's own keys): whatever window has the focus, unless the focused window asks for the same chord, so a panel overrides the application's key while it has the focus.In two windows: the focused one's fires, the other does not.A chord of one key alone or with shift, other than the function keys, does not fire (the field uses it); chords with ctrl, alt or super, and the function keys, fire.
'global'Wherever the focus is, before the 'focused' calls of the same chord.The first 'global' call of the frame fires; the others do not.Keys that type a character do not fire (Dear ImGui's rule); the others fire.
'item'The item drawn just before the call, while it is active: a text field being edited, a button held down; before every other call of the chord.Only the active item's call fires.Fires: keys for the field being edited, such as f1 for its own help.
'always'Every call, wherever it is made: no route, whatever has the focus (v0.3's ig_shortcut).Every call fires.Fires, the field's own keys included: the field acts on the key too.
  • Text fields keep their keys. While a text field is edited, a 'focused' chord of one key alone or with shift, such as 'down', 'enter', 'escape', 'home' or 'shift+left', does not fire: the field uses them (left, right, home and end move its cursor, enter and escape end the edit; in a one-line field, up and down move Dear ImGui's keyboard navigation to the widget above or below, ending the edit). Chords with ctrl, alt or super, and the function keys ('f1' to 'f12'), still fire. Keys that type a character ('a', 'space', 'shift+1') do not fire for 'global' calls either (Dear ImGui's own rule). The chords a field routes itself (enter, ctrl+enter, shift+enter, ctrl+a, ctrl+c, ctrl+v, ctrl+x, ctrl+z, ctrl+y) stay the field's, for every routed scope. Keys for the field being edited go to an 'item' call after it. An 'always' call fires on all of these, as the field acts on them: it is for a key that must act everywhere, such as an emergency stop, and for v0.3's behaviour.
  • repeat=.true. fires again while the chord is held, at the keyboard's repeat rate (Dear ImGui's KeyRepeatDelay, 0.275 s, then every KeyRepeatRate, 0.05 s); releasing or changing a modifier stops it. Without it, once per press.
  • macOS: ctrl is the cmd key there, as for every shortcut in Dear ImGui, so 'ctrl+s' is cmd+s for a macOS user, with no change to the program. In remote mode the browser on a Mac sends cmd as ctrl for the same reason.
  • Menus: call it outside the menus. A menu is closed most of the time, and a menu item's shortcut text does nothing by itself.
  • In a test, press the platform's shortcut key with test_key('shortcut', down=.true.): cmd on macOS, ctrl elsewhere. test_key('ctrl') is the physical ctrl key, which on macOS is not the shortcut key. A window gets the focus from a click on it (its title bar, to touch no widget).

Changed in v0.4.0, corrected in v0.5.0

Until v0.3.1 ig_shortcut fired on every call, whatever had the focus (it called Dear ImGui's IsKeyChordPressed, which does no routing): xall_figure's up and down keys moved its list while the user typed in a text field, and two panels binding ctrl+s both saved. From v0.4.0 the default scope is 'focused'. A call outside every window, the usual place of an application's ctrl+s, ctrl+q or f1, keeps firing whatever has the focus. A call inside a window fires only while that window has the focus.

v0.3's behaviour is scope='always' (from v0.5.0): every call fires, whatever has the focus, a text field being edited included. v0.4.0's text of this box named 'global' instead; it is not the same: 'global' routes the chord to one call, so of two 'global' calls of one chord only the first of the frame fires, and a key that types a character does not fire while a field is edited. For one key that must work everywhere, 'global' is the routed choice; for two calls of one chord that must both fire, or for v0.3's behaviour exactly, 'always'.

A button that owns a key ​

fortran
call ig_set_next_item_shortcut('f5', scope='global')               ! f5 presses Run, wherever the focus is
if (ig_button('Run')) then
   runs = runs + 1_int32
   call did('Run pressed')
endif

ig_set_next_item_shortcut is called right before the item, every frame. The chord presses the item as a click would (a button returns .true., a checkbox toggles, a text field takes the keyboard), with the same scopes as ig_shortcut, except 'item' and 'always': the item owns the chord through a route. The item's tooltip shows the chord when the pointer rests on it. While a text field is edited, a 'focused' item does not take a chord of one key alone or with shift, as above.

A key for one field ​

fortran
if (ig_input_text('command', command)) continue
if (ig_shortcut('f1', scope='item')) call did('f1: help on the command field') ! while it is edited
fortran
if (ig_shortcut('f1')) call did('f1: the general help') ! outside every window: unless a window takes f1

'item' routes the chord to the item drawn just before the call, while it is active, before every other call of the chord: f1 in the command field gives the field's help, f1 anywhere else the general one. The program runs headless with --check and presses the keys itself:

text
$ ./cb_shortcuts --check
frame 11: down: next block, selected: fuselage
frame 17: ctrl+s: the blocks saved
frame 47: ctrl+s: the log saved
frame 59: Run pressed
frame 71: f1: help on the command field
frame 83: f1: the general help

On frame 29 (not shown) down was pressed in the name field: the block list did not move (the keyboard navigation went from the field to the Run button below it). On frame 53 the Log panel had the focus: the block list's down did not fire.

Status, modes and threads ​

  • Status: an unknown key or scope is FIG_ERR_ARGUMENT in stat: ig_shortcut: unknown key "nosuchkey" in "ctrl+nosuchkey", ig_shortcut: unknown scope "window" ('focused', 'global', 'item' or 'always'), ig_set_next_item_shortcut: unknown scope "item" ('focused' or 'global') (and the same for "always"); also more than one key in "..." and no key besides the modifiers in "...". ig_shortcut then returns .false., and the next item has no chord. Without stat, the program stops with the message (Error handling). With no frame open, or from a task: FIG_ERR_STATE (Pairing and frames). Neither procedure opens a scope.
  • Window: the keyboard of the window. Headless: the keys of test_key. Remote: the browser's keys; a browser keeps some chords for itself (Known issues).
  • Threads: the frame loop's thread only; a task is refused (FIG_ERR_STATE), as every drawing call.
  • Disabled: inside ig_begin_disabled/ig_end_disabled, ig_shortcut does not fire and a disabled item is not pressed by its chord.
  • What it does not do: no key sequences (ctrl+k then ctrl+c), no chords of two keys besides the modifiers, no mouse buttons; the routing is Dear ImGui's, by window and item, not by the program's own areas inside a window (use a child region to give an area its own focus). FIGURE does not show a key's binding anywhere by itself: a menu item's shortcut text, and an item's tooltip with ig_set_next_item_shortcut, are the only places.

Popups and modals ​

A popup is opened once, by an event, and declared every frame:

fortran
if (ig_button('Options')) call ig_open_popup('options') ! once, on the click
if (ig_begin_popup('options')) then                     ! every frame; closes on a click outside
   if (ig_checkbox('verbose output', verbose)) continue
   call ig_end_popup()
endif
ProcedureNotes
ig_open_popup(id)Open the popup id: once, on the event (a click, a quit request), not every frame.
ig_begin_popup(id) → logical, ig_end_popup()A popup without a title bar; .true. while open. It closes on a click outside it.
ig_begin_popup_modal(title [, open]) → logical, ig_end_popup()A modal dialog: the rest of the interface is greyed out and ignores input while it is open. Its size fits its content; with open, a close button.
ig_close_current_popup()Close the popup or modal being declared: call it inside, on its OK or Cancel.

ig_begin_popup is a popup that a click outside closes; ig_begin_popup_modal is a modal dialog, titled, that keeps the rest of the interface from taking input until the program closes it with ig_close_current_popup (or the user with its close button, given open): a question that needs an answer. ig_end_popup follows only a begin that returned .true., of either kind. Open and begin use the same id, in the same window (the id is scoped like a widget's label). A menu that opens on a right click, with no ig_open_popup, is a context menu. A wrong end (after a false begin, or with another scope innermost) is refused and reported: Pairing and frames.

Context menus ​

docs/examples/src/cb_context_menu.F90: a menu on each row, one on the list's empty space, a tooltip with a table
ProcedureNotes
ig_begin_popup_context(id [, on] [, button] [, stat]) → logicalA menu that opens itself on a click of button (default 'right') over the place on names; .true. while open: declare its entries, then ig_end_popup().

(Dear ImGui's BeginPopupContextItem, BeginPopupContextWindow with ImGuiPopupFlags_NoOpenOverItems, and BeginPopupContextVoid.)

fortran
do i = 1_int32, rows
   call ig_push_id(i)                                ! each row's menu has its own id
   if (ig_selectable(trim(names(i)), .false.)) continue
   if (ig_begin_popup_context('row')) then          ! a right click on the row just drawn
      call ig_text_disabled(trim(names(i)))
      call ig_separator()
      if (ig_menu_item('Insert below', enabled=rows < MAX_ROWS)) call ask('insert', i)
      if (ig_menu_item('Duplicate', enabled=rows < MAX_ROWS)) call ask('duplicate', i)
      if (ig_menu_item('Copy name')) call ig_set_clipboard(trim(names(i)))
      if (ig_menu_item('Delete')) call ask('delete', i)
      call ig_end_popup()
   endif
   call ig_same_line(ig_em(8.0_real64))             ! the condition in a column of its own
   call ig_text_disabled(trim(kinds(i)))
   call ig_pop_id()
enddo
call apply()                                       ! the list changes after it is drawn, not while
onOpens on a click
'item' (default)over the item drawn just before the call: a selectable row, a tree node, a button, a text (any item, interactive or not)
'window'over the current window's empty space, not over its items: the items keep their own menus
'void'over the display's background, where no window is: call it outside every window
fortran
if (ig_begin_popup_context('list', on='window')) then ! the window's empty space, not over a row
   if (ig_menu_item('Add a row', enabled=rows < MAX_ROWS)) call ask('add', rows)
   call ig_end_popup()
endif
call apply()
  • Declared every frame. Unlike ig_begin_popup, there is no ig_open_popup to call: the call itself opens the menu when the button is released over its place (a click, as Dear ImGui's popups open on the release), and draws it while it is open. Call it every frame, right after the item for 'item', anywhere in the window for 'window'.
  • The id names the menu in the current id scope, as a widget's label: the rows of a list, which share one id 'row', each get their own menu inside ig_push_id(i). ig_open_popup(id), in the same window and id scope, opens the same menu from the program (a key, a button).
  • It closes on a pick of an ig_menu_item (or of an item of a submenu), on ig_close_current_popup() inside it, on a click outside it, or on escape. Any widget can go in it, not only menu items: a check box, a field, a submenu (ig_begin_menu).
  • Act after the loop. An entry that inserts or deletes rows is picked while the list is being drawn: change the list after the loop that draws it (the example records the request and applies it after enddo), not inside it.
  • Pairing: ig_end_popup only after a true begin, as for every popup; a wrong end is refused and reported, the message naming ig_begin_popup_context('row') (Pairing and frames). button: 'right', 'left' or 'middle'.
  • Status: an unknown on or button returns .false. and gives FIG_ERR_ARGUMENT in stat: ig_begin_popup_context: unknown place "row" ('item', 'window' or 'void'), ig_begin_popup_context: unknown button "back" ('right', 'left' or 'middle'); stat is optional (absent: error stop with the message, Error handling). With no frame open, or from a task, it is refused with FIG_ERR_STATE.
  • Window: the mouse. Headless: test_click(x, y, button='right') (Synthetic input); test_popup_rect tells where the menu is. Remote: the browser's right button (the page keeps the browser's own context menu away from the canvas).
  • Threads: the frame loop's thread only; a task is refused (FIG_ERR_STATE), as every drawing call.
  • What it does not do: no menu on a keyboard key of its own (the menu key, shift+f10): open it with ig_open_popup(id) from an ig_shortcut; no menu over a part of an item (a cell of a table is an item when it holds a widget); 'void' does not fire over a window, including a window that covers the whole display. A right click does not select the row: do it in the menu's first frame if the list needs it.

The program checks itself headless (cb_context_menu --check):

text
$ ./cb_context_menu --check
frame 12: right click on outlet, its menu open: T
frame 20: Duplicate: inlet, outlet, outlet-copy, wall, symmetry
frame 36: Delete on inlet: outlet, outlet-copy, wall, symmetry
frame 36: pointer over a row: F
frame 44: right click below the rows, the list's menu open: T
frame 52: Add a row: outlet, outlet-copy, wall, symmetry, patch-1
frame 53: pointer on outlet, tooltip shown: F, row under the pointer: 1
frame 60: pointer on outlet, tooltip shown: F, row under the pointer: 1
frame 75: pointer on outlet, tooltip shown: T, row under the pointer: 1
frame 88: help link clicked, help shown: T
frame 96: documentation link clicked, opened: https://szaghi.github.io/figure/
frame 112: Copy name on row 2, the clipboard: outlet-copy

Message boxes ​

A question the user answers with a button (quit or not, overwrite or not), or a message to acknowledge, in one call:

fortran
if (app%quit_requested()) asking = .true.
if (asking) then                                         ! every frame until answered
   answer = app%message_box('quit', 'Quit?', 'The case has unsaved changes.', &
                            [character(len=10) :: 'Quit', 'Save first', 'Cancel'])
   select case (answer)
   case (0)                                              ! still open
   case (1)
      write(output_unit, '(A)') 'quit'
      asking = .false.
      call app%quit()
   case (2)
      write(output_unit, '(A)') 'save first'
      asking = .false.
      saving = .true.                                    ! a message, then the question again
   case default
      write(output_unit, '(A)') 'cancelled'
      asking = .false.
   endselect
endif
ProcedureNotes
app%message_box(id, title, text [, buttons] [, stat]) → integer(int32)0 while the box id is open, then the button chosen (from 1), once.
  • Polled. Call it every frame while waiting for the answer. The first call opens the box; later calls return 0 (their title, text and buttons replace the box's, so a count can change while it is shown); once the user chooses, the next call returns the button's number and the box is gone: the id is free for another question. The box stays open until answered, whether it is called again or not.
  • Drawn by FIGURE after the program's windows, as the notifications are: a modal centred in the work area, titled title, its text wrapped at 28 times the font size, its buttons (default 'OK') in a row, each at least 5 em wide. While it is open the rest of the interface takes no input. Enter chooses the first button, Escape the last.
  • Several at once. Each new box opens over the ones before it, two font sizes lower and to the right, the newest on top and answered first; each returns its own button. (A single global box, as giu has, cannot ask a second question while the first is open.)
  • A popup of the program's (an open menu, its own modal, the file browser): the box waits for it to close, not drawn, since Dear ImGui keeps one popup per level and opening the box would close the program's.

docs/examples/src/cb_message_box.F90 answers the question with Save first, acknowledges the message that follows, then quits, headless (figure_test_app answers two boxes open at once):

text
$ ./cb_message_box
save first
saved: OK
quit

A test answers a box by clicking its button by path: '<title>/<button>' (test_item_click('Quit?/Save first')).

Status. stat is optional (absent: error stop with the message). FIG_ERR_ARGUMENT: app%message_box: the id is empty, app%message_box: every button label is empty; FIG_ERR_STATE: app%message_box: figure is not initialized, and from a task (a task does not draw). Modes: the same in window, headless and remote modes. Threads: the frame loop's thread.

What it does not do. No icon, no text field, no check box ("do not ask again": keep that in a preference and skip the call). The box's buttons are labels only: give them the words of the answer ('Overwrite', not 'Yes').

Ask before quitting ​

docs/examples/src/cb_quit.F90
fortran
if (app%quit_requested()) then                     ! the close button was clicked
   if (edited) then
      call ig_open_popup('Discard changes?')
   else
      call app%quit()                              ! nothing to lose
   endif
endif
if (ig_begin_popup_modal('Discard changes?')) then
   call ig_text('The document has unsaved changes.')
   if (ig_button('Save')) then
      edited = .false.                             ! (save here)
      call app%quit()
   endif
   call ig_same_line()
   if (ig_button('Discard')) call app%quit()
   call ig_same_line()
   if (ig_button('Cancel')) call ig_close_current_popup()
   call ig_default_focus()                         ! the safe button: enter or space presses it
   call ig_end_popup()
endif
ProcedureNotes
app%set_confirm_quit(enabled)With .true., the window's close button (and the system's quit) no longer ends next_frame.
app%quit_requested() → logical.true. once per request: open the dialog then.
app%quit()The next next_frame returns .false. (every mode).

app%set_confirm_quit(.true.) turns the close button into a request: app%quit_requested() reports it once, the program asks (Save, Discard, Cancel), then calls app%quit() or carries on; from which threads they may be called: next_frame. A test makes the request with test_quit() (Headless testing); a capture script with <frame> close (Frame capture).

The window's title ​

An editor shows the document in the window's title, with a mark while it has unsaved changes. Set it whenever it changes (the call is cheap; doing it every frame is fine):

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

(The tutorial's studio, chapter 10, calls it whenever the case is opened, edited or saved.)

ProcedureNotes
app%set_title(text [, stat])The window's title after init. Shown in window mode; kept in remote and headless modes.
app%title() → character(len=:), allocatableThe title: init's, or the last set_title ('' headless until set).

app%set_title shows the text in the window's title bar, or in FIGURE's own bar with decorations='figure' (The window's frame).

Released under the MIT licence.