Menus, popups and shortcuts
Menus
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| Procedure | Notes |
|---|---|
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:
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()shortcutis text shown on the right of the item, nothing more: the keys are read byig_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
| Procedure | Notes |
|---|---|
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.)
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 focuskeys 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:
atoz,0to9,f1tof12,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.
scope | Who receives the chord | Two calls of one chord | While 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'sKeyRepeatDelay, 0.275 s, then everyKeyRepeatRate, 0.05 s); releasing or changing a modifier stops it. Without it, once per press.- macOS:
ctrlis 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
shortcuttext 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
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')
endifig_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
if (ig_input_text('command', command)) continue
if (ig_shortcut('f1', scope='item')) call did('f1: help on the command field') ! while it is editedif (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:
$ ./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 helpOn 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_ARGUMENTinstat: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"); alsomore than one key in "..."andno key besides the modifiers in "...".ig_shortcutthen returns.false., and the next item has no chord. Withoutstat, 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_shortcutdoes 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
shortcuttext, and an item's tooltip withig_set_next_item_shortcut, are the only places.
Popups and modals
A popup is opened once, by an event, and declared every frame:
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| Procedure | Notes |
|---|---|
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
| Procedure | Notes |
|---|---|
ig_begin_popup_context(id [, on] [, button] [, stat]) → logical | A 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.)
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 whileon | Opens 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 |
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 noig_open_popupto 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 insideig_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), onig_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_popuponly after a true begin, as for every popup; a wrong end is refused and reported, the message namingig_begin_popup_context('row')(Pairing and frames).button:'right','left'or'middle'. - Status: an unknown
onorbuttonreturns.false.and givesFIG_ERR_ARGUMENTinstat:ig_begin_popup_context: unknown place "row" ('item', 'window' or 'void'),ig_begin_popup_context: unknown button "back" ('right', 'left' or 'middle');statis optional (absent:error stopwith the message, Error handling). With no frame open, or from a task, it is refused withFIG_ERR_STATE. - Window: the mouse. Headless:
test_click(x, y, button='right')(Synthetic input);test_popup_recttells 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 anig_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):
$ ./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-copyMessage boxes
A question the user answers with a button (quit or not, overwrite or not), or a message to acknowledge, in one call:
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| Procedure | Notes |
|---|---|
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,textandbuttonsreplace 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):
$ ./cb_message_box
save first
saved: OK
quitA 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
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| Procedure | Notes |
|---|---|
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):
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.)
| Procedure | Notes |
|---|---|
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=:), allocatable | The 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).