Renamed CaptureMouseFromApp() and CaptureKeyboardFromApp() to SetNextFrameWantCaptureMouse() and SetNextFrameWantCaptureKeyboard(). Added demo. (#5304, #4831, #4480, #533)
diff --git a/docs/CHANGELOG.txt b/docs/CHANGELOG.txt
index 99b8906..6dc978e 100644
--- a/docs/CHANGELOG.txt
+++ b/docs/CHANGELOG.txt
@@ -37,6 +37,9 @@
Breaking changes:
+- Renamed CaptureMouseFromApp() and CaptureKeyboardFromApp() to SetNextFrameWantCaptureMouse()
+ and SetNextFrameWantCaptureKeyboard() to clarify purpose, old name was too misleading.
+ Kept inline redirection functions (will obsolete).
- Renamed ImGuiKeyModFlags to ImGuiModFlags. Kept inline redirection enums (will obsolete).
(This was never used in public API functions but technically present in imgui.h and ImGuiIO).
- Backends: OSX: Removed ImGui_ImplOSX_HandleEvent() from backend API in favor of backend
@@ -95,6 +98,7 @@
- DrawList: Circle with a radius smaller than 0.5f won't appear, to be consistent with other primitives. [@thedmd]
- Debug: Added DebugTextEncoding() function to facilitate diagnosing issues when not sure about whether
you have a UTF-8 text encoding issue or a font loading issue. [@LaMarche05, @ocornut]
+- Demo: Add better demo of how to use SetNextFrameWantCaptureMouse()/SetNextFrameWantCaptureKeyboard().
- Metrics: Added a "UTF-8 Encoding Viewer" section using the aforementioned DebugTextEncoding() function.
- Misc: Fixed calling GetID("label") _before_ a widget emitting this item inside a group (such as InputInt())
from causing an assertion when closing the group. (#5181).
diff --git a/imgui.cpp b/imgui.cpp
index f5408fa..632df57 100644
--- a/imgui.cpp
+++ b/imgui.cpp
@@ -7767,16 +7767,16 @@
g.MouseCursor = cursor_type;
}
-void ImGui::CaptureKeyboardFromApp(bool capture)
+void ImGui::SetNextFrameWantCaptureKeyboard(bool want_capture_keyboard)
{
ImGuiContext& g = *GImGui;
- g.WantCaptureKeyboardNextFrame = capture ? 1 : 0;
+ g.WantCaptureKeyboardNextFrame = want_capture_keyboard ? 1 : 0;
}
-void ImGui::CaptureMouseFromApp(bool capture)
+void ImGui::SetNextFrameWantCaptureMouse(bool want_capture_mouse)
{
ImGuiContext& g = *GImGui;
- g.WantCaptureMouseNextFrame = capture ? 1 : 0;
+ g.WantCaptureMouseNextFrame = want_capture_mouse ? 1 : 0;
}
static const char* GetInputSourceName(ImGuiInputSource source)
diff --git a/imgui.h b/imgui.h
index 7db6d1e..859cdd8 100644
--- a/imgui.h
+++ b/imgui.h
@@ -65,7 +65,7 @@
// Version
// (Integer encoded as XYYZZ for use in #if preprocessor conditionals. Work in progress versions typically starts at XYY99 then bounce up to XYY00, XYY01 etc. when release tagging happens)
#define IMGUI_VERSION "1.88 WIP"
-#define IMGUI_VERSION_NUM 18722
+#define IMGUI_VERSION_NUM 18723
#define IMGUI_CHECKVERSION() ImGui::DebugCheckVersionAndDataLayout(IMGUI_VERSION, sizeof(ImGuiIO), sizeof(ImGuiStyle), sizeof(ImVec2), sizeof(ImVec4), sizeof(ImDrawVert), sizeof(ImDrawIdx))
#define IMGUI_HAS_TABLE
@@ -881,7 +881,7 @@
IMGUI_API bool IsKeyReleased(ImGuiKey key); // was key released (went from Down to !Down)?
IMGUI_API int GetKeyPressedAmount(ImGuiKey key, float repeat_delay, float rate); // uses provided repeat rate/delay. return a count, most often 0 or 1 but might be >1 if RepeatRate is small enough that DeltaTime > RepeatRate
IMGUI_API const char* GetKeyName(ImGuiKey key); // [DEBUG] returns English name of the key. Those names a provided for debugging purpose and are not meant to be saved persistently not compared.
- IMGUI_API void CaptureKeyboardFromApp(bool want_capture_keyboard_value = true); // attention: misleading name! manually override io.WantCaptureKeyboard flag next frame (said flag is entirely left for your application to handle). e.g. force capture keyboard when your widget is being hovered. This is equivalent to setting "io.WantCaptureKeyboard = want_capture_keyboard_value"; after the next NewFrame() call.
+ IMGUI_API void SetNextFrameWantCaptureKeyboard(bool want_capture_keyboard); // Override io.WantCaptureKeyboard flag next frame (said flag is left for your application to handle, typically when true it instructs your app to ignore inputs). e.g. force capture keyboard when your widget is being hovered. This is equivalent to setting "io.WantCaptureKeyboard = want_capture_keyboard"; after the next NewFrame() call.
// Inputs Utilities: Mouse
// - To refer to a mouse button, you may use named enums in your code e.g. ImGuiMouseButton_Left, ImGuiMouseButton_Right.
@@ -902,7 +902,7 @@
IMGUI_API void ResetMouseDragDelta(ImGuiMouseButton button = 0); //
IMGUI_API ImGuiMouseCursor GetMouseCursor(); // get desired cursor type, reset in ImGui::NewFrame(), this is updated during the frame. valid before Render(). If you use software rendering by setting io.MouseDrawCursor ImGui will render those for you
IMGUI_API void SetMouseCursor(ImGuiMouseCursor cursor_type); // set desired cursor type
- IMGUI_API void CaptureMouseFromApp(bool want_capture_mouse_value = true); // attention: misleading name! manually override io.WantCaptureMouse flag next frame (said flag is entirely left for your application to handle). This is equivalent to setting "io.WantCaptureMouse = want_capture_mouse_value;" after the next NewFrame() call.
+ IMGUI_API void SetNextFrameWantCaptureMouse(bool want_capture_mouse); // Override io.WantCaptureMouse flag next frame (said flag is left for your application to handle, typical when true it instucts your app to ignore inputs). This is equivalent to setting "io.WantCaptureMouse = want_capture_mouse;" after the next NewFrame() call.
// Clipboard Utilities
// - Also see the LogToClipboard() function to capture GUI into clipboard, or easily output text data to the clipboard.
@@ -2961,16 +2961,19 @@
#ifndef IMGUI_DISABLE_OBSOLETE_FUNCTIONS
namespace ImGui
{
+ // OBSOLETED in 1.88 (from May 2022)
+ static inline void CaptureKeyboardFromApp(bool want_capture_keyboard = true) { SetNextFrameWantCaptureKeyboard(want_capture_keyboard); } // Renamed as name was misleading + removed default value.
+ static inline void CaptureMouseFromApp(bool want_capture_mouse = true) { SetNextFrameWantCaptureMouse(want_capture_mouse); } // Renamed as name was misleading + removed default value.
// OBSOLETED in 1.86 (from November 2021)
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 ImGuiListClipper.
// OBSOLETED in 1.85 (from August 2021)
- static inline float GetWindowContentRegionWidth() { return GetWindowContentRegionMax().x - GetWindowContentRegionMin().x; }
+ static inline float GetWindowContentRegionWidth() { return GetWindowContentRegionMax().x - GetWindowContentRegionMin().x; }
// OBSOLETED in 1.81 (from February 2021)
IMGUI_API bool ListBoxHeader(const char* label, int items_count, int height_in_items = -1); // Helper to calculate size from items_count and height_in_items
- static inline bool ListBoxHeader(const char* label, const ImVec2& size = ImVec2(0, 0)) { return BeginListBox(label, size); }
+ static inline bool ListBoxHeader(const char* label, const ImVec2& size = ImVec2(0, 0)) { return BeginListBox(label, size); }
static inline void ListBoxFooter() { EndListBox(); }
// OBSOLETED in 1.79 (from August 2020)
- static inline void OpenPopupContextItem(const char* str_id = NULL, ImGuiMouseButton mb = 1) { OpenPopupOnItemClick(str_id, mb); } // Bool return value removed. Use IsWindowAppearing() in BeginPopup() instead. Renamed in 1.77, renamed back in 1.79. Sorry!
+ static inline void OpenPopupContextItem(const char* str_id = NULL, ImGuiMouseButton mb = 1) { OpenPopupOnItemClick(str_id, mb); } // Bool return value removed. Use IsWindowAppearing() in BeginPopup() instead. Renamed in 1.77, renamed back in 1.79. Sorry!
// OBSOLETED in 1.78 (from June 2020)
// Old drag/sliders functions that took a 'float power = 1.0' argument instead of flags.
// For shared code, you can version check at compile-time with `#if IMGUI_VERSION_NUM >= 17704`.
diff --git a/imgui_demo.cpp b/imgui_demo.cpp
index eb1e58a..a6a82be 100644
--- a/imgui_demo.cpp
+++ b/imgui_demo.cpp
@@ -5781,13 +5781,35 @@
if (ImGui::TreeNode("Capture override"))
{
- ImGui::Button("Hovering me sets the\nkeyboard capture flag");
- if (ImGui::IsItemHovered())
- ImGui::CaptureKeyboardFromApp(true);
- ImGui::SameLine();
- ImGui::Button("Holding me clears the\nthe keyboard capture flag");
- if (ImGui::IsItemActive())
- ImGui::CaptureKeyboardFromApp(false);
+ HelpMarker(
+ "The value of io.WantCaptureMouse and io.WantCaptureKeyboard are normally set by Dear ImGui "
+ "to instruct your application of how to route inputs. Typically, when a value is true, it means "
+ "Dear ImGui wants the corresponding inputs and we expect the underlying application to ignore them.\n\n"
+ "The most typical case is: when hovering a window, Dear ImGui set io.WantCaptureMouse to true, "
+ "and underlying application should ignore mouse inputs (in practice there are many and more subtle "
+ "rules leading to how those flags are set).");
+
+ ImGui::Text("io.WantCaptureMouse: %d", io.WantCaptureMouse);
+ ImGui::Text("io.WantCaptureMouseUnlessPopupClose: %d", io.WantCaptureMouseUnlessPopupClose);
+ ImGui::Text("io.WantCaptureKeyboard: %d", io.WantCaptureKeyboard);
+
+ HelpMarker(
+ "Hovering the colored canvas will override io.WantCaptureXXX fields.\n"
+ "Notice how normally (when set to none), the value of io.WantCaptureKeyboard would be false when hovering and true when clicking.");
+ static int capture_override_mouse = -1;
+ static int capture_override_keyboard = -1;
+ const char* capture_override_desc[] = { "None", "Set to false", "Set to true" };
+ ImGui::SetNextItemWidth(ImGui::GetFontSize() * 15);
+ ImGui::SliderInt("SetNextFrameWantCaptureMouse()", &capture_override_mouse, -1, +1, capture_override_desc[capture_override_mouse + 1], ImGuiSliderFlags_AlwaysClamp);
+ ImGui::SetNextItemWidth(ImGui::GetFontSize() * 15);
+ ImGui::SliderInt("SetNextFrameWantCaptureKeyboard()", &capture_override_keyboard, -1, +1, capture_override_desc[capture_override_keyboard + 1], ImGuiSliderFlags_AlwaysClamp);
+
+ ImGui::ColorButton("##panel", ImVec4(0.7f, 0.1f, 0.7f, 1.0f), ImGuiColorEditFlags_NoTooltip | ImGuiColorEditFlags_NoDragDrop, ImVec2(256.0f, 192.0f)); // Dummy item
+ if (ImGui::IsItemHovered() && capture_override_mouse != -1)
+ ImGui::SetNextFrameWantCaptureMouse(capture_override_mouse == 1);
+ if (ImGui::IsItemHovered() && capture_override_keyboard != -1)
+ ImGui::SetNextFrameWantCaptureKeyboard(capture_override_keyboard == 1);
+
ImGui::TreePop();
}
diff --git a/imgui_internal.h b/imgui_internal.h
index ba1d9a0..6927754 100644
--- a/imgui_internal.h
+++ b/imgui_internal.h
@@ -1806,8 +1806,8 @@
int FramerateSecPerFrameIdx;
int FramerateSecPerFrameCount;
float FramerateSecPerFrameAccum;
- int WantCaptureMouseNextFrame; // Explicit capture via CaptureKeyboardFromApp()/CaptureMouseFromApp() sets those flags
- int WantCaptureKeyboardNextFrame;
+ int WantCaptureMouseNextFrame; // Explicit capture override via SetNextFrameWantCaptureMouse()/SetNextFrameWantCaptureKeyboard(). Default to -1.
+ int WantCaptureKeyboardNextFrame; // "
int WantTextInputNextFrame;
char TempBuffer[1024 * 3 + 1]; // Temporary text buffer
