Begin: WIP consistent Begin/End behavior.

docs/FAQ.md

@@ -429,8 +429,10 @@ provide similar or better string helpers.
 ### Q: How can I display custom shapes? (using low-level ImDrawList API)
 
 - You can use the low-level `ImDrawList` api to render shapes within a window.
+
 ```cpp
-ImGui::Begin("My shapes");
+if (!ImGui::Begin("My shapes"))
+    return;
 
 ImDrawList* draw_list = ImGui::GetWindowDrawList();
 

docs/README.md

@@ -52,7 +52,8 @@ Result:
 Code:
 ```cpp
 // Create a window called "My First Tool", with a menu bar.
-ImGui::Begin("My First Tool", &my_tool_active, ImGuiWindowFlags_MenuBar);
+if (!ImGui::Begin("My First Tool", &my_tool_active, ImGuiWindowFlags_MenuBar))
+    return;
 if (ImGui::BeginMenuBar())
 {
     if (ImGui::BeginMenu("File"))

examples/example_win32_directx11/main.cpp

@@ -122,17 +122,21 @@ int main(int, char**)
         ImGui_ImplWin32_NewFrame();
         ImGui::NewFrame();
 
+#if 1
+        // Enable Debugging
+        io.ConfigDebugBeginReturnValue = io.KeyShift;
+#endif
+
         // 1. Show the big demo window (Most of the sample code is in ImGui::ShowDemoWindow()! You can browse its code to learn more about Dear ImGui!).
         if (show_demo_window)
             ImGui::ShowDemoWindow(&show_demo_window);
 
         // 2. Show a simple window that we create ourselves. We use a Begin/End pair to created a named window.
+        if (ImGui::Begin("Hello, world!"))                          // Create a window called "Hello, world!" and append into it.
         {
             static float f = 0.0f;
             static int counter = 0;
 
-            ImGui::Begin("Hello, world!");                          // Create a window called "Hello, world!" and append into it.
-
             ImGui::Text("This is some useful text.");               // Display some text (you can use a format strings too)
             ImGui::Checkbox("Demo Window", &show_demo_window);      // Edit bools storing our window open/close state
             ImGui::Checkbox("Another Window", &show_another_window);
@@ -150,9 +154,9 @@ int main(int, char**)
         }
 
         // 3. Show another simple window.
-        if (show_another_window)
+        // Passing a pointer to our bool variable in the Begin() call: the window will have a closing button that will clear the bool when clicked.
+        if (show_another_window && ImGui::Begin("Another Window", &show_another_window))
         {
-            ImGui::Begin("Another Window", &show_another_window);   // Pass a pointer to our bool variable (the window will have a closing button that will clear the bool when clicked)
             ImGui::Text("Hello from another window!");
             if (ImGui::Button("Close Me"))
                 show_another_window = false;

imgui.cpp

@@ -1083,6 +1083,9 @@ ImGuiIO::ImGuiIO()
     ConfigWindowsMoveFromTitleBarOnly = false;
     ConfigMemoryCompactTimer = 60.0f;
 
+    // Debug options
+    ConfigDebugBeginReturnValue = false;
+
     // Platform Functions
     BackendPlatformName = BackendRendererName = NULL;
     BackendPlatformUserData = BackendRendererUserData = BackendLanguageUserData = NULL;
@@ -4107,13 +4110,27 @@ void ImGui::NewFrame()
     UpdateDebugToolItemPicker();
 
     // Create implicit/fallback window - which we will only render it if the user has added something to it.
-    // We don't use "Debug" to avoid colliding with user trying to create a "Debug" window with custom flags.
+    // - We don't use "Debug" to avoid colliding with user trying to create a "Debug" window with custom flags.
-    // This fallback is particularly important as it avoid ImGui:: calls from crashing.
+    // - This fallback is particularly important as it avoid ImGui:: calls from crashing.
+    // - The fallback window exceptionally doesn't call End() automatically if Begin() returns false (this is intended).
     g.WithinFrameScopeWithImplicitWindow = true;
     SetNextWindowSize(ImVec2(400, 400), ImGuiCond_FirstUseEver);
     Begin("Debug##Default");
     IM_ASSERT(g.CurrentWindow->IsFallbackWindow == true);
 
+    // [DEBUG] When io.ConfigDebugBeginReturnValue is set, we make Begin() return false at different level of the window stack to validate Begin()/End() behavior in user code.
+    if (g.IO.ConfigDebugBeginReturnValue)
+    {
+        g.DebugBeginReturnValueCullDepth = (g.DebugBeginReturnValueCullDepth == -1) ? 0 : ((g.DebugBeginReturnValueCullDepth + ((g.FrameCount % 4) == 0 ? 1 : 0)) % 10);
+        char buf[64];
+        ImFormatString(buf, IM_ARRAYSIZE(buf), "Cull depth %d", g.DebugBeginReturnValueCullDepth);
+        GetForegroundDrawList()->AddText(ImVec2(0, 0), IM_COL32(255, 255, 0, 255), buf);
+    }
+    else
+    {
+        g.DebugBeginReturnValueCullDepth = -1;
+    }
+
     CallContextHooks(&g, ImGuiContextHookType_NewFramePost);
 }
 
@@ -5120,7 +5137,7 @@ bool ImGui::BeginChildEx(const char* name, ImGuiID id, const ImVec2& size_arg, b
     bool ret = Begin(title, NULL, flags);
     g.Style.ChildBorderSize = backup_border_size;
 
-    ImGuiWindow* child_window = g.CurrentWindow;
+    ImGuiWindow* child_window = g.LastBeginWindow; // FIXME-NEWBEGIN
     child_window->ChildId = id;
     child_window->AutoFitChildAxises = (ImS8)auto_fit_axises;
 
@@ -5198,6 +5215,7 @@ void ImGui::EndChild()
 // Helper to create a child window / scrolling region that looks like a normal widget frame.
 bool ImGui::BeginChildFrame(ImGuiID id, const ImVec2& size, ImGuiWindowFlags extra_flags)
 {
+    // FIXME-NEWBEGIN
     ImGuiContext& g = *GImGui;
     const ImGuiStyle& style = g.Style;
     PushStyleColor(ImGuiCol_ChildBg, style.Colors[ImGuiCol_FrameBg]);
@@ -5981,6 +5999,7 @@ bool ImGui::Begin(const char* name, bool* p_open, ImGuiWindowFlags flags)
     // We intentionally set g.CurrentWindow to NULL to prevent usage until when the viewport is set, then will call SetCurrentWindow()
     g.CurrentWindowStack.push_back(window);
     g.CurrentWindow = window;
+    g.LastBeginWindow = window;
     window->DC.StackSizesOnBegin.SetToCurrentState();
     g.CurrentWindow = NULL;
 
@@ -6740,7 +6759,24 @@ bool ImGui::Begin(const char* name, bool* p_open, ImGuiWindowFlags flags)
         window->SkipItems = skip_items;
     }
 
-    return !window->SkipItems;
+    // FIXME-OPT
+    if (window->SkipItems || g.DebugBeginReturnValueCullDepth == g.CurrentWindowStack.Size)
+    {
+        // The implicit fallback is NOT automatically ended as an exception to the rule,
+        // allowing it to always be able to receive commands without crashing.
+        if (!window->IsFallbackWindow)
+        {
+            if (window->Flags & ImGuiWindowFlags_Popup)
+                EndPopup();
+            else if (window->Flags & ImGuiWindowFlags_ChildWindow)
+                EndChild();
+            else
+                End();
+        }
+        return false;
+    }
+
+    return true;
 }
 
 void ImGui::End()
@@ -6751,6 +6787,34 @@ void ImGui::End()
     // Error checking: verify that user hasn't called End() too many times!
     if (g.CurrentWindowStack.Size <= 1 && g.WithinFrameScopeWithImplicitWindow)
     {
+        // - IMPORTANT: SINCE 1.XX (XXXX 2020): Only call a matching End() if Begin() returned true!.
+        // - IMPORTANT: BEFORE 1.XX (XXXX 2020): The return value of Begin() was inconsistent with most other BeginXXX()
+        //   functions, and would require the user to always call End() even if Begin() returned false.
+
+        // - When transitioning a codebase from < 1.XX to >= 1.XX, code needs to be refactored the following way:
+        //   Before ------------------------------------> After
+        //      ImGui::Begin("Hello");                       if (ImGui::Begin("Hello"))
+        //      ImGui::Button("OK");                         {
+        //      ImGui::End();                                    ImGui::Button("OK");
+        //                                                       ImGui::End();
+        //                                                   }
+        //
+        //   Before ------------------------------------> After
+        //      if (ImGui::Begin("Hello"))                   if (ImGui::Begin("Hello"))
+        //      {                                            {
+        //          ImGui::Button("OK");                         ImGui::Button("OK");
+        //      }                                                ImGui::End();
+        //      ImGui::End();                                }
+        //       
+        //   Before ------------------------------------> After
+        //      if (!ImGui::Begin("Hello"))                  if (!ImGui::Begin("Hello"))
+        //      {                                                return;
+        //          ImGui::End();                            ImGui::Button("OK");
+        //          return;                                  ImGui::End();
+        //      }
+        //      ImGui::Button("OK");
+        //      ImGui::End();
+
         IM_ASSERT_USER_ERROR(g.CurrentWindowStack.Size > 1, "Calling End() too many times!");
         return;
     }
@@ -8509,7 +8573,9 @@ void ImGui::BeginTooltipEx(ImGuiWindowFlags extra_flags, ImGuiTooltipFlags toolt
                 ImFormatString(window_name, IM_ARRAYSIZE(window_name), "##Tooltip_%02d", ++g.TooltipOverrideCount);
             }
     ImGuiWindowFlags flags = ImGuiWindowFlags_Tooltip | ImGuiWindowFlags_NoInputs | ImGuiWindowFlags_NoTitleBar | ImGuiWindowFlags_NoMove | ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoSavedSettings | ImGuiWindowFlags_AlwaysAutoResize | ImGuiWindowFlags_NoDocking;
-    Begin(window_name, NULL, flags | extra_flags);
+    bool ret = Begin(window_name, NULL, flags | extra_flags);
+    // FIXME-NEWBEGIN
+    IM_ASSERT(ret);
 }
 
 void ImGui::EndTooltip()
@@ -8765,11 +8831,9 @@ bool ImGui::BeginPopupEx(ImGuiID id, ImGuiWindowFlags flags)
     else
         ImFormatString(name, IM_ARRAYSIZE(name), "##Popup_%08x", id); // Not recycling, so we can close/open during the same frame
 
+    // NB: Begin can return false when the popup is completely clipped (e.g. zero size display)
     flags |= ImGuiWindowFlags_Popup | ImGuiWindowFlags_NoDocking;
     bool is_open = Begin(name, NULL, flags);
-    if (!is_open) // NB: Begin can return false when the popup is completely clipped (e.g. zero size display)
-        EndPopup();
-
     return is_open;
 }
 
@@ -8811,9 +8875,11 @@ bool ImGui::BeginPopupModal(const char* name, bool* p_open, ImGuiWindowFlags fla
     const bool is_open = Begin(name, p_open, flags);
     if (!is_open || (p_open && !*p_open)) // NB: is_open can be 'false' when the popup is completely clipped (e.g. zero size display)
     {
-        EndPopup();
         if (is_open)
+        {
+            EndPopup();
             ClosePopupToLevel(g.BeginPopupStack.Size, true);
+        }
         return false;
     }
     return is_open;
@@ -10188,7 +10254,10 @@ void ImGui::NavUpdateWindowingOverlay()
     SetNextWindowSizeConstraints(ImVec2(viewport->Size.x * 0.20f, viewport->Size.y * 0.20f), ImVec2(FLT_MAX, FLT_MAX));
     SetNextWindowPos(viewport->Pos + viewport->Size * 0.5f, ImGuiCond_Always, ImVec2(0.5f, 0.5f));
     PushStyleVar(ImGuiStyleVar_WindowPadding, g.Style.WindowPadding * 2.0f);
-    Begin("###NavWindowingList", NULL, ImGuiWindowFlags_NoTitleBar | ImGuiWindowFlags_NoFocusOnAppearing | ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoMove | ImGuiWindowFlags_NoInputs | ImGuiWindowFlags_AlwaysAutoResize | ImGuiWindowFlags_NoSavedSettings);
+    bool ret = Begin("###NavWindowingList", NULL, ImGuiWindowFlags_NoTitleBar | ImGuiWindowFlags_NoFocusOnAppearing | ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoMove | ImGuiWindowFlags_NoInputs | ImGuiWindowFlags_AlwaysAutoResize | ImGuiWindowFlags_NoSavedSettings);
+    PopStyleVar();
+    if (!ret)
+        return;
     for (int n = g.WindowsFocusOrder.Size - 1; n >= 0; n--)
     {
         ImGuiWindow* window = g.WindowsFocusOrder[n];
@@ -10200,7 +10269,6 @@ void ImGui::NavUpdateWindowingOverlay()
         Selectable(label, g.NavWindowingTarget == window);
     }
     End();
-    PopStyleVar();
 }
 
 
@@ -15680,10 +15748,7 @@ static void MetricsHelpMarker(const char* desc)
 void ImGui::ShowMetricsWindow(bool* p_open)
 {
     if (!Begin("Dear ImGui Metrics/Debugger", p_open))
-    {
-        End();
         return;
-    }
 
     ImGuiContext& g = *GImGui;
     ImGuiIO& io = g.IO;

imgui.h

@@ -68,6 +68,9 @@ Index of this file:
 #define IMGUI_HAS_VIEWPORT          1 // Viewport WIP branch
 #define IMGUI_HAS_DOCK              1 // Docking WIP branch
 
+// Features
+#define IMGUI_HAS_NEWBEGIN          1
+
 // Define attributes of all API symbols declarations (e.g. for DLL under Windows)
 // IMGUI_API is used for core imgui functions, IMGUI_IMPL_API is used for the default backends files (imgui_impl_xxx.h)
 // Using dear imgui via a shared library is not recommended, because we don't guarantee backward nor forward ABI compatibility (also function call overhead, as dear imgui is a call-heavy API)
@@ -297,10 +300,10 @@ namespace ImGui
     // - You may append multiple times to the same window during the same frame by calling Begin()/End() pairs multiple times.
     //   Some information such as 'flags' or 'p_open' will only be considered by the first call to Begin().
     // - Begin() return false to indicate the window is collapsed or fully clipped, so you may early out and omit submitting
-    //   anything to the window. Always call a matching End() for each Begin() call, regardless of its return value!
+    //   anything to the window.
-    //   [Important: due to legacy reason, this is inconsistent with most other functions such as BeginMenu/EndMenu,
+    // - IMPORTANT: SINCE 1.XX (XXXX 2020): Only call a matching End() if Begin() returned true!.
-    //    BeginPopup/EndPopup, etc. where the EndXXX call should only be called if the corresponding BeginXXX function
+    // - IMPORTANT: BEFORE 1.XX (XXXX 2020): The return value of Begin() was inconsistent with most other BeginXXX()
-    //    returned true. Begin and BeginChild are the only odd ones out. Will be fixed in a future update.]
+    //   functions, and would require the user to always call End() even if Begin() returned false.
     // - Note that the bottom of window stack always contains a window called "Debug".
     IMGUI_API bool          Begin(const char* name, bool* p_open = NULL, ImGuiWindowFlags flags = 0);
     IMGUI_API void          End();
@@ -309,10 +312,9 @@ namespace ImGui
     // - Use child windows to begin into a self-contained independent scrolling/clipping regions within a host window. Child windows can embed their own child.
     // - For each independent axis of 'size': ==0.0f: use remaining host window size / >0.0f: fixed size / <0.0f: use remaining window size minus abs(size) / Each axis can use a different mode, e.g. ImVec2(0,400).
     // - BeginChild() returns false to indicate the window is collapsed or fully clipped, so you may early out and omit submitting anything to the window.
-    //   Always call a matching EndChild() for each BeginChild() call, regardless of its return value.
+    // - IMPORTANT: SINCE 1.XX (XXXX 2020): Only call a matching EndChild() if BeginChild() returned true!.
-    //   [Important: due to legacy reason, this is inconsistent with most other functions such as BeginMenu/EndMenu,
+    // - IMPORTANT: BEFORE 1.XX (XXXX 2020): The return value of BeginChild() was inconsistent with most other BeginXXX()
-    //    BeginPopup/EndPopup, etc. where the EndXXX call should only be called if the corresponding BeginXXX function
+    //   functions, and would require the user to always call EndChild() even if BeginChild() returned false. This has been changed.
-    //    returned true. Begin and BeginChild are the only odd ones out. Will be fixed in a future update.]
     IMGUI_API bool          BeginChild(const char* str_id, const ImVec2& size = ImVec2(0, 0), bool border = false, ImGuiWindowFlags flags = 0);
     IMGUI_API bool          BeginChild(ImGuiID id, const ImVec2& size = ImVec2(0, 0), bool border = false, ImGuiWindowFlags flags = 0);
     IMGUI_API void          EndChild();
@@ -1821,6 +1823,9 @@ struct ImGuiIO
     bool        ConfigWindowsMoveFromTitleBarOnly; // = false       // [BETA] Set to true to only allow moving windows when clicked+dragged from the title bar. Windows without a title bar are not affected.
     float       ConfigMemoryCompactTimer;       // = 60.0f          // [BETA] Free transient windows/tables memory buffers when unused for given amount of time. Set to -1.0f to disable.
 
+    // Debug options
+    bool        ConfigDebugBeginReturnValue;    // = false          // When set, some calls to Begin() will return false to facilitate testing and transitioning to 1.78 Begin()/End() pairing behavior. Will cycle through each unique window depth then repeat. Suggested use: add "io.ConfigDebugBeginReturnValue = io.KeyShift" in your main loop then occasionally press SHIFT. Windows should be flickering. Your code will assert in End() if calling End() incorrectly.
+
     //------------------------------------------------------------------
     // Platform Functions
     // (the imgui_impl_xxxx backend files are setting those up for you)

imgui_internal.h

@@ -1438,6 +1438,7 @@ struct ImGuiContext
     ImGuiWindow*            HoveredWindowUnderMovingWindow;     // Hovered window ignoring MovingWindow. Only set if MovingWindow is set.
     ImGuiDockNode*          HoveredDockNode;                    // Hovered dock node.
     ImGuiWindow*            MovingWindow;                       // Track the window we clicked on (in order to preserve focus). The actual window that is moved is generally MovingWindow->RootWindow.
+    ImGuiWindow*            LastBeginWindow;                    // Track the last window we called Begin() on, this is used to easily access it even if Begin() returned false.
     ImGuiWindow*            WheelingWindow;                     // Track the window we started mouse-wheeling on. Until a timer elapse or mouse has moved, generally keep scrolling the same window even if during the course of scrolling the mouse ends up hovering a child window.
     ImVec2                  WheelingWindowRefMousePos;
     float                   WheelingWindowTimer;
@@ -1640,6 +1641,7 @@ struct ImGuiContext
     // Debug Tools
     bool                    DebugItemPickerActive;              // Item picker is active (started with DebugStartItemPicker())
     ImGuiID                 DebugItemPickerBreakId;             // Will call IM_DEBUG_BREAK() when encountering this id
+    int                     DebugBeginReturnValueCullDepth;     // Cycle between 0..9 then wrap around.
     ImGuiMetricsConfig      DebugMetricsConfig;
 
     // Misc
@@ -1675,6 +1677,7 @@ struct ImGuiContext
         HoveredWindowUnderMovingWindow = NULL;
         HoveredDockNode = NULL;
         MovingWindow = NULL;
+        LastBeginWindow = NULL;
         WheelingWindow = NULL;
         WheelingWindowTimer = 0.0f;
 
@@ -1793,6 +1796,7 @@ struct ImGuiContext
 
         DebugItemPickerActive = false;
         DebugItemPickerBreakId = 0;
+        DebugBeginReturnValueCullDepth = -1;
 
         memset(FramerateSecPerFrame, 0, sizeof(FramerateSecPerFrame));
         FramerateSecPerFrameIdx = 0;

imgui_widgets.cpp

@@ -1627,7 +1627,6 @@ bool ImGui::BeginCombo(const char* label, const char* preview_value, ImGuiComboF
     PopStyleVar();
     if (!ret)
     {
-        EndPopup();
         IM_ASSERT(0);   // This should never happen as we tested for IsPopupOpen() above
         return false;
     }
@@ -3838,7 +3837,6 @@ bool ImGui::InputTextEx(const char* label, const char* hint, char* buf, int buf_
         PopStyleColor();
         if (!child_visible)
         {
-            EndChild();
             EndGroup();
             return false;
         }
@@ -6133,8 +6131,8 @@ bool ImGui::ListBoxHeader(const char* label, const ImVec2& size_arg)
     if (label_size.x > 0)
         RenderText(ImVec2(frame_bb.Max.x + style.ItemInnerSpacing.x, frame_bb.Min.y + style.FramePadding.y), label);
 
-    BeginChildFrame(id, frame_bb.GetSize());
+    // FIXME-NEWBEGIN
-    return true;
+    return BeginChildFrame(id, frame_bb.GetSize());
 }
 
 // FIXME: In principle this function should be called EndListBox(). We should rename it after re-evaluating if we want to keep the same signature.
@@ -6568,10 +6566,7 @@ bool ImGui::BeginMainMenuBar()
 
     g.NextWindowData.MenuBarOffsetMinVal = ImVec2(0.0f, 0.0f);
     if (!is_open)
-    {
-        End();
         return false;
-    }
     return true; //-V1020
 }
 

misc/freetype/README.md

@@ -104,7 +104,8 @@ struct FreeTypeTest
     // Call to draw interface
     void ShowFreetypeOptionsWindow()
     {
-        ImGui::Begin("FreeType Options");
+        if (!ImGui::Begin("FreeType Options"))
+            return;
         ImGui::ShowFontSelector("Fonts");
         WantRebuild |= ImGui::RadioButton("FreeType", (int*)&BuildMode, FontBuildMode_FreeType);
         ImGui::SameLine();