Begin: WIP consistent Begin/End behavior, ListBoxHeader() fix.

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,29 @@ 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.
-    // This fallback is particularly important as it avoid ImGui:: calls from crashing.
+    // - 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.
+    // - 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");
+    bool ret = Begin("Debug##Default");
+    IM_UNUSED(ret);
+    IM_ASSERT(ret);
     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);
 }
 
@@ -4134,11 +4153,13 @@ void ImGui::UpdateDebugToolItemPicker()
             g.DebugItemPickerActive = false;
         }
         ImGui::SetNextWindowBgAlpha(0.60f);
-        ImGui::BeginTooltip();
-        ImGui::Text("HoveredId: 0x%08X", hovered_id);
-        ImGui::Text("Press ESC to abort picking.");
-        ImGui::TextColored(GetStyleColorVec4(hovered_id ? ImGuiCol_Text : ImGuiCol_TextDisabled), "Click to break in debugger!");
-        ImGui::EndTooltip();
+        if (ImGui::BeginTooltip())
+        {
+            ImGui::Text("HoveredId: 0x%08X", hovered_id);
+            ImGui::Text("Press ESC to abort picking.");
+            ImGui::TextColored(GetStyleColorVec4(hovered_id ? ImGuiCol_Text : ImGuiCol_TextDisabled), "Click to break in debugger!");
+            ImGui::EndTooltip();
+        }
     }
 }
 
@@ -5120,15 +5141,10 @@ 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;
 
-    // Set the cursor to handle case where the user called SetNextWindowPos()+BeginChild() manually.
-    // While this is not really documented/defined, it seems that the expected thing to do.
-    if (child_window->BeginCount == 1)
-        parent_window->DC.CursorPos = child_window->Pos;
-
     // Process navigation-in immediately so NavInit can run on first frame
     if (g.NavActivateId == id && !(flags & ImGuiWindowFlags_NavFlattened) && (child_window->DC.NavLayerActiveMask != 0 || child_window->DC.NavHasScroll))
     {
@@ -5160,6 +5176,11 @@ void ImGui::EndChild()
     IM_ASSERT(g.WithinEndChild == false);
     IM_ASSERT(window->Flags & ImGuiWindowFlags_ChildWindow);   // Mismatched BeginChild()/EndChild() calls
 
+    // Set the cursor to handle case where the user called SetNextWindowPos()+BeginChild() manually.
+    // While this is not really documented/defined, it seems that the expected thing to do.
+    if (window->BeginCount == 1)
+        window->ParentWindow->DC.CursorPos = window->Pos;
+
     g.WithinEndChild = true;
     if (window->BeginCount > 1)
     {
@@ -5981,6 +6002,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 +6762,24 @@ bool ImGui::Begin(const char* name, bool* p_open, ImGuiWindowFlags flags)
         window->SkipItems = skip_items;
     }
 
-    return !window->SkipItems;
+    // FIXME-OPT
+    bool debug_skip = (g.DebugBeginReturnValueCullDepth == g.CurrentWindowStack.Size) && (window->Flags & ImGuiWindowFlags_DockNodeHost) == 0;
+    if (window->SkipItems || debug_skip)
+    {
+        // 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)
+            return true;
+
+        if (window->Flags & ImGuiWindowFlags_Popup)
+            EndPopup();
+        else if (window->Flags & ImGuiWindowFlags_ChildWindow)
+            EndChild();
+        else
+            End();
+        return false;
+    }
+    return true;
 }
 
 void ImGui::End()
@@ -6751,6 +6790,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;
     }
@@ -8475,12 +8542,12 @@ void ImGui::SetScrollHereY(float center_y_ratio)
 // [SECTION] TOOLTIPS
 //-----------------------------------------------------------------------------
 
-void ImGui::BeginTooltip()
+bool ImGui::BeginTooltip()
 {
-    BeginTooltipEx(ImGuiWindowFlags_None, ImGuiTooltipFlags_None);
+    return BeginTooltipEx(ImGuiWindowFlags_None, ImGuiTooltipFlags_None);
 }
 
-void ImGui::BeginTooltipEx(ImGuiWindowFlags extra_flags, ImGuiTooltipFlags tooltip_flags)
+bool ImGui::BeginTooltipEx(ImGuiWindowFlags extra_flags, ImGuiTooltipFlags tooltip_flags)
 {
     ImGuiContext& g = *GImGui;
 
@@ -8509,7 +8576,11 @@ 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: adding a bool to API...
+    //IM_UNUSED(ret);
+    //IM_ASSERT(ret);
+    return ret;
 }
 
 void ImGui::EndTooltip()
@@ -8520,7 +8591,8 @@ void ImGui::EndTooltip()
 
 void ImGui::SetTooltipV(const char* fmt, va_list args)
 {
-    BeginTooltipEx(0, ImGuiTooltipFlags_OverridePreviousTooltip);
+    if (!BeginTooltipEx(0, ImGuiTooltipFlags_OverridePreviousTooltip))
+        return;
     TextV(fmt, args);
     EndTooltip();
 }
@@ -8765,11 +8837,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 +8881,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 +10260,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 +10275,6 @@ void ImGui::NavUpdateWindowingOverlay()
         Selectable(label, g.NavWindowingTarget == window);
     }
     End();
-    PopStyleVar();
 }
 
 
@@ -10312,7 +10386,9 @@ bool ImGui::BeginDragDropSource(ImGuiDragDropFlags flags)
         {
             // Target can request the Source to not display its tooltip (we use a dedicated flag to make this request explicit)
             // We unfortunately can't just modify the source flags and skip the call to BeginTooltip, as caller may be emitting contents.
-            BeginTooltip();
+            bool ret = BeginTooltip(); // FIXME-NEWBEGIN: problematic
+            IM_UNUSED(ret);
+            IM_ASSERT(ret);
             if (g.DragDropAcceptIdPrev && (g.DragDropAcceptFlags & ImGuiDragDropFlags_AcceptNoPreviewTooltip))
             {
                 ImGuiWindow* tooltip_window = g.CurrentWindow;
@@ -13201,8 +13277,10 @@ static void ImGui::DockNodeUpdate(ImGuiDockNode* node)
             window_flags |= ImGuiWindowFlags_NoTitleBar;
 
             PushStyleVar(ImGuiStyleVar_WindowPadding, ImVec2(0, 0));
-            Begin(window_label, NULL, window_flags);
+            bool ret = Begin(window_label, NULL, window_flags);
             PopStyleVar();
+            IM_UNUSED(ret);
+            IM_ASSERT(ret); // FIXME-NEWBEGIN
             beginned_into_host_window = true;
 
             node->HostWindow = host_window = g.CurrentWindow;
@@ -13385,7 +13463,8 @@ bool ImGui::DockNodeBeginAmendTabBar(ImGuiDockNode* node)
         return false;
     if (node->SharedFlags & ImGuiDockNodeFlags_KeepAliveOnly)
         return false;
-    Begin(node->HostWindow->Name);
+    if (!Begin(node->HostWindow->Name))
+        return false;
     PushOverrideID(node->ID);
     bool ret = BeginTabBarEx(node->TabBar, node->TabBar->BarRect, node->TabBar->Flags, node);
     IM_ASSERT(ret);
@@ -14472,10 +14551,12 @@ void ImGui::DockSpace(ImGuiID id, const ImVec2& size_arg, ImGuiDockNodeFlags fla
     if (node->Windows.Size > 0 || node->IsSplitNode())
         PushStyleColor(ImGuiCol_ChildBg, IM_COL32(0, 0, 0, 0));
     PushStyleVar(ImGuiStyleVar_ChildBorderSize, 0.0f);
-    Begin(title, NULL, window_flags);
+    bool ret = Begin(title, NULL, window_flags);
     PopStyleVar();
     if (node->Windows.Size > 0 || node->IsSplitNode())
         PopStyleColor();
+    if (!ret)
+        return; // FIXME-NEWBEGIN
 
     ImGuiWindow* host_window = g.CurrentWindow;
     host_window->DockNodeAsHost = node;
@@ -14526,12 +14607,16 @@ ImGuiID ImGui::DockSpaceOverViewport(ImGuiViewport* viewport, ImGuiDockNodeFlags
     PushStyleVar(ImGuiStyleVar_WindowRounding, 0.0f);
     PushStyleVar(ImGuiStyleVar_WindowBorderSize, 0.0f);
     PushStyleVar(ImGuiStyleVar_WindowPadding, ImVec2(0.0f, 0.0f));
-    Begin(label, NULL, host_window_flags);
+    bool ret = Begin(label, NULL, host_window_flags);
     PopStyleVar(3);
-
     ImGuiID dockspace_id = GetID("DockSpace");
-    DockSpace(dockspace_id, ImVec2(0.0f, 0.0f), dockspace_flags, window_class);
-    End();
+
+    // FIXME-NEWBEGIN: KeepAlive if not visible?
+    if (ret)
+    {
+        DockSpace(dockspace_id, ImVec2(0.0f, 0.0f), dockspace_flags, window_class);
+        End();
+    }
 
     return dockspace_id;
 }
@@ -15667,9 +15752,8 @@ static void RenderViewportsThumbnails()
 static void MetricsHelpMarker(const char* desc)
 {
     ImGui::TextDisabled("(?)");
-    if (ImGui::IsItemHovered())
+    if (ImGui::IsItemHovered() && ImGui::BeginTooltip())
     {
-        ImGui::BeginTooltip();
         ImGui::PushTextWrapPos(ImGui::GetFontSize() * 35.0f);
         ImGui::TextUnformatted(desc);
         ImGui::PopTextWrapPos();
@@ -15680,10 +15764,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)
@@ -101,6 +104,16 @@ Index of this file:
 #define IM_FMTLIST(FMT)
 #endif
 
+#if (__cplusplus >= 201703)
+#define IM_NODISCARD                [[nodiscard]]
+#elif defined(__GNUC__) && (__GNUC__ >= 4)
+#define IM_NODISCARD                __attribute__ ((warn_unused_result))
+#elif defined(_MSC_VER) && (_MSC_VER >= 1700)
+#define IM_NODISCARD                _Check_return_
+#else
+#define IM_NODISCARD
+#endif
+
 // Warnings
 #if defined(__clang__)
 #pragma clang diagnostic push
@@ -297,24 +310,23 @@ 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!
-    //   [Important: due to legacy reason, this is inconsistent with most other functions such as BeginMenu/EndMenu,
-    //    BeginPopup/EndPopup, etc. where the EndXXX call should only be called if the corresponding BeginXXX function
-    //    returned true. Begin and BeginChild are the only odd ones out. Will be fixed in a future update.]
+    //   anything to the window.
+    // - 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.
     // - 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);
+    IM_NODISCARD IMGUI_API bool Begin(const char* name, bool* p_open = NULL, ImGuiWindowFlags flags = 0);
     IMGUI_API void          End();
 
     // Child Windows
     // - 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: due to legacy reason, this is inconsistent with most other functions such as BeginMenu/EndMenu,
-    //    BeginPopup/EndPopup, etc. where the EndXXX call should only be called if the corresponding BeginXXX function
-    //    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);
+    // - IMPORTANT: SINCE 1.XX (XXXX 2020): Only call a matching EndChild() if BeginChild() returned true!.
+    // - IMPORTANT: BEFORE 1.XX (XXXX 2020): The return value of BeginChild() was inconsistent with most other BeginXXX()
+    //   functions, and would require the user to always call EndChild() even if BeginChild() returned false. This has been changed.
+    IM_NODISCARD IMGUI_API bool          BeginChild(const char* str_id, const ImVec2& size = ImVec2(0, 0), bool border = false, ImGuiWindowFlags flags = 0);
+    IM_NODISCARD IMGUI_API bool          BeginChild(ImGuiID id, const ImVec2& size = ImVec2(0, 0), bool border = false, ImGuiWindowFlags flags = 0);
     IMGUI_API void          EndChild();
 
     // Windows Utilities
@@ -622,7 +634,7 @@ namespace ImGui
 
     // Tooltips
     // - Tooltip are windows following the mouse which do not take focus away.
-    IMGUI_API void          BeginTooltip();                                                     // begin/append a tooltip window. to create full-featured tooltip (with any kind of items).
+    IMGUI_API bool          BeginTooltip();                                                     // begin/append a tooltip window. to create full-featured tooltip (with any kind of items).
     IMGUI_API void          EndTooltip();
     IMGUI_API void          SetTooltip(const char* fmt, ...) IM_FMTARGS(1);                     // set a text-only tooltip, typically use with ImGui::IsItemHovered(). override any previous call to SetTooltip().
     IMGUI_API void          SetTooltipV(const char* fmt, va_list args) IM_FMTLIST(1);
@@ -822,7 +834,7 @@ namespace ImGui
     IMGUI_API void          SetStateStorage(ImGuiStorage* storage);                             // replace current window storage with our own (if you want to manipulate it yourself, typically clear subsection of it)
     IMGUI_API ImGuiStorage* GetStateStorage();
     IMGUI_API void          CalcListClipping(int items_count, float items_height, int* out_items_display_start, int* out_items_display_end);    // calculate coarse clipping for large list of evenly sized items. Prefer using the ImGuiListClipper higher-level helper if you can.
-    IMGUI_API bool          BeginChildFrame(ImGuiID id, const ImVec2& size, ImGuiWindowFlags flags = 0); // helper to create a child window / scrolling region that looks like a normal widget frame
+    IM_NODISCARD IMGUI_API bool          BeginChildFrame(ImGuiID id, const ImVec2& size, ImGuiWindowFlags flags = 0); // helper to create a child window / scrolling region that looks like a normal widget frame
     IMGUI_API void          EndChildFrame();                                                    // always call EndChildFrame() regardless of BeginChildFrame() return values (which indicates a collapsed/clipped window)
 
     // Text Utilities
@@ -1821,6 +1833,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;
@@ -2445,7 +2449,7 @@ namespace ImGui
     IMGUI_API void          ClosePopupsOverWindow(ImGuiWindow* ref_window, bool restore_focus_to_window_under_popup);
     IMGUI_API bool          IsPopupOpen(ImGuiID id, ImGuiPopupFlags popup_flags);
     IMGUI_API bool          BeginPopupEx(ImGuiID id, ImGuiWindowFlags extra_flags);
-    IMGUI_API void          BeginTooltipEx(ImGuiWindowFlags extra_flags, ImGuiTooltipFlags tooltip_flags);
+    IMGUI_API bool          BeginTooltipEx(ImGuiWindowFlags extra_flags, ImGuiTooltipFlags tooltip_flags);
     IMGUI_API ImGuiWindow*  GetTopMostPopupModal();
     IMGUI_API ImVec2        FindBestWindowPosForPopup(ImGuiWindow* window);
     IMGUI_API ImVec2        FindBestWindowPosForPopupEx(const ImVec2& ref_pos, const ImVec2& size, ImGuiDir* last_dir, const ImRect& r_outer, const ImRect& r_avoid, ImGuiPopupPositionPolicy policy);

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;
         }
@@ -5355,7 +5353,8 @@ void ImGui::ColorTooltip(const char* text, const float* col, ImGuiColorEditFlags
 {
     ImGuiContext& g = *GImGui;
 
-    BeginTooltipEx(0, ImGuiTooltipFlags_OverridePreviousTooltip);
+    if (!BeginTooltipEx(0, ImGuiTooltipFlags_OverridePreviousTooltip))
+        return;
     const char* text_end = text ? FindRenderedTextEnd(text, NULL) : text;
     if (text_end > text)
     {
@@ -6133,8 +6132,11 @@ 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());
-    return true;
+    // FIXME-NEWBEGIN: Use to be return true so we'll trigger more issues.
+    bool ret = BeginChildFrame(id, frame_bb.GetSize());
+    if (!ret)
+        EndGroup();
+    return ret;
 }
 
 // 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 +6570,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();