@ -23,7 +23,7 @@ or view this file with any Markdown viewer.
| [I integrated Dear ImGui in my engine and some elements are clipping or disappearing when I move windows around...](#q-i-integrated-dear-imgui-in-my-engine-and-some-elements-are-clipping-or-disappearing-when-i-move-windows-around) |
| [I integrated Dear ImGui in my engine and some elements are clipping or disappearing when I move windows around...](#q-i-integrated-dear-imgui-in-my-engine-and-some-elements-are-clipping-or-disappearing-when-i-move-windows-around) |
| [I integrated Dear ImGui in my engine and some elements are displaying outside their expected windows boundaries...](#q-i-integrated-dear-imgui-in-my-engine-and-some-elements-are-displaying-outside-their-expected-windows-boundaries) |
| [I integrated Dear ImGui in my engine and some elements are displaying outside their expected windows boundaries...](#q-i-integrated-dear-imgui-in-my-engine-and-some-elements-are-displaying-outside-their-expected-windows-boundaries) |
| **Q&A: Usage** |
| **Q&A: Usage** |
| **[Why is my widget not reacting when I click on it?<br>How can I have widgets with an empty label?<br>How can I have multiple widgets with the same label?](#q-why-is-my-widget-not-reacting-when-i-click-on-it)** |
| **[About the ID Stack system..<br>Why is my widget not reacting when I click on it?<br>How can I have widgets with an empty label?<br>How can I have multiple widgets with the same label?](#q-about-the-id-stack-system)** |
| [How can I display an image? What is ImTextureID, how does it work?](#q-how-can-i-display-an-image-what-is-imtextureid-how-does-it-work)|
| [How can I display an image? What is ImTextureID, how does it work?](#q-how-can-i-display-an-image-what-is-imtextureid-how-does-it-work)|
| [How can I use my own math types instead of ImVec2/ImVec4?](#q-how-can-i-use-my-own-math-types-instead-of-imvec2imvec4) |
| [How can I use my own math types instead of ImVec2/ImVec4?](#q-how-can-i-use-my-own-math-types-instead-of-imvec2imvec4) |
| [How can I interact with standard C++ types (such as std::string and std::vector)?](#q-how-can-i-interact-with-standard-c-types-such-as-stdstring-and-stdvector) |
| [How can I interact with standard C++ types (such as std::string and std::vector)?](#q-how-can-i-interact-with-standard-c-types-such-as-stdstring-and-stdvector) |
@ -186,17 +186,23 @@ Refer to rendering backends in the [examples/](https://github.com/ocornut/imgui/
# Q&A: Usage
# Q&A: Usage
### Q: About the ID Stack system...
### Q: Why is my widget not reacting when I click on it?
### Q: Why is my widget not reacting when I click on it?
### Q: How can I have widgets with an empty label?
### Q: How can I have widgets with an empty label?
### Q: How can I have multiple widgets with the same label?
### Q: How can I have multiple widgets with the same label?
A primer on labels and the ID Stack...
A primer on labels and the ID Stack...
Dear ImGui internally need to uniquely identify UI elements.
Dear ImGui internally needs to uniquely identify UI elements.
Elements that are typically not clickable (such as calls to the Text functions) don't need an ID.
Elements that are typically not clickable (such as calls to the Text functions) don't need an ID.
Interactive widgets (such as calls to Button buttons) need a unique ID.
Interactive widgets (such as calls to Button buttons) need a unique ID.
Unique ID are used internally to track active widgets and occasionally associate state to widgets.
Unique ID are implicitly built from the hash of multiple elements that identify the "path" to the UI element.
**Unique ID are used internally to track active widgets and occasionally associate state to widgets.<BR>
Unique ID are implicitly built from the hash of multiple elements that identify the "path" to the UI element.**
Since Dear ImGui 1.85 you can use `Demo>Tools>Stack Tool` or call `ImGui::ShowStackToolWindow()`. The tool display intermediate values leading to the creation of a unique ID, making things easier to debug and understand.
@ -354,6 +354,7 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
- nav: some features such as PageUp/Down/Home/End should probably work without ImGuiConfigFlags_NavEnableKeyboard? (where do we draw the line?)
- nav: some features such as PageUp/Down/Home/End should probably work without ImGuiConfigFlags_NavEnableKeyboard? (where do we draw the line?)
- nav: configuration flag to disable global shortcuts (currently only CTRL-Tab) ?
- nav: configuration flag to disable global shortcuts (currently only CTRL-Tab) ?
! nav: never clear NavId on some setup (e.g. gamepad centric)
! nav: never clear NavId on some setup (e.g. gamepad centric)
- nav: scroll up/down if possible when move request fails
- nav: there's currently no way to completely clear focus with the keyboard. depending on patterns used by the application to dispatch inputs, it may be desirable.
- nav: there's currently no way to completely clear focus with the keyboard. depending on patterns used by the application to dispatch inputs, it may be desirable.
- nav: code to focus child-window on restoring NavId appears to have issue: e.g. when focus change is implicit because of window closure.
- nav: code to focus child-window on restoring NavId appears to have issue: e.g. when focus change is implicit because of window closure.
- nav: Home/End behavior when navigable item is not fully visible at the edge of scrolling? should be backtrack to keep item into view?
- nav: Home/End behavior when navigable item is not fully visible at the edge of scrolling? should be backtrack to keep item into view?
@ -381,8 +382,6 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
- nav/windowing: when CTRL-Tab/windowing is active, the HoveredWindow detection doesn't take account of the window display re-ordering.
- nav/windowing: when CTRL-Tab/windowing is active, the HoveredWindow detection doesn't take account of the window display re-ordering.
- nav/windowing: Resizing window will currently fail with certain types of resizing constraints/callback applied
- nav/windowing: Resizing window will currently fail with certain types of resizing constraints/callback applied
- focus: preserve ActiveId/focus stack state, e.g. when opening a menu and close it, previously selected InputText() focus gets restored (#622)
- focus: preserve ActiveId/focus stack state, e.g. when opening a menu and close it, previously selected InputText() focus gets restored (#622)
- focus: SetKeyboardFocusHere() on with >= 0 offset could be done on same frame (else latch and modulate on beginning of next frame)
- focus: unable to use SetKeyboardFocusHere() on clipped widgets. (#787, #343)
- viewport: make it possible to have no main/hosting viewport
- viewport: make it possible to have no main/hosting viewport
- viewport: We set ImGuiViewportFlags_NoFocusOnAppearing in a way that is required for GLFW/SDL binding, but could be handled better without
- viewport: We set ImGuiViewportFlags_NoFocusOnAppearing in a way that is required for GLFW/SDL binding, but could be handled better without
// We may later decide to test for different NoXXXInputs based on the active navigation input (mouse vs nav) but that may feel more confusing to the user.
// We may later decide to test for different NoXXXInputs based on the active navigation input (mouse vs nav) but that may feel more confusing to the user.
NavMoveRequestSubmit(ImGuiDir_None,ImGuiDir_None,ImGuiNavMoveFlags_Tabbing,scroll_flags);// FIXME-NAV: Once we refactor tabbing, add LegacyApi flag to not activate non-inputable.
// (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)
// (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)
// You may use this file to debug, understand or extend ImGui features but we don't provide any guarantee of forward compatibility!
// You may use this file to debug, understand or extend ImGui features but we don't provide any guarantee of forward compatibility!
@ -756,7 +756,7 @@ enum ImGuiItemFlags_
ImGuiItemFlags_SelectableDontClosePopup=1<<5,// false // Disable MenuItem/Selectable() automatically closing their popup window
ImGuiItemFlags_SelectableDontClosePopup=1<<5,// false // Disable MenuItem/Selectable() automatically closing their popup window
ImGuiItemFlags_MixedValue=1<<6,// false // [BETA] Represent a mixed/indeterminate value, generally multi-selection where values differ. Currently only supported by Checkbox() (later should support all sorts of widgets)
ImGuiItemFlags_MixedValue=1<<6,// false // [BETA] Represent a mixed/indeterminate value, generally multi-selection where values differ. Currently only supported by Checkbox() (later should support all sorts of widgets)
ImGuiItemFlags_ReadOnly=1<<7,// false // [ALPHA] Allow hovering interactions but underlying value is not changed.
ImGuiItemFlags_ReadOnly=1<<7,// false // [ALPHA] Allow hovering interactions but underlying value is not changed.
ImGuiItemFlags_Inputable=1<<8// false // [WIP] Auto-activate item when focused. Currently only used and supported by a few items before it becomes a generic feature.
ImGuiItemFlags_Inputable=1<<8// false // [WIP] Auto-activate input mode when tab focused. Currently only used and supported by a few items before it becomes a generic feature.
};
};
// Storage for LastItem data
// Storage for LastItem data
@ -771,9 +771,7 @@ enum ImGuiItemStatusFlags_
ImGuiItemStatusFlags_HasDeactivated=1<<5,// Set if the widget/group is able to provide data for the ImGuiItemStatusFlags_Deactivated flag.
ImGuiItemStatusFlags_HasDeactivated=1<<5,// Set if the widget/group is able to provide data for the ImGuiItemStatusFlags_Deactivated flag.
ImGuiItemStatusFlags_Deactivated=1<<6,// Only valid if ImGuiItemStatusFlags_HasDeactivated is set.
ImGuiItemStatusFlags_Deactivated=1<<6,// Only valid if ImGuiItemStatusFlags_HasDeactivated is set.
ImGuiItemStatusFlags_HoveredWindow=1<<7,// Override the HoveredWindow test to allow cross-window hover testing.
ImGuiItemStatusFlags_HoveredWindow=1<<7,// Override the HoveredWindow test to allow cross-window hover testing.
ImGuiItemStatusFlags_FocusedByCode=1<<8,// Set when the Focusable item just got focused from code.
ImGuiItemStatusFlags_FocusedByTabbing=1<<8// Set when the Focusable item just got focused by Tabbing (FIXME: to be removed soon)
ImGuiItemStatusFlags_FocusedByTabbing=1<<9,// Set when the Focusable item just got focused by Tabbing.
ImGuiNavMoveFlags_AlsoScoreVisibleSet=1<<5,// Store alternate result in NavMoveResultLocalVisible that only comprise elements that are already fully visible (used by PageUp/PageDown)
ImGuiNavMoveFlags_AlsoScoreVisibleSet=1<<5,// Store alternate result in NavMoveResultLocalVisible that only comprise elements that are already fully visible (used by PageUp/PageDown)
ImGuiNavMoveFlags_ScrollToEdgeY=1<<6,// Force scrolling to min/max (used by Home/End) // FIXME-NAV: Aim to remove or reword, probably unnecessary
ImGuiNavMoveFlags_ScrollToEdgeY=1<<6,// Force scrolling to min/max (used by Home/End) // FIXME-NAV: Aim to remove or reword, probably unnecessary
ImGuiNavMoveFlags_Forwarded=1<<7,
ImGuiNavMoveFlags_Forwarded=1<<7,
ImGuiNavMoveFlags_DebugNoResult=1<<8
ImGuiNavMoveFlags_DebugNoResult=1<<8,// Dummy scoring for debug purpose, don't apply result
ImGuiNavMoveFlags_Tabbing=1<<9,// == Focus + Activate if item is Inputable + DontChangeNavHighlight
ImGuiNavMoveFlags_Activate=1<<10,
ImGuiNavMoveFlags_DontSetNavHighlight=1<<11// Do not alter the visible state of keyboard vs mouse nav highlight
};
};
enumImGuiNavLayer
enumImGuiNavLayer
@ -1255,12 +1256,13 @@ struct ImGuiNavItemData
ImGuiIDID;// Init,Move // Best candidate item ID
ImGuiIDID;// Init,Move // Best candidate item ID
ImGuiIDFocusScopeId;// Init,Move // Best candidate focus scope ID
ImGuiIDFocusScopeId;// Init,Move // Best candidate focus scope ID
ImRectRectRel;// Init,Move // Best candidate bounding box in window relative space
ImRectRectRel;// Init,Move // Best candidate bounding box in window relative space
ImGuiItemFlagsInFlags;// ????,Move // Best candidate item flags
floatDistBox;// Move // Best candidate box distance to current NavId
floatDistBox;// Move // Best candidate box distance to current NavId
floatDistCenter;// Move // Best candidate center distance to current NavId
floatDistCenter;// Move // Best candidate center distance to current NavId
floatDistAxial;// Move // Best candidate axial distance to current NavId
floatDistAxial;// Move // Best candidate axial distance to current NavId
ImGuiDirNavMoveClipDir;// FIXME-NAV: Describe the purpose of this better. Might want to rename?
ImGuiDirNavMoveClipDir;// FIXME-NAV: Describe the purpose of this better. Might want to rename?
ImRectNavScoringRect;// Rectangle used for scoring, in screen space. Based of window->NavRectRel[], modified for directional navigation scoring.
ImRectNavScoringRect;// Rectangle used for scoring, in screen space. Based of window->NavRectRel[], modified for directional navigation scoring.
intNavScoringDebugCount;// Metrics for debugging
intNavScoringDebugCount;// Metrics for debugging
intNavTabbingInputableRemaining;// >0 when counting items for tabbing
ImGuiNavItemDataNavMoveResultLocal;// Best move request candidate within NavWindow
ImGuiNavItemDataNavMoveResultLocal;// Best move request candidate within NavWindow
ImGuiNavItemDataNavMoveResultLocalVisible;// Best move request candidate within NavWindow that are mostly visible (when using ImGuiNavMoveFlags_AlsoScoreVisibleSet flag)
ImGuiNavItemDataNavMoveResultLocalVisible;// Best move request candidate within NavWindow that are mostly visible (when using ImGuiNavMoveFlags_AlsoScoreVisibleSet flag)
ImGuiNavItemDataNavMoveResultOther;// Best move request candidate within NavWindow's flattened hierarchy (when using ImGuiWindowFlags_NavFlattened flag)
ImGuiNavItemDataNavMoveResultOther;// Best move request candidate within NavWindow's flattened hierarchy (when using ImGuiWindowFlags_NavFlattened flag)
@ -1781,9 +1784,7 @@ struct ImGuiContext
// Legacy Focus/Tabbing system (older than Nav, active even if Nav is disabled, misnamed. FIXME-NAV: This needs a redesign!)
// Legacy Focus/Tabbing system (older than Nav, active even if Nav is disabled, misnamed. FIXME-NAV: This needs a redesign!)
ImGuiWindow*TabFocusRequestCurrWindow;//
ImGuiWindow*TabFocusRequestCurrWindow;//
ImGuiWindow*TabFocusRequestNextWindow;//
ImGuiWindow*TabFocusRequestNextWindow;//
intTabFocusRequestCurrCounterRegular;// Any item being requested for focus, stored as an index (we on layout to be stable between the frame pressing TAB and the next frame, semi-ouch)
intTabFocusRequestCurrCounterTabStop;// Tab item being requested for focus, stored as an index
intTabFocusRequestCurrCounterTabStop;// Tab item being requested for focus, stored as an index
intTabFocusRequestNextCounterRegular;// Stored for next frame
intTabFocusRequestNextCounterTabStop;// "
intTabFocusRequestNextCounterTabStop;// "
boolTabFocusPressed;// Set in NewFrame() when user pressed Tab
boolTabFocusPressed;// Set in NewFrame() when user pressed Tab
// Widget code are simplified as there's no need to call FocusableItemUnregister() while managing the transition from regular widget to TempInputText()
// Widget code are simplified as there's no need to call FocusableItemUnregister() while managing the transition from regular widget to TempInputText()
inlineboolFocusableItemRegister(ImGuiWindow*window,ImGuiIDid){IM_ASSERT(0);IM_UNUSED(window);IM_UNUSED(id);returnfalse;}// -> pass ImGuiItemAddFlags_Inputable flag to ItemAdd()
inlineboolFocusableItemRegister(ImGuiWindow*window,ImGuiIDid){IM_ASSERT(0);IM_UNUSED(window);IM_UNUSED(id);returnfalse;}// -> pass ImGuiItemAddFlags_Inputable flag to ItemAdd()
ocornut
3 years ago