Docs: improve docking API comments and demo. (#9000)

docs/CHANGELOG.txt

@@ -177,6 +177,7 @@ Docking+Viewports Branch:
   - Vulkan: pipeline created for secondary viewport automatically match
     surface format. (#8686) [@sylmroz]
   - Vulkan: Added ImGui_ImplVulkanH_GetWindowDataFromViewport() accessor/helper. (#8946, #8940) [@olivier-gerard]
+- Docs: improve docking API comments and demo. (#9000)
 - Examples: DX10, DX11: Disabled DXGI's Alt+Enter default behavior in examples.
   Applications are free to leave this enabled, but it does not work properly with
   multiple viewports. (#4350) [@PathogenDavid]

imgui.h

@@ -956,18 +956,24 @@ namespace ImGui
     IMGUI_API void          SetTabItemClosed(const char* tab_or_docked_window_label);           // notify TabBar or Docking system of a closed tab/window ahead (useful to reduce visual flicker on reorderable tab bars). For tab-bar: call after BeginTabBar() and before Tab submissions. Otherwise call with a window name.
 
     // Docking
-    // [BETA API] Enable with io.ConfigFlags |= ImGuiConfigFlags_DockingEnable.
+    // - Read https://github.com/ocornut/imgui/wiki/Docking for details.
-    // Note: You can use most Docking facilities without calling any API. You DO NOT need to call DockSpace() to use Docking!
+    // - Enable with io.ConfigFlags |= ImGuiConfigFlags_DockingEnable.
-    // - Drag from window title bar or their tab to dock/undock. Hold SHIFT to disable docking.
+    // - You can use most Docking facilities without calling any API. You don't necessarily need to call a DockSpaceXXX function to use Docking!
-    // - Drag from window menu button (upper-left button) to undock an entire node (all windows).
+    //   - Drag from window title bar or their tab to dock/undock. Hold SHIFT to disable docking.
-    // - When io.ConfigDockingWithShift == true, you instead need to hold SHIFT to enable docking.
+    //   - Drag from window menu button (upper-left button) to undock an entire node (all windows).
-    // About dockspaces:
+    //   - When io.ConfigDockingWithShift == true, you instead need to hold SHIFT to enable docking.
-    // - Use DockSpaceOverViewport() to create a window covering the screen or a specific viewport + a dockspace inside it.
+    // - Dockspaces:
-    //   This is often used with ImGuiDockNodeFlags_PassthruCentralNode to make it transparent.
+    //   - If you want to dock windows into the edge of your screen, most application can simply call DockSpaceOverViewport():
-    // - Use DockSpace() to create an explicit dock node _within_ an existing window. See Docking demo for details.
+    //     e.g. ImGui::NewFrame(); then ImGui::DockSpaceOverViewport();  // Create a dockspace in main viewport.
-    // - Important: Dockspaces need to be submitted _before_ any window they can host. Submit it early in your frame!
+    //      or: ImGui::NewFrame(); then ImGui::DockSpaceOverViewport(0, nullptr, ImGuiDockNodeFlags_PassthruCentralNode);  // Create a dockspace in main viewport, where central node is transparent.
-    // - Important: Dockspaces need to be kept alive if hidden, otherwise windows docked into it will be undocked.
+    //   - A dockspace is an explicit dock node within an existing window.
-    //   e.g. if you have multiple tabs with a dockspace inside each tab: submit the non-visible dockspaces with ImGuiDockNodeFlags_KeepAliveOnly.
+    //   - DockSpaceOverViewport() basically creates an invisible window covering a viewport, and submit a DockSpace() into it.
+    //   - IMPORTANT: Dockspaces need to be submitted _before_ any window they can host. Submit them early in your frame!
+    //   - IMPORTANT: 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.
+    // - Programmatic docking:
+    //   - There is no public API yet other than the very limited SetNextWindowDockID() function. Sorry for that!
+    //   - Read https://github.com/ocornut/imgui/wiki/Docking for examples of how to use current internal API.
     IMGUI_API ImGuiID       DockSpace(ImGuiID dockspace_id, const ImVec2& size = ImVec2(0, 0), ImGuiDockNodeFlags flags = 0, const ImGuiWindowClass* window_class = NULL);
     IMGUI_API ImGuiID       DockSpaceOverViewport(ImGuiID dockspace_id = 0, const ImGuiViewport* viewport = NULL, ImGuiDockNodeFlags flags = 0, const ImGuiWindowClass* window_class = NULL);
     IMGUI_API void          SetNextWindowDockID(ImGuiID dock_id, ImGuiCond cond = 0);           // set next window dock id

imgui_demo.cpp

@@ -10248,37 +10248,27 @@ static void ShowExampleAppCustomRendering(bool* p_open)
 // [SECTION] Example App: Docking, DockSpace / ShowExampleAppDockSpace()
 //-----------------------------------------------------------------------------
 
-// Demonstrate using DockSpace() to create an explicit docking node within an existing window.
+// Demonstrate using DockSpace() to create an explicit docking node within an existing window, with various options.
-// Note: You can use most Docking facilities without calling any API. You DO NOT need to call DockSpace() to use Docking!
+// THIS IS A DEMO FOR ADVANCED USAGE OF DockSpace().
-// - Drag from window title bar or their tab to dock/undock. Hold SHIFT to disable docking.
+// MOST REGULAR APPLICATIONS WHO WANT TO ALLOW DOCKING WINDOWS ON THE EDGE OF YOUR SCREEN CAN SIMPLY USE:
-// - Drag from window menu button (upper-left button) to undock an entire node (all windows).
+//    ImGui::NewFrame();
-// - When io.ConfigDockingWithShift == true, you instead need to hold SHIFT to enable docking.
+//    ImGui::DockSpaceOverViewport(); // Create a dockspace in main viewport
-// About dockspaces:
+// OR:
-// - Use DockSpace() to create an explicit dock node _within_ an existing window.
+//    ImGui::NewFrame();
-// - Use DockSpaceOverViewport() to create an explicit dock node covering the screen or a specific viewport.
+//    ImGui::DockSpaceOverViewport(0, nullptr, ImGuiDockNodeFlags_PassthruCentralNode); // Create a dockspace in main viewport, where central node is transparent.
-//   This is often used with ImGuiDockNodeFlags_PassthruCentralNode.
+// Read https://github.com/ocornut/imgui/wiki/Docking for details.
-// - Important: Dockspaces need to be submitted _before_ any window they can host. Submit it early in your frame! (*)
+// The reasons we do not use DockSpaceOverViewport() in this demo is because:
-// - Important: Dockspaces need to be kept alive if hidden, otherwise windows docked into it will be undocked.
+// - (1) we allow the host window to be floating/moveable instead of filling the viewport (when opt_fullscreen == false)
-//   e.g. if you have multiple tabs with a dockspace inside each tab: submit the non-visible dockspaces with ImGuiDockNodeFlags_KeepAliveOnly.
+//       which is mostly to showcase the idea that DockSpace() may be submitted anywhere.
-// (*) because of this constraint, the implicit \"Debug\" window can not be docked into an explicit DockSpace() node,
+// - (2) we allow the host window to have padding (when opt_padding == true)
-// because that window is submitted as part of the part of the NewFrame() call. An easy workaround is that you can create
+// - (3) we expose many flags and need a way to have them visible.
-// your own implicit "Debug##2" window after calling DockSpace() and leave it in the window stack for anyone to use.
+// - (4) we have a local menu bar in the host window (vs. you could use BeginMainMenuBar() + DockSpaceOverViewport()
+//       in your code, but we don't here because we allow the window to be floating)
 void ShowExampleAppDockSpace(bool* p_open)
 {
-    // READ THIS !!!
     // TL;DR; this demo is more complicated than what most users you would normally use.
-    // If we remove all options we are showcasing, this demo would become:
+    // If we remove all options we are showcasing, this demo would become a simple call to ImGui::DockSpaceOverViewport() !!
-    //     void ShowExampleAppDockSpace()
-    //     {
-    //         ImGui::DockSpaceOverViewport(0, ImGui::GetMainViewport());
-    //     }
-    // In most cases you should be able to just call DockSpaceOverViewport() and ignore all the code below!
     // In this specific demo, we are not using DockSpaceOverViewport() because:
-    // - (1) we allow the host window to be floating/moveable instead of filling the viewport (when opt_fullscreen == false)
-    // - (2) we allow the host window to have padding (when opt_padding == true)
-    // - (3) we expose many flags and need a way to have them visible.
-    // - (4) we have a local menu bar in the host window (vs. you could use BeginMainMenuBar() + DockSpaceOverViewport()
-    //      in your code, but we don't here because we allow the window to be floating)
 
     static bool opt_fullscreen = true;
     static bool opt_padding = false;
@@ -10323,6 +10313,8 @@ void ShowExampleAppDockSpace(bool* p_open)
         ImGui::PopStyleVar(2);
 
     // Submit the DockSpace
+    // REMINDER: THIS IS A DEMO FOR ADVANCED USAGE OF DockSpace()!
+    // MOST REGULAR APPLICATIONS WILL SIMPLY WANT TO CALL DockSpaceOverViewport(). READ COMMENTS ABOVE.
     ImGuiIO& io = ImGui::GetIO();
     if (io.ConfigFlags & ImGuiConfigFlags_DockingEnable)
     {
@@ -10334,6 +10326,7 @@ void ShowExampleAppDockSpace(bool* p_open)
         ShowDockingDisabledMessage();
     }
 
+    // Show demo options and help
     if (ImGui::BeginMenuBar())
     {
         if (ImGui::BeginMenu("Options"))
@@ -10356,16 +10349,23 @@ void ShowExampleAppDockSpace(bool* p_open)
                 *p_open = false;
             ImGui::EndMenu();
         }
-        HelpMarker(
+        if (ImGui::BeginMenu("Help"))
-            "When docking is enabled, you can ALWAYS dock MOST window into another! Try it now!" "\n"
+        {
-            "- Drag from window title bar or their tab to dock/undock." "\n"
+            ImGui::TextUnformatted(
-            "- Drag from window menu button (upper-left button) to undock an entire node (all windows)." "\n"
+                "This demo has nothing to do with enabling docking!" "\n"
-            "- Hold SHIFT to disable docking (if io.ConfigDockingWithShift == false, default)" "\n"
+                "This demo only demonstrate the use of ImGui::DockSpace() which allows you to manually\ncreate a docking node _within_ another window." "\n"
-            "- Hold SHIFT to enable docking (if io.ConfigDockingWithShift == true)" "\n"
+                "Most application can simply call ImGui::DockSpaceOverViewport() and be done with it.");
-            "This demo app has nothing to do with enabling docking!" "\n\n"
+            ImGui::Separator();
-            "This demo app only demonstrate the use of ImGui::DockSpace() which allows you to manually create a docking node _within_ another window." "\n\n"
+            ImGui::TextUnformatted("When docking is enabled, you can ALWAYS dock MOST window into another! Try it now!" "\n"
-            "Read comments in ShowExampleAppDockSpace() for more details.");
+                "- Drag from window title bar or their tab to dock/undock." "\n"
-
+                "- Drag from window menu button (upper-left button) to undock an entire node (all windows)." "\n"
+                "- Hold SHIFT to disable docking (if io.ConfigDockingWithShift == false, default)" "\n"
+                "- Hold SHIFT to enable docking (if io.ConfigDockingWithShift == true)");
+            ImGui::Separator();
+            ImGui::TextUnformatted("More details:"); ImGui::Bullet(); ImGui::SameLine(); ImGui::TextLinkOpenURL("Docking Wiki page", "https://github.com/ocornut/imgui/wiki/Docking");
+            ImGui::BulletText("Read comments in ShowExampleAppDockSpace()");
+            ImGui::EndMenu();
+        }
         ImGui::EndMenuBar();
     }