Docking DockBuilder with DockSpaceOverViewport

[gkoreman]

Version/Branch of Dear ImGui:

Version 1.90.2, Branch: docking

Back-ends:

imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp

Compiler, OS:

macOS + Clang

Full config/build information:

<Not important for this question/answer>

Details:

My Issue/Question:

This question is meant as feedback on the docking system. I have solved the issue for my use case but I believe it shows a common use case for docking that could be solved by imgui itself. The question is as follows:

When using Docking how do I set a default layout for my windows if I am using DockSpaceOverViewport?

I found #2109 which has a bunch of great information. Specifically, this:

ImGuiID dockspace_id = ImGui::GetID("MyDockSpace");
if (ImGui::DockBuilderGetNode(dockspace_id) == NULL)
{
  ImGui::DockBuilderRemoveNode(dockspace_id); // Clear out existing layout
  ImGui::DockBuilderAddNode(dockspace_id, ImGuiDockNodeFlags_Dockspace); // Add empty node
  ImGui::DockBuilderSetNodeSize(dockspace_id, dockspace_size);
  
  ImGuiID dock_main_id = dockspace_id; // This variable will track the document node, however we are not using it here as we aren't docking anything into it.
  ImGuiID dock_id_prop = ImGui::DockBuilderSplitNode(dock_main_id, ImGuiDir_Left, 0.20f, NULL, &dock_main_id);
  ImGuiID dock_id_bottom = ImGui::DockBuilderSplitNode(dock_main_id, ImGuiDir_Down, 0.20f, NULL, &dock_main_id);
  
  ImGui::DockBuilderDockWindow("Log", dock_id_bottom);
  ImGui::DockBuilderDockWindow("Properties", dock_id_prop);
  ImGui::DockBuilderDockWindow("Mesh", dock_id_prop);
  ImGui::DockBuilderDockWindow("Extra", dock_id_prop);
  ImGui::DockBuilderFinish(dockspace_id);
}
ImGui::DockSpace(dockspace_id);

This is using a trick where the ini file will load the MyDockSpace ID if we already saved our docking layout so we only create the docking layout the first time. This trick doesn't quite work if you use DockSpaceOverViewport because it creates a window AND the dock space in one function call.

Things I tried:

ImGuiID dockspace_id = ImGui::GetID("DockSpace");
if (ImGui::DockBuilderGetNode(dockspace_id) == NULL)
{
...
}
ImGui::DockSpaceOverViewport();

"DockSpace" is the ID that the DockSpaceOverViewport uses for its internal DockSpace. This doesn't work because the GetID returned from my code doesn't match the GetID in DockSpaceOverViewport because my code is outside the window that gets created in DockSpaceOverViewport.

I considered pre-creating the window and getting the ID from within that context, but that defeats the purpose of DockSpaceOverViewport because I'd have to duplicate all the window flags etc.

Ultimately what I did was create a new DockSpaceOverViewportEx function that takes a lambda that will optionally call my DockBuilder code. This requires c++20 due to auto, but could easily be written differently.

namespace ImGui
{
    ImGuiID DockSpaceOverViewportEx(const ImGuiViewport* viewport, ImGuiDockNodeFlags dockspace_flags, const ImGuiWindowClass* window_class, auto DockBuilder)
    {
        if (viewport == NULL)
            viewport = GetMainViewport();

        SetNextWindowPos(viewport->WorkPos);
        SetNextWindowSize(viewport->WorkSize);
        SetNextWindowViewport(viewport->ID);

        ImGuiWindowFlags host_window_flags = 0;
        host_window_flags |= ImGuiWindowFlags_NoTitleBar | ImGuiWindowFlags_NoCollapse | ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoMove | ImGuiWindowFlags_NoDocking;
        host_window_flags |= ImGuiWindowFlags_NoBringToFrontOnFocus | ImGuiWindowFlags_NoNavFocus;
        if (dockspace_flags & ImGuiDockNodeFlags_PassthruCentralNode)
            host_window_flags |= ImGuiWindowFlags_NoBackground;

        char label[32];
        ImFormatString(label, IM_ARRAYSIZE(label), "DockSpaceViewport_%08X", viewport->ID);

        PushStyleVar(ImGuiStyleVar_WindowRounding, 0.0f);
        PushStyleVar(ImGuiStyleVar_WindowBorderSize, 0.0f);
        PushStyleVar(ImGuiStyleVar_WindowPadding, ImVec2(0.0f, 0.0f));
        Begin(label, NULL, host_window_flags);
        PopStyleVar(3);

        ImGuiID dockspace_id = GetID("DockSpace");

/// vvvv ---- call DockBuilder callback if no docking exists --- vvvv
        if(DockBuilderGetNode(dockspace_id) == nullptr)
        {
            DockBuilder(dockspace_id);
        }
/// ^^^^ ---------------------------------------------------- ^^^^

        DockSpace(dockspace_id, ImVec2(0.0f, 0.0f), dockspace_flags, window_class);
        End();

        return dockspace_id;
    }
}

Screenshots/Video:

No response

Minimal, Complete and Verifiable Example code:

No response