Clarified comments about popups input blocking and ImGuiHoveredFlags_AllowWhenBlockedByPopup flag. (#3154)
diff --git a/imgui.h b/imgui.h
index bdc241f..f2b1cd9 100644
--- a/imgui.h
+++ b/imgui.h
@@ -591,13 +591,16 @@
// Popups, Modals
// The properties of popups windows are:
- // - They block normal mouse hovering detection outside them. (*)
+ // - They block normal mouse hovering detection outside them. (*1)
// - Unless modal, they can be closed by clicking anywhere outside them, or by pressing ESCAPE.
- // - Their visibility state (~bool) is held internally by imgui instead of being held by the programmer as we are used to with regular Begin() calls.
- // User can manipulate the visibility state by calling OpenPopup().
+ // Because hovering detection is disabled outside the popup, when clicking outside the click will not be seen by underlying widgets! (*1)
+ // - Their visibility state (~bool) is held internally by Dear ImGui instead of being held by the programmer as we are used to with regular Begin() calls.
+ // User can manipulate the visibility state by calling OpenPopup(), CloseCurrentPopup() etc.
// - We default to use the right mouse (ImGuiMouseButton_Right=1) for the Popup Context functions.
- // (*) You can use IsItemHovered(ImGuiHoveredFlags_AllowWhenBlockedByPopup) to bypass it and detect hovering even when normally blocked by a popup.
- // Those three properties are connected. The library needs to hold their visibility state because it can close popups at any time.
+ // Those three properties are connected: we need to retain popup visibility state in the library because popups may be closed as any time.
+ // (*1) You can bypass that restriction and detect hovering even when normally blocked by a popup.
+ // To do this use the ImGuiHoveredFlags_AllowWhenBlockedByPopup when calling IsItemHovered() or IsWindowHovered().
+ // This is what BeginPopupContextItem() and BeginPopupContextWindow() are doing already, allowing a right-click to reopen another popups without losing the click.
IMGUI_API void OpenPopup(const char* str_id); // call to mark popup as open (don't call every frame!). popups are closed when user click outside, or if CloseCurrentPopup() is called within a BeginPopup()/EndPopup() block. By default, Selectable()/MenuItem() are calling CloseCurrentPopup(). Popup identifiers are relative to the current ID-stack (so OpenPopup and BeginPopup needs to be at the same level).
IMGUI_API bool BeginPopup(const char* str_id, ImGuiWindowFlags flags = 0); // return true if the popup is open, and you can start outputting to it. only call EndPopup() if BeginPopup() returns true!
IMGUI_API bool BeginPopupContextItem(const char* str_id = NULL, ImGuiMouseButton mouse_button = 1); // helper to open and begin popup when clicked on last item. if you can pass a NULL str_id only if the previous item had an id. If you want to use that on a non-interactive item such as Text() you need to pass in an explicit ID here. read comments in .cpp!
