98  - Efficient runtime and memory consumption (NB- we do allocate when "growing" content e.g. creating a window,.
149  - C++: this is a very C-ish codebase: we don't rely on C++11, we don't include any C++ headers, and ImGui:: is a namespace.
152    However, imgui_internal.h can optionally export math operators for ImVec2/ImVec4, which we use in this codebase.
159  - Read the "API BREAKING CHANGES" section (below). This is where we list occasional API breaking changes.
188      // Initialize helper Platform and Renderer bindings (here we are using imgui_impl_win32 and imgui_impl_dx11)
231      // After we have created the texture, store its pointer/identifier (_in whichever format your engine uses_) in 'io.Fonts->TexID'.
372  - 2018/12/10 (1.67) - renamed io.ConfigResizeWindowsFromEdges to io.ConfigWindowsResizeFromEdges as we are doing a large pass on configuration flags.
393  - 2018/05/03 (1.61) - DragInt(): the default compile-time format string has been changed from "%.0f" to "%d", as we are not using integers internally any more.
436                        removed the IsItemRectHovered()/IsWindowRectHovered() names introduced in 1.51 since they were merely more consistent names for the two functions we are now obsoleting.
441  - 2017/08/25 (1.52) - io.MousePos needs to be set to ImVec2(-FLT_MAX,-FLT_MAX) when mouse is unavailable/missing. Previously ImVec2(-1,-1) was enough but we now accept negative mouse coordinates. In your binding if you need to support unavailable mouse, make sure to replace "io.MousePos = ImVec2(-1,-1)" with "io.MousePos = ImVec2(-FLT_MAX,-FLT_MAX)".
464                        If your TitleBg/TitleBgActive alpha was <1.0f you need to tweak your custom theme to readjust for the fact that we don't draw a WindowBg background behind the title bar.
483  - 2015/08/29 (1.45) - with the addition of horizontal scrollbar we made various fixes to inconsistencies with dealing with cursor position.
534               (1.30) - added texture identifier in ImDrawCmd passed to your render function (we can now render images). make sure to set io.Fonts->TexID.
578       to render them is generally fairly short (a few dozen lines). In the examples/ folder we provide functions for popular graphics API (OpenGL, DirectX, etc.).
583     - In the examples/ bindings, for each graphics API binding we decided on a type that is likely to be a good representation for specifying
591       For example, in the OpenGL example binding we store raw OpenGL texture identifier (GLuint) inside ImTextureID.
592       Whereas in the DirectX11 example binding we store a pointer to ID3D11ShaderResourceView inside ImTextureID, which is a higher-level structure
635         // Now that we have an OpenGL texture, assuming our imgui rendering function (imgui_impl_xxx.cpp file) takes GLuint as ImTextureID, we can display it:
644         my_void_ptr = (void*)(intptr_t)my_tex;                  // cast a GLuint into a void* (we don't take its address! we literally store the value inside the pointer)
719      At each level of the stack we store the seed used for items at this level of the ID stack.
981 // When using CTRL+TAB (or Gamepad Square+L/R) we delay the visual a little in order to reduce visual noise doing a fast switch.
1096     TouchExtraPadding       = ImVec2(0,0);      // Expand reactive bounding box for touch-based system where touch position is not accurate enough. Unfortunately we don't sort widgets so priority on overlap will always be given to the first widget. So don't grow this too much!
1119 // Important: This operation is lossy because we round all sizes to integer. If you need to change your scale multiples, call this over a freshly initialized ImGuiStyle structure rather than scaling multiple times.
1195     // Input (NB: we already have memset zero the entire structure!)
1386     if (p_start != buf)                     // Copy memory if we had leading blanks
1392 // Ideally we would test for only one of those limits at runtime depending on the behavior the vsnprintf(), but trying to deduct it at compile time sounds like a pandora can of worm.
1478 // Because this syntax is rarely used we are optimizing for the common case.
1479 // - If we reach ### in the string we discard the hash so far and reset to the seed.
1513     // We need a fopen() wrapper because MSVC/Windows fopen doesn't handle UTF-8 filenames. Converting both strings from UTF-8 to wchar format (using a single allocation, because we can)
1705 // Not optimal but we very rarely use this function.
2043     const char* we = wb;
2044     while (we < e)
2046         if (*we == separator)
2048             out->push_back(TextRange(wb, we));
2049             wb = we + 1;
2051         we++;
2053     if (wb != we)
2054         out->push_back(TextRange(wb, we));
2189     // FIXME: It is problematic that we have to do that here, because custom/equivalent end-user code would stumble on the same issue.
2194     window->DC.PrevLineSize.y = (line_height - GImGui->Style.ItemSpacing.y);    // If we end up needing more accurate data (to e.g. use SameLine) we may as well make the clipper have a fourth step to let user process and display the last item in their list.
2201 // FIXME-LEGACY: Ideally we should remove the Begin/End functions but they are part of the legacy API we still support. This is why some of the code in Step() calling Begin() and reassign some fields, spaghetti style.
2222     // In theory here we should assert that ImGui::GetCursorPosY() == StartPosY + DisplayEnd * ItemsHeight, but it feels saner to just seek at the end and not assert/crash the user.
2236     if (StepNo == 0) // Step 0: the clipper let you process the first element, regardless of it being visible or not, so we can measure the element height.
2261     if (StepNo == 3) // Step 3: the clipper validate that we have reached the expected Y position (corresponding to element DisplayEnd), advance the cursor to the end of the list and then returns 'false' to end the loop.
2338     if (clip_rect) // If we had no explicit clipping rectangle then pos==clip_min
2341     // Align whole block. We should defer that to the better rendering function when we'll have support for individual line alignment.
2664     // Assume that SetFocusID() is called in the context where its NavLayer is the current layer, which is the case everywhere we call it.
2713     // ActiveId might have been released by the time we call this (as in the typical press/release button behavior) but still need need to fill the data.
2731                 // For the purpose of those flags we differentiate "standard popup" from "modal popup"
2787         //  (b) So that we can scroll up/down past clipped items. This adds a small O(N) cost to regular navigation requests unfortunately, but it is still limited to one window.
2789         //      We could early out with "if (is_clipped && !g.NavInitRequest) return false;" but when we wouldn't be able to reach unclipped widgets. This would work if user had explicit scrolling control (e.g. mapped on a stick)
2819 // - we allow hovering to be true when ActiveId==window->MoveID, so that clicking on non-interactive items such as a Text() item still returns true with IsItemHovered()
2820 // - this should work even for non-interactive items that have no ID, so we cannot use LastItemId
2833     // Test if we are hovering the right window (our window could be behind another window)
2855     // When the window is collapsed (SkipItems==true) that last item will never be overwritten so we need to detect the case.
2905     // Note that we can always TAB out of a widget that doesn't allow tabbing in.
2907         window->FocusIdxTabRequestNext = window->FocusIdxTabCounter + (g.IO.KeyShift ? (is_tab_stop ? -1 : 0) : +1); // Modulo on index will be applied at the end of frame once we've got the total counter of items.
2985 // Note that we still point to some static data and members (such as GFontAtlas), so the state instance you end up using will point to the static data within its module
3089     // This is because we want ActiveId to be set even when the window is not permitted to move.
3110         // We actually want to move the root window. g.MovingWindow == window we clicked on (could be a child window).
3133         // When clicking/dragging from a window that has the _NoMove flag, we still set the ActiveId in order to prevent hovering others.
3151     // Unless we just made a window/popup appear
3155     // Click to focus window and start moving (after we're done with all our widgets)
3172     // With right mouse button we close popups without changing focus
3177         // This is where we can trim the popup stack.
3207     // If mouse just appeared or disappeared (usually denoted by -FLT_MAX components) we cancel out movement in MouseDelta
3242             // Maintain the maximum distance we reaching from the initial click position, which is used with dragging threshold
3261     // If a child window has the ImGuiWindowFlags_NoScrollWithMouse flag, we give a chance to scroll its parent (unless either ImGuiWindowFlags_NoInputs or ImGuiWindowFlags_NoScrollbar are also set).
3298 // The reason this is exposed in imgui_internal.h is: on touch-based system that don't have hovering, we want to dispatch inputs to the right target (imgui vs imgui+app)
3304     // - Child windows can extend beyond the limit of their parent so we need to derive HoveredRootWindow from HoveredWindow.
3305     // - When moving a window we can skip the search, which also conveniently bypasses the fact that window->WindowRectClipped is lagging as this point of the frame.
3333     // If mouse was first clicked outside of ImGui bounds we also cancel out hovering.
3334     // FIXME: For patterns of drag and drop across OS windows, we may need to rework/remove this test (first committed 311c0ca9 on 2015/02)
3379     // Perform simple check: required key mapping (we intentionally do NOT check all keys to not pressure user into setting up everything, but Space is required and was only recently added in 1.60 WIP)
3396     // Save settings (with a delay after the last modification, so we don't spam disk too much)
3526     // But in order to allow the user to call NewFrame() multiple times without calling Render(), we are doing an explicit clear.
3531     // Create implicit/fallback window - which we will only render it if the user has added something to it.
3563     // The fonts atlas can be used prior to calling NewFrame(), so we clear it even if g.Initialized is FALSE (which would happen if we never called NewFrame)
3576     // Save settings (unless we haven't attempted to load them: CreateContext/DestroyContext without a call to NewFrame shouldn't save an empty file)
3837     // This usually assert if there is a mismatch between the ImGuiWindowFlags_ChildWindow / ParentWindow values and DC.ChildWindows[] in parents, aka we've done something wrong.
3949     // When performing a navigation request, ensure we have one item extra in the direction we are moving to
3962 // FIXME: Note that we have an inconsequential lag here: OuterRectClipped is updated in Begin(), so windows moved programatically
4174             return g.IO.MousePos - g.IO.MouseClickedPos[button];     // Assume we can only get active with left-mouse button (at the moment).
4411             // When browsing a window that has no activable items (scroll only) we keep a highlight on the child
4452     // For color, style and font stacks there is an incentive to use Push/Begin/Pop/.../End patterns, so we relax our checks a little to allow them.
4586         if (is_popup || is_menu) // Popups and menus bypass style.WindowMinSize by default, but we give then a non-zero minimum size to facilitate understanding problematic cases (e.g. empty popups)
4591         // we are growing the size on the other axis to compensate for expected scrollbar. FIXME: Might turn bigger than ViewportSize-WindowPadding.
4721         // Using the FlattenChilds button flag we make the resize button accessible even if we are hovering over a child window
4879         ImVec2 size_on_first_use = (g.NextWindowData.SizeCond != 0) ? g.NextWindowData.SizeVal : ImVec2(0.0f, 0.0f); // Any condition flag will do since we are creating a new window here.
4941             // May be processed on the next frame if this is our first frame and we are measuring size
4992         // The title bar always display the 'name' parameter, so we only update the string storage if it needs to be visible to the end-user elsewhere.
5016         // Hide popup/tooltip window when re-opening while we measure size (because we recycle the windows)
5042         // At this point we don't have a clipping rectangle setup yet, so we can use the title bar area for hit detection and drawing
5045             // We don't use a regular button+id to test for double-click on title bar (mostly due to legacy reason, could be fixed), so verify that we don't have items over the title bar.
5096             // When reading the current size we need to read it after size constraints have been applied
5219         // As we highlight the title bar when want_focus is set, multiple reappearing windows will have have their title bar highlighted on their reappearing frame.
5272             // Render resize grips (after their input handling so we don't have a frame of latency)
5304         // Store a backup of SizeFull which we will use next frame to decide if we need scrollbars.
5358         // Apply focus (we need to call FocusWindow() AFTER setting DC.CursorStartPos so our initial navigation reference rectangle can start around there)
5377                     window->WantCollapseToggle = true; // Defer collapsing to next frame as we are too far in the Begin() function
5415         // Save clipped aabb so we can access it in constant-time in FindHoveredWindow()
5420         // This works but 1. doesn't handle multiple Begin/End pairs, 2. recursing into another Begin/End pair - so we need to work that out and add better logging scope.
5421         // Maybe we can support CTRL+C on every element?
5430         // Note that if our window is collapsed we will end up with an inverted (~null) clipping rectangle which is the correct behavior.
5463         // Mark them as collapsed so commands are skipped earlier (we can't manually collapse them because they have no title bar).
5481     // Return false if we don't intend to display anything to allow user to perform an early out optimization
5491     // Old API feature: we could pass the initial window size as a parameter. This was misleading because it only had an effect if the window didn't have data in the .ini file.
5662         // Align to a right-side limit. We include 1 frame padding in the calculation because this is how the width is always used (we add 2 frame padding to it), but we could move that responsibility to the widget as well.
5720 // FIXME: Look into renaming this once we have settled the new Focus/Activation/TabStop system.
5755 // FIXME: This may incur a round-trip (if the end user got their data from a float4) but eventually we aim to store the in-flight colors as ImU32
6007 // Can we focus this window with CTRL+TAB (or PadMenu + PadFocusPrev/PadFocusNext)
6036     window->DC.CursorMaxPos.x += window->Scroll.x; // SizeContents is generally computed based on CursorMaxPos which is affected by scroll position, so we need to apply our change to it.
6043     window->DC.CursorMaxPos.y += window->Scroll.y; // SizeContents is generally computed based on CursorMaxPos which is affected by scroll position, so we need to apply our change to it.
6061     window->DC.CursorPos += (window->Pos - old_pos);    // As we happen to move the window while it is being appended to (which is a bad idea - will smear) let's at least offset the cursor
6062     window->DC.CursorMaxPos += (window->Pos - old_pos); // And more importantly we need to adjust this so size calculation doesn't get affected.
6207     g.NextWindowData.ContentSizeVal = size;  // In Begin() we will add the size of window decorations (title bar, menu etc.) to that to form a SizeContents value.
6325 // User generally sees positions in window coordinates. Internally we store CursorPos in absolute screen coordinates because it is more convenient.
6326 // Conversion happens as we pass the value to user, but it makes our naming convention confusing because GetCursorPos() == (DC.CursorPos - window.Pos). May want to rename 'DC.CursorPos'.
6421     // We store a target position so centering can occur on the next frame when we are guaranteed to have a known window size
6588         window->DC.CurrentLineTextBaseOffset = ImMax(window->DC.PrevLineTextBaseOffset, group_data.BackupCurrentLineTextBaseOffset);      // FIXME: Incorrect, we should grab the base offset from the *first line* of the group but it is hard to obtain now.
6593     // If the current ActiveId was declared within the boundary of our group, we copy it to LastItemId so IsItemActive(), IsItemDeactivated() etc. will be functional on the entire group.
6594     // It would be be neater if we replaced window.DC.LastItemId by e.g. 'bool LastItemIsActive', but would put a little more burden on individual widgets.
6661         // In the context of a dragging tooltip we try to reduce that offset and we enforce following the cursor.
6662         // Whatever we do we want to call SetNextWindowPos() to enforce a tooltip position and disable clipping the tooltip without our display area, like regular tooltip do.
6686                 // Hide previous tooltip from being displayed. We can't easily "reset" the content of a window so we create a new one.
6755 // One open popup per level of the popup hierarchy (NB: when assigning we reset the Window member of ImGuiPopupRef to NULL)
6761     ImGuiPopupRef popup_ref; // Tagged as new ref as Window will be set back to NULL if we write this into OpenPopupStack.
6777         // Gently handle the user mistakenly calling OpenPopup() every frame. It is a programming mistake! However, if we were to run the regular code path, the ui
6779         // situation for the programmer. Instead, we silently allow the popup to proceed, it will keep reappearing and the programming error will be more obvious to understand.
6791         // When reopening a popup we first refocus its parent, otherwise if its parent is itself a popup it would get closed by ClosePopupsOverWindow().
6803         ImGuiID id = str_id ? window->GetID(str_id) : window->DC.LastItemId; // If user hasn't passed an ID, we can use the LastItemID. Using LastItemID as a Popup ID won't conflict!
6855     // FIXME: This code is faulty and we may want to eventually to replace or remove the 'apply_focus_to_window_under=true' path completely.
6856     // Instead of using g.OpenPopupStack[remaining-1].Window etc. we should find the highest root window that is behind the popups we are closing.
6860     // However if the clicked window has the _NoMove flag set we would be left with B focused.
6861     // For now, we have disabled this path when called from ClosePopupsOverWindow() because the users of ClosePopupsOverWindow() don't need to alter focus anyway,
6862     // but we should inspect and fix this properly.
6871 // Close the popup we have begin-ed into.
6896     // To improve this usage pattern, we avoid nav highlight for a single frame in the parent window.
6897     // Similarly, we could avoid mouse hover highlight in this window but it is less visually problematic.
6915         ImFormatString(name, IM_ARRAYSIZE(name), "##Popup_%08x", id); // Not recycling, so we can close/open during the same frame
6984     ImGuiID id = str_id ? window->GetID(str_id) : window->DC.LastItemId; // If user hasn't passed an ID, we can use the LastItemID. Using LastItemID as a Popup ID won't conflict!
7020 // r_avoid = the rectangle to avoid (e.g. for tooltip it is a rectangle around the mouse cursor which we want to avoid. for popups it's a small point around the cursor.)
7021 // r_outer = the visible area rectangle, minus safe area padding. If our popup size won't fit because of safe area padding we ignore it.
7028     // Combo Box policy (we want a connecting edge)
7082         // Child menus typically request _any_ position within the parent menu item, and then we move the new menu outside the parent bounds.
7083         // This is how we end up with child menus appearing (most-commonly) on the right of the parent menu.
7111             pos = ref_pos + ImVec2(2, 2); // If there's not enough room, for tooltip we prefer avoiding the cursor at all cost even if it means that part of the tooltip won't be visible.
7166     const ImRect& curr = g.NavScoringRectScreen; // Current modified source rect (NB: we've applied Max.x = Min.x in NavUpdate() to inhibit the effect of having varied item width)
7169     // When entering through a NavFlattened border, we consider child window items as fully clipped for scoring
7190     // Compute distance between centers (this is off by a factor of 2, but we only compare center distances with each other so it doesn't matter)
7244     // Is it in the quadrant we're interesting in moving to?
7265                 // Still tied! we need to be extra-careful to make sure everything gets linked properly. We consistently break ties by symbolically moving "later" items
7266                 // (with higher index) to the right/downwards by an infinitesimal amount since we the current "best" button already (so it must have a lower index),
7277     // 2017/09/29: FIXME: This now currently only enabled inside menu bars, ideally we'd disable it everywhere. Menus in particular need to catch failure. For general navigation it feels awkward.
7303         // Even if 'ImGuiItemFlags_NoNavDefaultFocus' is on (typically collapse/close button) we record the first ResultId so they can be used as a fallback
7430 // Call when we are expected to land on Layer 0 after FocusWindow()
7456 // This needs to be called before we submit any widget (aka in or before Begin)
7485         // Mouse (we need a fallback in case the mouse becomes invalid after being used)
7539 // NB: We modify rect_rel by the amount we scrolled for, so it is immediately updated.
7578     // Set input source as Gamepad when buttons are pressed before we map Keyboard (some features differs when used with Gamepad vs Keyboard)
7625     // When a forwarded move request failed, we restore the highlight that we disabled during the forward frame
7634     // Apply application mouse position movement, after we had a chance to process move request result.
7652     // Store our return window (for returning from Layer 1 to Layer 0) and clear it as soon as we step back in our own Layer 0
7698             // Clear NavLastId for popups but keep it for regular child window so we can leave one and come back where we were
7760     // If we initiate a movement request and have no current NavId, we initiate a InitDefautRequest that will be used as a fallback if the direction fails to find a match
7808     // When we have manually scrolled (without using navigation) and NavId becomes out of bounds, we project its bounding box to the visible area to restart navigation within visible items
7823     // For scoring we use a single segment on the left side our current item bounding box (not touching the edge to avoid box overlap with zero-spaced items)
7829     IM_ASSERT(!g.NavScoringRectScreen.IsInverted()); // Ensure if we have a finite, non-inverted bounding box here will allows us to remove extraneous ImFabs() calls in NavScoreItem().
7873         // Estimate upcoming scroll so we can offset our result position so mouse position can be applied immediately after in NavUpdate()
7878         // Also scroll parent window to keep us into view if necessary (we could/should technically recurse back the whole the parent hierarchy).
7921                     g.NavMoveDir = ImGuiDir_Down; // Because our scoring rect is offset, we intentionally request the opposite direction (so we can always land on the last item)
7928                     g.NavMoveDir = ImGuiDir_Up; // Because our scoring rect is offset, we intentionally request the opposite direction (so we can always land on the last item)
8025             g.NavWindowingToggleLayer &= (g.NavWindowingHighlightAlpha < 1.0f); // Once button was held long enough we don't consider it a tap-to-toggle-layer press anymore.
8212     // Active (dragged) column always follow mouse. The reason we need this is that dragging a column to the right edge of an auto-resizing
8213     // window creates a feedback loop because we store normalized positions. So while dragging we enforce absolute positioning.
8330     // In addition, when an identifier isn't explicitly provided we include the number of columns in the hash to make it uniquer.
8428             // Draw column (we clip the Y boundaries CPU side because very long triangles are mishandled by some GPU drivers.)
8452 // [2018-03: This is currently the only public API, while we are working on making BeginColumns/EndColumns user-facing]
8532             if (g.ActiveId == source_id) // Allow the underlying widget to display/return hovered during the mouse release frame, else we would get a flicker.
8569             // Target can request the Source to not display its tooltip (we use a dedicated flag to make this request explicit)
8670 // 1) we use LastItemRectHoveredRect which handles items that pushes a temporarily clip rectangle in their code. Calling BeginDragDropTargetCustom(LastItemRect) would not handle them.
8671 // 2) and it's faster. as this code may be very frequently called, we want to early out as fast as we can.
8672 // Also note how the HoveredWindow test is positioned differently in both functions (in both functions we optimize for the cheapest early out case)
8754 // We don't really use/need this now, but added it for the sake of consistency and because we might need it later.
8807     if (g.LogStartDepth > window->DC.TreeDepth)  // Re-adjust padding if we have popped out of our starting depth
9012     // For user convenience, we allow passing a non zero-terminated string (hence the ini_size parameter).
9013     // For our convenience and to make the code simpler, we'll also write zero-terminators within the buffer. So let's create a writable copy..
9121     // (if a window wasn't opened in this session we preserve its settings)
9307                 ImGui::TextColored(ImVec4(1.0f,0.4f,0.4f,1.0f), "CURRENTLY APPENDING"); // Can't display stats for active draw list! (we don't have the data double-buffered)
9446     // Access private state, we are going to display the draw lists from last frame
9475         ImGui::Text("HoveredId: 0x%08X/0x%08X (%.2f sec), AllowOverlap: %d", g.HoveredId, g.HoveredIdPreviousFrame, g.HoveredIdTimer, g.HoveredIdAllowOverlap); // Data is "in-flight" so depending on when the Metrics window is called we may see current frame information or not

Indexes created Sun Nov 30 00:09:37 GMT 2025