@ -142,7 +142,7 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
- plot: option/feature: draw unit
- plot: add a helper e.g. Plot(char* label, float value, float time_span=2.0f) that stores values and Plot them for you - probably another function name. and/or automatically allow to plot ANY displayed value (more reliance on stable ID)
- clipper: ability to force display 1 item in the list would be convenient (for patterns where we need to set active id etc.)
- clipper: ability to force display 1 item in the list would be convenient (for patterns where we need to set active id etc.) (#3841) (can resurrect ForceDisplayRangeXXX functions removed)
- clipper: ability to disable the clipping through a simple flag/bool.
- clipper: ability to run without knowing full count in advance.
// Set cursor position and a few other things so that SetScrollHereY() and Columns() can work when seeking cursor.
// FIXME: It is problematic that we have to do that here, because custom/equivalent end-user code would stumble on the same issue.
// The clipper should probably have a 4th step to display the last item in a regular manner.
// The clipper should probably have a final step to display the last item in a regular manner, maybe with an opt-out flag for data sets which may have costly seek?
window->DC.CursorPosPrevLine.y=window->DC.CursorPos.y-line_height;// Setting those fields so that SetScrollHereY() can properly function after the end of our clipper usage.
window->DC.PrevLineSize.y=(line_height-g.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.
// 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.
// In theory here we should assert that we are already at the right position, but it seems saner to just seek at the end and not assert/crash the user.
// - Very important: when a starting position is after our maximum item, we set Min to (ItemsCount - 1). This allows us to handle most forms of wrapping.
// - Due to how Selectable extra padding they tend to be "unaligned" with exact unit in the item list,
// which with the flooring/ceiling tend to lead to 2 items instead of one being submitted.
IM_ASSERT(!scoring_rect.IsInverted());// Ensure if we have a finite, non-inverted bounding box here will allows us to remove extraneous ImFabs() calls in NavScoreItem().
// (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)
IMGUI_APIconstchar*GetStyleColorName(ImGuiColidx);// get a string corresponding to the enum value (for display, saving, etc.).
IMGUI_APIvoidSetStateStorage(ImGuiStorage*storage);// replace current window storage with our own (if you want to manipulate it yourself, typically clear subsection of it)
IMGUI_APIImGuiStorage*GetStateStorage();
IMGUI_APIvoidCalcListClipping(intitems_count,floatitems_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_APIboolBeginChildFrame(ImGuiIDid,constImVec2&size,ImGuiWindowFlagsflags=0);// helper to create a child window / scrolling region that looks like a normal widget frame
IMGUI_APIvoidEndChildFrame();// always call EndChildFrame() regardless of BeginChildFrame() return values (which indicates a collapsed/clipped window)
@ -2278,10 +2277,12 @@ struct ImGuiStorage
};
// Helper: Manually clip large list of items.
// If you are submitting lots of evenly spaced items and you have a random access to the list, you can perform coarse
// clipping based on visibility to save yourself from processing those items at all.
// If you have lots evenly spaced items and you have a random access to the list, you can perform coarse
// clipping based on visibility to only submit items that are in view.
// The clipper calculates the range of visible items and advance the cursor to compensate for the non-visible items we have skipped.
// (Dear ImGui already clip items based on their bounds but it needs to measure text size to do so, whereas manual coarse clipping before submission makes this cost and your own data fetching/submission cost almost null)
// (Dear ImGui already clip items based on their bounds but: it needs to first layout the item to do so, and generally
// fetching/submitting your own data incurs additional cost. Coarse clipping using ImGuiListClipper allows you to easily
// scale using lists with tens of thousands of items without a problem)
// Usage:
// ImGuiListClipper clipper;
// clipper.Begin(1000); // We have 1000 elements, evenly spaced.
@ -2290,28 +2291,25 @@ struct ImGuiStorage
// ImGui::Text("line number %d", i);
// Generally what happens is:
// - Clipper lets you process the first element (DisplayStart = 0, DisplayEnd = 1) regardless of it being visible or not.
// - User code submit one element.
// - User code submit that one element.
// - Clipper can measure the height of the first element
// - Clipper calculate the actual range of elements to display based on the current clipping rectangle, position the cursor before the first visible element.
// - User code submit visible elements.
// - The clipper also handles various subtleties related to keyboard/gamepad navigation, wrapping etc.
structImGuiListClipper
{
intDisplayStart;
intDisplayEnd;
// [Internal]
intItemsCount;
intStepNo;
intItemsFrozen;
floatItemsHeight;
floatStartPosY;
IMGUI_APIImGuiListClipper();
IMGUI_API~ImGuiListClipper();
intDisplayStart;// First item to display, updated by each call to Step()
intDisplayEnd;// End of items to display (exclusive)
intItemsCount;// [Internal] Number of items
floatItemsHeight;// [Internal] Height of item after a first step and item submission can calculate it
floatStartPosY;// [Internal] Cursor position at the time of Begin() or after table frozen rows are all processed
void*TempData;// [Internal] Internal data
// items_count: Use INT_MAX if you don't know how many items you have (in which case the cursor won't be advanced in the final step)
// items_height: Use -1.0f to be calculated automatically on first step. Otherwise pass in the distance between your items, typically GetTextLineHeightWithSpacing() or GetFrameHeightWithSpacing().
IMGUI_APIvoidBegin(intitems_count,floatitems_height=-1.0f);// Automatically called by constructor if you passed 'items_count' or by Step() in Step 1.
IMGUI_APIvoidEnd();// Automatically called on the last call of Step() that returns false.
IMGUI_APIboolStep();// Call until it returns false. The DisplayStart/DisplayEnd fields will be set and you can process/draw those items.
@ -3086,6 +3084,8 @@ struct ImGuiPlatformMonitor
#ifndef IMGUI_DISABLE_OBSOLETE_FUNCTIONS
namespaceImGui
{
// OBSOLETED in 1.86 (from November 2021)
IMGUI_APIvoidCalcListClipping(intitems_count,floatitems_height,int*out_items_display_start,int*out_items_display_end);// Calculate coarse clipping for large list of evenly sized items. Prefer using ImGuiListClipper.
ocornut
3 years ago