Docking (original) (raw)

Search Issues: https://github.com/ocornut/imgui/labels/docking
See: Glossary -> Docking terms.

Docked windows

Preamble

Where to find it?

Docking is currently available in the docking branch.

This is a well maintained branch and most large teams have been using this branch for a while.
It is safe and recommended to use that branch.
The branch also include the Multi-viewports feature.
Since July 2023, releases are also tagged for docking, e.g. v1.92.0 v1.92.0-docking.

How can I enable docking?

Enable config flag:

ImGui::GetIO().ConfigFlags |= ImGuiConfigFlags_DockingEnable;

Create a fullscreen dockspace (optional)

ImGui::DockSpaceOverViewport();

That's pretty much it. There are additional docked related configuration flags in the ImGuiIO structure which you may toy with.

Why is not merged to master???

(This is the most asked question ever)
TL;DR; I am not happy with the current state of the code. I am a cautious person.

I want to rewrite it from scratch a third time (1st version was never released).
DockBuilder API is kept in imgui_internal.h because it is not great.
Many open issues don't have easy enough fixes, which suggests the code being too complex or fragile compared to the quality I strive for.
Some core concepts needs to be re-implemented or redesigned.
I have been incrementally adding automated tests to imgui_test_suite in order to facilitate rewriting the code.

However, you can benefit from a lot of docking features without being impacted by any of this. The largest amount of interactions you'll have with the docking system are at end-user level and do not require API calls. By just enabling the config flag above and calling a few functions you can benefit from 90% of Docking features. Even the hypothetical full rewrite of Docking system is not expected to impact most users. API that are most at risk of changing are hidden in imgui_internal.h for this reason, and even so, if they do change, we'll make reasonable effort to document the reasoning the update path.

In addition, Docking will only move forward with feedback from users, so the more people using it, the closer we are to a reach mergeable version. TL;DR; is totally fine to use for most users.

Usage Guide

Also see our Glossary about Docking terminology.

Docking

Dock by dragging windows from their title tab or tab (hold SHIFT to disable docking)

Dock into an existing window or node
Split existing node

Undocking

Undock a window from a node
Undock a node (all windows) from a hierarchy

Other features

Tab bar may be hidden

Dockspace

If you want to dock window on the edge of your screen (rather than only into other windows), most application can do:

ImGui::NewFrame();

// Create a dockspace in main viewport. ImGui::DockSpaceOverViewport();

ImGui::NewFrame();

// Create a dockspace in main viewport, where central node is transparent. ImGui::DockSpaceOverViewport(0, ImGui::GetMainViewport(), ImGuiDockNodeFlags_PassthruCentralNode);

DockSpaceOverViewport() is a helper which:

Create an invisible window covering the given viewport.
Then submits a DockSpace() into it.

That's pretty much what it does.

A DockSpace() is an arbitrary location inside a window, where other windows may be docked into.

Dockspaces need to be submitted before any window they can host. Submit it early in your frame!
- (because of this constraint, the implicit "Debug" window can not be docked into an explicit DockSpace() node, because that window is submitted as part of the part of the NewFrame() call. An easy workaround is that you can create your own implicit "Debug##2" window after submitting a dockspace, leave it in the window stack for anyone to use)
Dockspaces need to be kept alive if hidden, otherwise windows docked into it will be undocked.
- If you have e.g. multiple tabs with a dockspace inside each tab: submit the non-visible dockspaces with ImGuiDockNodeFlags_KeepAliveOnly.

Programmatically setting up docking layout (DockBuider api)

Unfortunately, there is no great API for this yet. I am sorry! I know everyone is asking for this!

There is a DockBuilder API in imgui_internal.h. It's not great, it is unfinished, and not well documented (you can find more examples if you search in Issues).
An alternative is to manually create desired settings, save them using SaveIniSettingsXXX() function, strip the data to whatever is necessary to you and call LoadIniSettingsXXX().

DockBuilder API idiomatic example:

#include "imgui_internal.h"

ImGuiID dockspace_id = ImGui::GetID("My Dockspace"); ImGuiViewport* viewport = ImGui::GetMainViewport();

// Create settings if (ImGui::DockBuilderGetNode(dockspace_id) == nullptr) { ImGui::DockBuilderAddNode(dockspace_id, ImGuiDockNodeFlags_DockSpace); ImGui::DockBuilderSetNodeSize(dockspace_id, viewport->Size); ImGuiID dock_id_left = 0; ImGuiID dock_id_main = dockspace_id; ImGui::DockBuilderSplitNode(dock_id_main, ImGuiDir_Left, 0.20f, &dock_id_left, &dock_id_main); ImGuiID dock_id_left_top = 0; ImGuiID dock_id_left_bottom = 0; ImGui::DockBuilderSplitNode(dock_id_left, ImGuiDir_Up, 0.50f, &dock_id_left_top, &dock_id_left_bottom); ImGui::DockBuilderDockWindow("Game", dock_id_main); ImGui::DockBuilderDockWindow("Properties", dock_id_left_top); ImGui::DockBuilderDockWindow("Scene", dock_id_left_bottom); ImGui::DockBuilderFinish(dockspace_id); }

// Submit dockspace ImGui::DockSpaceOverViewport(dockspace_id, viewport, ImGuiDockNodeFlags_PassthruCentralNode);

// Submit windows ImGui::Begin("Properties"); ...

I dislike this API probably even more than you. I expect to redesign this before it reaches the public API.

DockBuilder example

Debugging

Use the Debug Log to log docking events.
Use the Metrics/Debugger Window's Docking section to browse internal docking data.

TODO: explain what data is persisting in .ini file, how and why.