Skip to content

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.

docs/examples/src/cb_dock.F90: a laid-out dock space, and a floating window docked by the user

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.

fortran
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
ProcedureDoes
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_begin before ig_dock_space for the same id, then the windows. ig_dock_layout_end only 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: stat is optional (absent: error stop with the message). FIG_ERR_STATE for ig_dock_space with docking off (ig_dock_space: docking is off (app%set_docking)), and for ig_dock_space, ig_dock_layout_begin or a builder call with no frame open or from a task; FIG_ERR_ARGUMENT for ig_dock_split with an unknown direction or a fraction outside (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).

fortran
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()
endif

docs/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:

text
$ ./cb_workspace
Result docked: T, in the right node: T
layout saved to workspace.layout
layout loaded from workspace.layout

A 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:

fortran
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
ProcedureDoes
ig_begin_side_bar(name, side, size) → logicalbegin 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:

fortran
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], ...). comment lines 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_begin is false for it, as on a start with an ini file. The dock space's id must be the one saved (the same ig_dock_id name).
  • With ini_file in app%init Dear ImGui also keeps the layout by itself, between runs; save_layout and load_layout are for named layouts the user picks.
  • Any mode; a file that cannot be read is FIG_ERR_FAILED, one with no [Window] or [Docking] section FIG_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.

fortran
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'])
ProcedureNotes
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=:), allocatableThe 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.:

fortran
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()
enddo

app%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 and remember is .true. (the default).
  • closable (default .true.): ig_begin(name) without open gets a close button, which hides the window (window_visible turns .false.; Dear ImGui writes FIGURE's flag, nothing is called back). With open given, 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.

fortran
if (ig_begin_main_menu_bar()) then
   call app%view_menu()                                 ! the windows, the layouts, Reset layout
   call ig_end_main_menu_bar()
endif

Layouts. 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_layout writes them); switching back gives it back before the next frame, and ig_dock_layout_begin is .false.: the program builds nothing. reset_layout forgets 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's Reset 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:

text
$ ./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: 4

Rules. 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).

FailureStatusMessage
a name added twiceFIG_ERR_ARGUMENTapp%add_window: '<name>' is added already (app%add_layout: ...)
an empty nameFIG_ERR_ARGUMENTapp%add_window: the name is empty (app%add_layout: ...)
a window not addedFIG_ERR_ARGUMENTapp%window_visible: no window '<name>' was added (app%set_window_visible: ...)
a layout not addedFIG_ERR_ARGUMENTapp%switch_layout: no layout '<name>' was added
before init*, from a taskFIG_ERR_STATEapp%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 in integer(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.

Released under the MIT licence.