diff --git a/docs/CHANGELOG.txt b/docs/CHANGELOG.txt index fae4d30b7..18c5675d1 100644 --- a/docs/CHANGELOG.txt +++ b/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] diff --git a/imgui.h b/imgui.h index 27baa6baf..60dc91d0d 100644 --- a/imgui.h +++ b/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. - // Note: You can use most Docking facilities without calling any API. You DO NOT need to call DockSpace() to use Docking! - // - Drag from window title bar or their tab to dock/undock. Hold SHIFT to disable docking. - // - Drag from window menu button (upper-left button) to undock an entire node (all windows). - // - When io.ConfigDockingWithShift == true, you instead need to hold SHIFT to enable docking. - // About dockspaces: - // - Use DockSpaceOverViewport() to create a window covering the screen or a specific viewport + a dockspace inside it. - // This is often used with ImGuiDockNodeFlags_PassthruCentralNode to make it transparent. - // - Use DockSpace() to create an explicit dock node _within_ an existing window. See Docking demo for details. - // - Important: Dockspaces need to be submitted _before_ any window they can host. Submit it early in your frame! - // - Important: Dockspaces need to be kept alive if hidden, otherwise windows docked into it will be undocked. - // e.g. if you have multiple tabs with a dockspace inside each tab: submit the non-visible dockspaces with ImGuiDockNodeFlags_KeepAliveOnly. + // - Read https://github.com/ocornut/imgui/wiki/Docking for details. + // - Enable with io.ConfigFlags |= ImGuiConfigFlags_DockingEnable. + // - 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 title bar or their tab to dock/undock. Hold SHIFT to disable docking. + // - Drag from window menu button (upper-left button) to undock an entire node (all windows). + // - When io.ConfigDockingWithShift == true, you instead need to hold SHIFT to enable docking. + // - Dockspaces: + // - If you want to dock windows into the edge of your screen, most application can simply call DockSpaceOverViewport(): + // e.g. ImGui::NewFrame(); then ImGui::DockSpaceOverViewport(); // Create a dockspace in main viewport. + // or: ImGui::NewFrame(); then ImGui::DockSpaceOverViewport(0, nullptr, ImGuiDockNodeFlags_PassthruCentralNode); // Create a dockspace in main viewport, where central node is transparent. + // - A dockspace is an explicit dock node within an existing window. + // - 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 diff --git a/imgui_demo.cpp b/imgui_demo.cpp index 4c5066b5d..40960c534 100644 --- a/imgui_demo.cpp +++ b/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. -// Note: You can use most Docking facilities without calling any API. You DO NOT need to call DockSpace() to use Docking! -// - Drag from window title bar or their tab to dock/undock. Hold SHIFT to disable docking. -// - Drag from window menu button (upper-left button) to undock an entire node (all windows). -// - When io.ConfigDockingWithShift == true, you instead need to hold SHIFT to enable docking. -// About dockspaces: -// - Use DockSpace() to create an explicit dock node _within_ an existing window. -// - Use DockSpaceOverViewport() to create an explicit dock node covering the screen or a specific viewport. -// This is often used with ImGuiDockNodeFlags_PassthruCentralNode. -// - Important: Dockspaces need to be submitted _before_ any window they can host. Submit it early in your frame! (*) -// - Important: Dockspaces need to be kept alive if hidden, otherwise windows docked into it will be undocked. -// e.g. if you have multiple tabs with a dockspace inside each tab: submit the non-visible dockspaces with ImGuiDockNodeFlags_KeepAliveOnly. -// (*) 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 calling DockSpace() and leave it in the window stack for anyone to use. +// Demonstrate using DockSpace() to create an explicit docking node within an existing window, with various options. +// THIS IS A DEMO FOR ADVANCED USAGE OF DockSpace(). +// MOST REGULAR APPLICATIONS WHO WANT TO ALLOW DOCKING WINDOWS ON THE EDGE OF YOUR SCREEN CAN SIMPLY USE: +// ImGui::NewFrame(); +// ImGui::DockSpaceOverViewport(); // Create a dockspace in main viewport +// OR: +// ImGui::NewFrame(); +// ImGui::DockSpaceOverViewport(0, nullptr, ImGuiDockNodeFlags_PassthruCentralNode); // Create a dockspace in main viewport, where central node is transparent. +// Read https://github.com/ocornut/imgui/wiki/Docking for details. +// The reasons we do not use DockSpaceOverViewport() in this demo is because: +// - (1) we allow the host window to be floating/moveable instead of filling the viewport (when opt_fullscreen == false) +// which is mostly to showcase the idea that DockSpace() may be submitted anywhere. +// - (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) 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: - // void ShowExampleAppDockSpace() - // { - // ImGui::DockSpaceOverViewport(0, ImGui::GetMainViewport()); - // } - // In most cases you should be able to just call DockSpaceOverViewport() and ignore all the code below! + // If we remove all options we are showcasing, this demo would become a simple call to ImGui::DockSpaceOverViewport() !! // 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( - "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" - "- 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)" "\n" - "This demo app has nothing to do with enabling docking!" "\n\n" - "This demo app only demonstrate the use of ImGui::DockSpace() which allows you to manually create a docking node _within_ another window." "\n\n" - "Read comments in ShowExampleAppDockSpace() for more details."); - + if (ImGui::BeginMenu("Help")) + { + ImGui::TextUnformatted( + "This demo has nothing to do with enabling docking!" "\n" + "This demo only demonstrate the use of ImGui::DockSpace() which allows you to manually\ncreate a docking node _within_ another window." "\n" + "Most application can simply call ImGui::DockSpaceOverViewport() and be done with it."); + ImGui::Separator(); + ImGui::TextUnformatted("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" + "- 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(); }