From 5cdd788f30d12b1abc5f2464135ea70eed87e77a Mon Sep 17 00:00:00 2001 From: omar Date: Fri, 31 May 2019 23:54:15 +0200 Subject: [PATCH] Comments (#2599). Moved branch Changelog above 1.71 wip one. Added some missing changelog bits. --- docs/CHANGELOG.txt | 133 +++++++++++++++++++++++---------------------- imgui.cpp | 1 + imgui.h | 8 +-- imgui_demo.cpp | 8 ++- 4 files changed, 81 insertions(+), 69 deletions(-) diff --git a/docs/CHANGELOG.txt b/docs/CHANGELOG.txt index 1e05b3b0..12136481 100644 --- a/docs/CHANGELOG.txt +++ b/docs/CHANGELOG.txt @@ -28,6 +28,75 @@ HOW TO UPDATE? and API updates have been a little more frequent lately. They are documented below and in imgui.cpp and should not affect all users. - Please report any issue! + +----------------------------------------------------------------------- + DOCKING BRANCH (In Progress) +----------------------------------------------------------------------- + +DOCKING FEATURES + +- Added Docking system: [BETA] (#2109, #351) + - Added ImGuiConfigFlags_DockingEnable flag to enable Docking. + Set with `io.ConfigFlags |= ImGuiConfigFlags_DockingEnable;`. + - Added DockSpace() API. + - Added ImGuiDockNodeFlags flags for DockSpace(). + - Added SetNextWindowDock(), SetNextWindowClass() API. + - Added GetWindowDockId(), IsWindowDocked() API. + - Added ImGuiWindowFlags_NoDocking window flag to disable the possibility for a window to be docked. + Popup, Menu and Child windows always have the ImGuiWindowFlags_NoDocking flag set. + - Added io.ConfigDockingNoSplit option. + - Added io.ConfigDockingWithShift option. + - Added io.ConfigDockingTabBarOnSingleWindows option. + - Added io.ConfigDockingTransparentPayload option. + - Style: Added ImGuiCol_DockingPreview, ImGuiCol_DockingEmptyBg colors. + - Demo: Added "DockSpace" example app showcasing use of explicit dockspace nodes. + +MULTI-VIEWPORT FEATURES (was previously 'viewport' branch, merged into 'docking') + +Breaking Changes: + +- IMPORTANT: When multi-viewports are enabled (with io.ConfigFlags |= ImGuiConfigFlags_ViewportsEnable), + all coordinates/positions will be in your natural OS coordinates space. It means that: + - Reference to hard-coded positions such as in SetNextWindowPos(ImVec2(0,0)) are _probably_ not what you want anymore. + Use GetMainViewport()->Pos to offset hard-coded positions, e.g. SetNextWindowPos(GetMainViewport()->Pos). + - Likewise io.MousePos and GetMousePos() will use OS coordinates. + If you query mouse positions to interact with non-imgui coordinates you will need to offset them. + e.g. subtract GetWindowViewport()->Pos. +- Render function: the ImDrawData structure now contains 'DisplayPos' and 'DisplaySize' fields. + To support multi-viewport, you need to use those values when creating your orthographic projection matrix. + Use 'draw_data->DisplaySize' instead of 'io.DisplaySize', and 'draw_data->DisplayPos' instead of (0,0) as the upper-left point. + You need to subtract 'draw_data->DisplayPos' from your scissor rectangles to convert them from global coordinates to frame-buffer coordinates. +- IO: Moved IME support functions from io.ImeSetInputScreenPosFn, io.ImeWindowHandle to the PlatformIO api. +- IO: Removed io.DisplayVisibleMin, io.DisplayVisibleMax settings (they were marked obsoleted, used to clip within the (0,0)..(DisplaySize) range). + +Other changes: +(FIXME: This need a fuller explanation!) + +- Added ImGuiPlatformIO structure and GetPlatformIO(). + Similarly to ImGuiIO and GetIO(), this structure is the main point of communication for back-ends supporting multi-viewports. +- Added ImGuiPlatformMonitor to feed OS monitor information in the ImGuiPlatformIO::Monitors. +- Added GetMainViewport(). +- Added GetWindowViewport(), SetNextWindowViewport(). +- Added GetWindowDpiScale(). +- Added GetOverlayDrawList(ImGuiViewport* viewport). + The no-parameter version of GetOverlayDrawList() return the overlay for the current window's viewport. +- Added UpdatePlatformWindows(), RenderPlatformWindows(), DestroyPlatformWindows() for usage for application core. +- Added FindViewportByID(), FindViewportByPlatformHandle() for usage by back-ends. +- Added ImGuiConfigFlags_ViewportsEnable configuration flag and other viewport options. +- Added io.ConfigViewportsNoAutoMerge, io.ConfigViewportsNoTaskBarIcon, io.ConfigViewportsNoDecoration, io.ConfigViewportsNoDefaultParent options. +- Added ImGuiBackendFlags_PlatformHasViewports, ImGuiBackendFlags_RendererHasViewports, ImGuiBackendFlags_HasMouseHoveredViewport backend flags. +- Added io.MainViewport, io.Viewports, io.MouseHoveredViewport (MouseHoveredViewport is optional _even_ for multi-viewport support). +- Added ImGuiViewport structure, ImGuiViewportFlags flags. +- Added ImGuiWindowClass and SetNextWindowClass() for passing viewport related hints to the OS/platform back-end. +- Examples: Renderer: OpenGL2, OpenGL3, DirectX11, DirectX12, Vulkan: Added support for multi-viewports. +- Examples: Platforms: Win32, GLFW, SDL2: Added support for multi-viewports. + Note that Linux/Mac still have inconsistent support for multi-viewports. If you want to help see https://github.com/ocornut/imgui/issues/2117. +- Examples: Win32: Added DPI-related helpers to access DPI features without requiring the latest Windows SDK at compile time, + and without requiring Windows 10 at runtime. +- Examples: Vulkan: Added various optional helpers in imgui_impl_vulkan.h (they are used for multi-viewport support) + to make the examples main.cpp easier to read. + + ----------------------------------------------------------------------- VERSION 1.71 (In Progress) ----------------------------------------------------------------------- @@ -78,70 +147,6 @@ Other Changes: support. (#2538, #2541) ------------------------------------------------------------------------ - DOCKING BRANCH (In Progress) ------------------------------------------------------------------------ - -DOCKING FEATURES - -- Added Docking system: [BETA] (#2109, #351) - - Added ImGuiConfigFlags_DockingEnable flag to enable Docking. - Set with `io.ConfigFlags |= ImGuiConfigFlags_DockingEnable;`. - - Added DockSpace() API. - - Added ImGuiDockNodeFlags flags for DockSpace(). - - Added SetNextWindowDock(), SetNextWindowClass() API. - - Added GetWindowDockId(), IsWindowDocked() API. - - Added ImGuiWindowFlags_NoDocking window flag to disable the possibility for a window to be docked. - Popup, Menu and Child windows always have the ImGuiWindowFlags_NoDocking flag set. - - Added io.ConfigDockingWithShift option to configure docking mode. - - Style: Added ImGuiCol_DockingPreview, ImGuiCol_DockingEmptyBg colors. - - Demo: Added "DockSpace" example app showcasing use of explicit dockspace nodes. - -MULTI-VIEWPORT FEATURES (was previously 'viewport' branch, merged into 'docking') - -Breaking Changes: - -- IMPORTANT: When multi-viewports are enabled (with io.ConfigFlags |= ImGuiConfigFlags_ViewportsEnable), - all coordinates/positions will be in your natural OS coordinates space. It means that: - - Reference to hard-coded positions such as in SetNextWindowPos(ImVec2(0,0)) are _probably_ not what you want anymore. - Use GetMainViewport()->Pos to offset hard-coded positions, e.g. SetNextWindowPos(GetMainViewport()->Pos). - - Likewise io.MousePos and GetMousePos() will use OS coordinates. - If you query mouse positions to interact with non-imgui coordinates you will need to offset them. - e.g. subtract GetWindowViewport()->Pos. -- Render function: the ImDrawData structure now contains 'DisplayPos' and 'DisplaySize' fields. - To support multi-viewport, you need to use those values when creating your orthographic projection matrix. - Use 'draw_data->DisplaySize' instead of 'io.DisplaySize', and 'draw_data->DisplayPos' instead of (0,0) as the upper-left point. - You need to subtract 'draw_data->DisplayPos' from your scissor rectangles to convert them from global coordinates to frame-buffer coordinates. -- IO: Moved IME support functions from io.ImeSetInputScreenPosFn, io.ImeWindowHandle to the PlatformIO api. -- IO: Removed io.DisplayVisibleMin, io.DisplayVisibleMax settings (they were marked obsoleted, used to clip within the (0,0)..(DisplaySize) range). - -Other changes: -(FIXME: This need a fuller explanation!) - -- Added ImGuiPlatformIO structure and GetPlatformIO(). - Similarly to ImGuiIO and GetIO(), this structure is the main point of communication for back-ends supporting multi-viewports. -- Added ImGuiPlatformMonitor to feed OS monitor information in the ImGuiPlatformIO::Monitors. -- Added GetMainViewport(). -- Added GetWindowViewport(), SetNextWindowViewport(). -- Added GetWindowDpiScale(). -- Added GetOverlayDrawList(ImGuiViewport* viewport). - The no-parameter version of GetOverlayDrawList() return the overlay for the current window's viewport. -- Added UpdatePlatformWindows(), RenderPlatformWindows(), DestroyPlatformWindows() for usage for application core. -- Added FindViewportByID(), FindViewportByPlatformHandle() for usage by back-ends. -- Added ImGuiConfigFlags_ViewportsEnable configuration flag and other viewport options. -- Added ImGuiBackendFlags_PlatformHasViewports, ImGuiBackendFlags_RendererHasViewports, ImGuiBackendFlags_HasMouseHoveredViewport backend flags. -- Added io.MainViewport, io.Viewports, io.MouseHoveredViewport (MouseHoveredViewport is optional _even_ for multi-viewport support). -- Added ImGuiViewport structure, ImGuiViewportFlags flags. -- Added ImGuiWindowClass and SetNextWindowClass() for passing viewport related hints to the OS/platform back-end. -- Examples: Renderer: OpenGL2, OpenGL3, DirectX11, DirectX12, Vulkan: Added support for multi-viewports. -- Examples: Platforms: Win32, GLFW, SDL2: Added support for multi-viewports. - Note that Linux/Mac still have inconsistent support for multi-viewports. If you want to help see https://github.com/ocornut/imgui/issues/2117. -- Examples: Win32: Added DPI-related helpers to access DPI features without requiring the latest Windows SDK at compile time, - and without requiring Windows 10 at runtime. -- Examples: Vulkan: Added various optional helpers in imgui_impl_vulkan.h (they are used for multi-viewport support) - to make the examples main.cpp easier to read. - - ----------------------------------------------------------------------- VERSION 1.70 (Released 2019-05-06) ----------------------------------------------------------------------- diff --git a/imgui.cpp b/imgui.cpp index ea1347a7..5ba7e30a 100644 --- a/imgui.cpp +++ b/imgui.cpp @@ -5768,6 +5768,7 @@ bool ImGui::Begin(const char* name, bool* p_open, ImGuiWindowFlags flags) flags = window->Flags; // Lock border size and padding for the frame (so that altering them doesn't cause inconsistencies) + // We read Style data after the call to UpdateSelectWindowViewport() which might be swapping the style. if (flags & ImGuiWindowFlags_ChildWindow) window->WindowBorderSize = style.ChildBorderSize; else diff --git a/imgui.h b/imgui.h index f46372c0..03b66663 100644 --- a/imgui.h +++ b/imgui.h @@ -597,9 +597,9 @@ namespace ImGui // Docking // [BETA API] Enable with io.ConfigFlags |= ImGuiConfigFlags_DockingEnable. // Note: you DO NOT need to call DockSpace() to use most Docking facilities! - // To dock windows: if io.ConfigDockingWithShift == false: drag window from their title bar. - // To dock windows: if io.ConfigDockingWithShift == true: hold SHIFT anywhere while moving windows. - // Use DockSpace() to create an explicit dock node _within_ an existing window. See Docking demo for details. + // - To dock windows: if io.ConfigDockingWithShift == false (default) drag window from their title bar. + // - To dock windows: if io.ConfigDockingWithShift == true: hold SHIFT anywhere while moving windows. + // - Use DockSpace() to create an explicit dock node _within_ an existing window. See Docking demo for details. IMGUI_API void DockSpace(ImGuiID id, const ImVec2& size = ImVec2(0, 0), ImGuiDockNodeFlags flags = 0, const ImGuiWindowClass* window_class = NULL); IMGUI_API ImGuiID DockSpaceOverViewport(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 (FIXME-DOCK) @@ -1052,7 +1052,7 @@ enum ImGuiConfigFlags_ ImGuiConfigFlags_NoMouseCursorChange = 1 << 5, // Instruct back-end to not alter mouse cursor shape and visibility. Use if the back-end cursor changes are interfering with yours and you don't want to use SetMouseCursor() to change mouse cursor. You may want to honor requests from imgui by reading GetMouseCursor() yourself instead. // [BETA] Docking - ImGuiConfigFlags_DockingEnable = 1 << 6, // Docking enable flags. Use SHIFT to dock window into another (or without SHIFT if io.ConfigDockingWithShift = false). + ImGuiConfigFlags_DockingEnable = 1 << 6, // Docking enable flags. // [BETA] Viewports // When using viewports it is recommended that your default value for ImGuiCol_WindowBg is opaque (Alpha=1.0) so transition to a viewport won't be noticeable. diff --git a/imgui_demo.cpp b/imgui_demo.cpp index 267439dc..11ae1952 100644 --- a/imgui_demo.cpp +++ b/imgui_demo.cpp @@ -4326,7 +4326,8 @@ static void ShowExampleAppCustomRendering(bool* p_open) //----------------------------------------------------------------------------- // Demonstrate using DockSpace() to create an explicit docking node within an existing window. -// Note that you already dock windows into each others _without_ a DockSpace() by just holding SHIFT when moving a window. +// Note that you already dock windows into each others _without_ a DockSpace() by just moving windows +// from their title bar (or by holding SHIFT if io.ConfigDockingWithShift is set). // DockSpace() is only useful to construct to a central location for your application. void ShowExampleAppDockSpace(bool* p_open) { @@ -4353,6 +4354,11 @@ void ShowExampleAppDockSpace(bool* p_open) if (dockspace_flags & ImGuiDockNodeFlags_PassthruCentralNode) window_flags |= ImGuiWindowFlags_NoBackground; + // Important: note that we proceed even if Begin() returns false (aka window is collapsed). + // This is because we want to keep our DockSpace() active. If a DockSpace() is inactive, + // all active windows docked into it will lose their parent and become undocked. + // We cannot preserve the docking relationship between an active window and an inactive docking, otherwise + // any change of dockspace/settings would lead to windows being stuck in limbo and never being visible. ImGui::PushStyleVar(ImGuiStyleVar_WindowPadding, ImVec2(0.0f, 0.0f)); ImGui::Begin("DockSpace Demo", p_open, window_flags); ImGui::PopStyleVar();