Docking
Docking is on by default. The user drags a window by its title bar onto another window, or onto a dock space, and drops it on one of the targets that appear. Dropped in the centre, it becomes a tab of that window; dropped on an edge, it splits the area. A docked window is dragged out again by its tab. Nothing in the program changes: a docked window is declared with ig_begin and ig_end as before.
A dock space
ig_dock_space(id), called every frame before the windows that dock into it, covers the display with a dock space. Where nothing is docked it is transparent, and floating windows stay above it. ig_dock_id(name) gives the id of a name, the same in every frame and every run.
A layout set by the program
The first time a dock space appears it is empty. A program that wants an initial arrangement builds it once, while ig_dock_layout_begin returns .true.: it splits the space into areas and assigns windows to them by name.
root = ig_dock_id('main')
if (ig_dock_layout_begin(root)) then ! the first frame only: no layout yet
call ig_dock_split(root, 'left', 0.3_real64, left, right) ! controls | the rest
call ig_dock_split(right, 'down', 0.25_real64, log, plot) ! the rest: plot above, log below
call ig_dock_window('Controls', left)
call ig_dock_window('Plot', plot)
call ig_dock_window('Log', log)
call ig_dock_layout_end(root)
endif
call ig_dock_space(root) ! every frame, before the windows| Procedure | Does |
|---|---|
ig_dock_id(name) → integer(int32) | the dock id of a name |
ig_dock_layout_begin(id [, stat]) → logical | .true. when the dock space has no layout yet, or after app%switch_layout and app%reset_layout (Windows and layouts): build it now |
ig_dock_split(id, direction, fraction, id_at_dir, id_other [, stat]) | split a node: id_at_dir takes fraction of it on the side direction ('left', 'right', 'up', 'down'), id_other the rest |
ig_dock_window(name, id [, stat]) | put the window name into the node id |
ig_dock_layout_end(id [, stat]) | finish the layout |
ig_dock_space(id [, flags] [, stat]) | the dock space, every frame, before its windows |
ig_window_dock(id, docked) | inside a window: its dock node (0 if none) and whether it is docked |
app%set_docking(enabled [, stat]) | docking on (the default) or off |
flags are ImGuiDockNodeFlags_*, exported by figure: NoDockingSplit, NoResize, AutoHideTabBar, NoUndocking, NoDockingOverCentralNode.
The builder runs inside ig_dock_layout_begin ... ig_dock_layout_end: ig_dock_split cuts a node in two, again on the new nodes for more areas, and ig_dock_window puts a window, by the name given to ig_begin, into a node.
- Order and pairing: in each frame,
ig_dock_layout_beginbeforeig_dock_spacefor the same id, then the windows.ig_dock_layout_endonly after a.true.ig_dock_layout_begin(the rule of tabs and tables); the layout is a scope of the frame's record, so a wrong end is refused and reported (Pairing and frames). - Status:
statis optional (absent:error stopwith the message).FIG_ERR_STATEforig_dock_spacewith docking off (ig_dock_space: docking is off (app%set_docking)), and forig_dock_space,ig_dock_layout_beginor a builder call with no frame open or from a task;FIG_ERR_ARGUMENTforig_dock_splitwith an unknowndirectionor afractionoutside (0, 1) (ig_dock_split: fraction must be in (0, 1)), and for a node that does not exist (ig_dock_window: unknown dock node). - Modes: the same in window, headless and remote mode. Threads: the frame loop's thread only; a task is refused (
FIG_ERR_STATE), as every drawing call.
The layout is the starting point: the user then rearranges it freely. With app%init(..., ini_file=...) Dear ImGui keeps the user's arrangement across runs, and ig_dock_layout_begin returns .false. when a saved layout exists. Without an ini file (the default) every run starts from the program's layout.
Which tab is in front. When a layout puts several windows into one node, as tabs, the tab in front is Dear ImGui's choice: it depends on how the windows took the focus as they first appeared, and follows neither the order of the ig_dock_window calls nor that of the ig_begin calls. To choose it, call ig_focus_window(name) on the frame after the layout was built (the window must have been drawn once, with ig_begin): its tab comes to the front. The tutorial's shell does so for its Input tab (docs/examples/src/tut09_shell.F90, region layout).
A window that appears later
A layout is built once, on the first frame. A window that appears afterwards (a file found while the program runs, a result computed later) is placed in a node with ig_set_next_window_dock(node), right before its ig_begin: it lands there the first time it appears, then stays where the user moves it (always=.true.: every frame).
if (show_result) then
call ig_set_next_window_dock(right) ! the node from the layout, the first time only
if (ig_begin('Result')) then
call ig_window_dock(node, docked) ! where it landed
call ig_text('the result')
endif
call ig_end()
endifdocs/examples/src/cb_workspace.F90 builds the layout below, shows its Result window on the fifth frame and checks, headless, that it landed in the right node:
$ ./cb_workspace
Result docked: T, in the right node: T
layout saved to workspace.layout
layout loaded from workspace.layoutA bar along a side
A toolbar, an activity bar or a status bar is a bar along one side of the display that the dock space leaves free:
if (ig_begin_main_menu_bar()) then
if (ig_begin_menu('File')) then
if (ig_menu_item('Quit')) call app%quit()
call ig_end_menu()
endif
call ig_end_main_menu_bar()
endif
if (ig_begin_side_bar('Tools', 'left', 80.0_real64)) then ! 'left', 'right', 'top' or 'bottom'
if (ig_tool_button('Input', ICON_FILE_PEN, selected=tool == 1)) tool = 1
if (ig_tool_button('Monitor', ICON_ACTIVITY, selected=tool == 2)) tool = 2
endif
call ig_end() ! always, as for any window
root = ig_dock_id('main')
if (ig_dock_layout_begin(root)) then
call ig_dock_split(root, 'left', 0.4_real64, left, right)
call ig_dock_window('Case', left)
call ig_dock_layout_end(root)
endif
call ig_dock_space(root) ! fills what the bars leave| Procedure | Does |
|---|---|
ig_begin_side_bar(name, side, size) → logical | begin the bar name along side, 'left', 'right', 'top' or 'bottom', size [pixels] wide (left, right) or high (top, bottom); .true. when its content is drawn; always ended with ig_end |
The bar is a window without title bar, not movable, resizable or dockable, at the side given and as wide (left, right) or as high (top, bottom) as size; the work area loses that strip, so the dock space and the windows placed in the work area do not cover it. Declare it every frame after the main menu bar and before the dock space, and always end it with ig_end. Several bars stack (a toolbar and a status bar). ig_begin_side_bar takes no stat: a side it does not know is taken as 'left'.
Save and load a layout
How the user arranged the windows (where each is docked, the splits' sizes, the floating windows' places, the tables' columns) is saved to a file, and loaded back while the program runs:
call app%save_layout('workspace.layout', comment='result = shown', stat=stat) ! any time
if (stat == FIG_OK) write(output_unit, '(A)') 'layout saved to workspace.layout'
call app%load_layout('workspace.layout', stat=stat) ! applied before the next frame
if (stat == FIG_OK) write(output_unit, '(A)') 'layout loaded from workspace.layout'A recipe for this: the cookbook.
- The file is Dear ImGui's settings text (
[Window][...],[Docking][Data], ...).commentlines come first, led by;: Dear ImGui skips them, the program reads them back itself (which windows it opens on demand, which panels are shown: what it, not Dear ImGui, decides). - A load clears the settings in effect, then reads the file: the dock nodes are rebuilt and the windows that exist take their saved place; a window that appears later takes its own when it does. The dock space keeps its layout:
ig_dock_layout_beginis false for it, as on a start with an ini file. The dock space's id must be the one saved (the sameig_dock_idname). - With
ini_fileinapp%initDear ImGui also keeps the layout by itself, between runs;save_layoutandload_layoutare for named layouts the user picks. - Any mode; a file that cannot be read is
FIG_ERR_FAILED, one with no[Window]or[Docking]sectionFIG_ERR_ARGUMENT.
Windows and layouts
A tool's windows are the same from one run to the next: a case, its residuals, a log. FIGURE keeps a registry of them, and of the layouts of the dock space the program offers, so that the program does not write a View menu, a layout switch, a "reset layout" and the code that remembers what the user closed.
call app%add_window('Case', closable=.false.) ! always there: no close button
call app%add_window('Residuals')
call app%add_window('Log', visible=.false.) ! hidden at the first run
call app%add_layout('Input', windows=[character(len=9) :: 'Case', 'Log'])
call app%add_layout('Monitor', windows=[character(len=9) :: 'Case', 'Residuals', 'Log'])| Procedure | Notes |
|---|---|
app%add_window(name [, visible] [, closable] [, in_view_menu] [, remember] [, stat]) | Register the window name, the name given to ig_begin. |
app%window_visible(name [, stat]) → logical | .true. while it is shown: draw it only then. |
app%set_window_visible(name, visible [, stat]) | Show or hide it from the program. |
app%view_menu([label] [, stat]) | The View menu, inside a menu bar. |
app%add_layout(name [, windows] [, stat]) | Declare a layout; the first added is current. |
app%layout() → character(len=:), allocatable | The current layout's name: the one to build ('' before add_layout). |
app%switch_layout(name [, stat]) | Make a layout current. |
app%reset_layout([stat]) | Lay the current layout out again. |
The registry. A registered window is drawn by the program, as any other, while window_visible(name) is .true.:
root = ig_dock_id('main')
if (ig_dock_layout_begin(root)) then ! the first frame, and after a switch or a reset
builds = builds + 1_int32
layout = app%layout() ! the one to build
select case (layout)
case ('Input')
call ig_dock_split(root, 'left', 0.5_real64, left, right)
call ig_dock_window('Case', left)
call ig_dock_window('Log', right)
case ('Monitor')
call ig_dock_split(root, 'left', 0.3_real64, left, right)
call ig_dock_split(right, 'down', 0.3_real64, bottom, top)
call ig_dock_window('Case', left)
call ig_dock_window('Residuals', top)
call ig_dock_window('Log', bottom)
endselect
call ig_dock_layout_end(root)
endif
call ig_dock_space(root)
do w = 1_int32, 3_int32
if (.not. app%window_visible(trim(PANELS(w)))) cycle ! draw a registered window while it is shown
if (ig_begin(trim(PANELS(w)))) call ig_text('the '//trim(PANELS(w)))
call ig_end()
enddoapp%add_window(name) registers a window, after init*, before or after app%open_prefs (a window added after it takes the visibility the preferences kept when it is added); app%set_window_visible(name, visible) shows or hides it from the program. The arguments of add_window:
visible(default.true.): shown at the first run; then as the user left it, when the program keeps its preferences andrememberis.true.(the default).closable(default.true.):ig_begin(name)withoutopengets a close button, which hides the window (window_visibleturns.false.; Dear ImGui writes FIGURE's flag, nothing is called back). Withopengiven, the program's own flag is used instead.in_view_menu(default.true.): listed in the View menu.
The View menu. app%view_menu() draws a menu View (or label) where it is called, in the main menu bar or a window's: a check item per window listed, in the order added, by the visible part of its name (without ##...); then, with layouts, one item per layout, the current one checked; then Reset layout, shown when there are layouts or a dock space was laid out with ig_dock_layout_begin.
if (ig_begin_main_menu_bar()) then
call app%view_menu() ! the windows, the layouts, Reset layout
call ig_end_main_menu_bar()
endifLayouts. A layout is a name, and the arrangement the program builds for it. FIGURE does not call the program to build it (no callbacks into Fortran: results are polled): the program builds app%layout() when ig_dock_layout_begin returns .true., which it does on the dock space's first frame and, after switch_layout or reset_layout, on its next call, for every dock space the program laid out that way (the region layouts above).
app%add_layout(name [, windows]) declares a layout: the first added is current, unless the preferences kept another.
windows: the registered windows the layout shows; when it becomes current (switched to, or reset), these are shown and the other registered windows hidden. Without it, a switch leaves them as they are.- The user's changes are kept by layout. Switching away keeps the arrangement the user left the layout in (Dear ImGui's settings, as
save_layoutwrites them); switching back gives it back before the next frame, andig_dock_layout_beginis.false.: the program builds nothing.reset_layoutforgets the changes of the current layout and has it built again. With the preferences, the current layout and each layout's arrangement are kept between runs too. - Without layouts,
reset_layout(and the View menu'sReset layout) lays the dock spaces out again all the same: the program's one builder runs again.
docs/examples/src/cb_view_menu.F90 clicks through its own View menu, headless:
$ ./cb_view_menu
shown: Case, Residuals, Log: T T F
layout: Monitor
shown: Case, Residuals, Log: T T T
Log shown after View/Log: F
layouts built: 3, Log shown again: T
layout: Input
layouts built: 4Rules. After init*; view_menu inside a frame and a menu bar (with no frame open: FIG_ERR_STATE, a usage error). A switch or a reset made inside a frame takes effect on the next. A layout's name is shown in the menu as given.
Status. stat is optional (absent: error stop with the message).
| Failure | Status | Message |
|---|---|---|
| a name added twice | FIG_ERR_ARGUMENT | app%add_window: '<name>' is added already (app%add_layout: ...) |
| an empty name | FIG_ERR_ARGUMENT | app%add_window: the name is empty (app%add_layout: ...) |
| a window not added | FIG_ERR_ARGUMENT | app%window_visible: no window '<name>' was added (app%set_window_visible: ...) |
| a layout not added | FIG_ERR_ARGUMENT | app%switch_layout: no layout '<name>' was added |
before init*, from a task | FIG_ERR_STATE | app%add_window: figure is not initialized; a task: as every drawing call |
Modes. The same in window, headless and remote modes. Threads: the frame loop's thread; a task's call is refused (FIG_ERR_STATE).
What it does not do. The menu's labels (View, Reset layout) are English: give label for the menu's own. A window hidden while docked leaves its tab's place to the others and comes back to its node. A layout does not keep which registered windows the user showed or hid in it: windows is applied each time it becomes current. Floating windows that are not docked by the builder keep their place across a reset.
Notes
- Dock ids are Dear ImGui's
ImGuiID(unsigned 32-bit) carried ininteger(int32): pass and compare them, do not compute with them. - Docking works the same in remote mode (the browser draws the result) and in headless mode, where tests can check where a window ended (
ig_window_dock). - Multi-viewports (windows dragged out of the main window into windows of their own) are not enabled: remote and headless modes cannot have them.
- The dock builder is internal to Dear ImGui (it is not part of its stable API); FIGURE's glue wraps the few calls above, so a later Dear ImGui release that changes it touches the glue only.