RangeSelect/MultiSelect: (Breaking) Renamed 'RangeValue' -> 'RangeSelected' + amend comments.

imgui.h

@@ -2719,16 +2719,17 @@ enum ImGuiMultiSelectFlags_
 struct ImGuiMultiSelectIO
 {
     // - Always process requests in this order: Clear, SelectAll, SetRange.
-    // - Below: who reads/writes each fields? 'r'=read, 'w'=write, 'ms'=multi-select code, 'app'=application/user code.
-    //                          // BEGIN         / LOOP          / END
-    bool    RequestClear;       //  ms:w, app:r  /               /  ms:w, app:r  // 1. Request user to clear selection (processed by app code)
-    bool    RequestSelectAll;   //  ms:w, app:r  /               /  ms:w, app:r  // 2. Request user to select all (processed by app code)
-    bool    RequestSetRange;    //               /               /  ms:w, app:r  // 3. Request user to alter selection in the [RangeSrcItem..RangeDstItem] range using RangeValue. In practice, only EndMultiSelect() request this, app code can read after BeginMultiSelect() and it will always be false.
-    void*   RangeSrcItem;       //  ms:w         /        app:r  /  ms:w, app:r  // Begin: Last known SetNextItemSelectionData() value for RangeSrcItem value. End: parameter from RequestSetRange request.
+    // - Below: who reads/writes each fields? 'r'=read, 'w'=write, 'ms'=multi-select code, 'app'=application/user code, 'BEGIN'=BeginMultiSelect() and after, 'END'=EndMultiSelect() and after.
+    // REQUESTS ----------------// BEGIN         / LOOP          / END
+    bool    RequestClear;       //  ms:w, app:r  /               /  ms:w, app:r  // 1. Request app/user to clear selection.
+    bool    RequestSelectAll;   //  ms:w, app:r  /               /  ms:w, app:r  // 2. Request app/user to select all.
+    bool    RequestSetRange;    //               /               /  ms:w, app:r  // 3. Request app/user to select/unselect [RangeSrcItem..RangeDstItem] items, based on RangeSelected. In practice, only EndMultiSelect() request this, app code can read after BeginMultiSelect() and it will always be false.
+    // STATE/ARGUMENTS ---------// BEGIN         / LOOP          / END
+    void*   RangeSrcItem;       //  ms:w         /        app:r  /  ms:w, app:r  // Begin: Last known SetNextItemSelectionData() value for RangeSrcItem. End: parameter from RequestSetRange request.
     void*   RangeDstItem;       //               /               /  ms:w, app:r  // End: parameter from RequestSetRange request.
     ImS8    RangeDirection;     //               /               /  ms:w, app:r  // End: parameter from RequestSetRange request. +1 if RangeSrcItem came before RangeDstItem, -1 otherwise. Available as an indicator in case you cannot infer order from the void* values. If your void* values are storing indices you will never need this.
-    bool    RangeValue;         //               /               /  ms:w, app:r  // End: parameter from RequestSetRange request. true = Select Range, false = Unselect Range.
-    bool    RangeSrcPassedBy;   //               /  ms:rw app:w  /  ms:r         // (If using a clipper) Need to be set by user if RangeSrcItem was part of the clipped set before submitting the visible items. Ignore if not clipping.
+    bool    RangeSelected;      //               /               /  ms:w, app:r  // End: parameter from RequestSetRange request. true = Select Range, false = Unselect Range.
+    bool    RangeSrcPassedBy;   //               /  ms:rw app:w  /  ms:r         // (If using clipper) Need to be set by app/user if RangeSrcItem was part of the clipped set before submitting the visible items. Ignore if not clipping.
 
     ImGuiMultiSelectIO()    { Clear(); }
     void Clear()            { memset(this, 0, sizeof(*this)); }

imgui_demo.cpp

@@ -594,6 +594,7 @@ void ImGui::ShowDemoWindow(bool* p_open)
     ImGui::End();
 }
 
+
 static void ShowDemoWindowWidgets()
 {
     IMGUI_DEMO_MARKER("Widgets");
@@ -2784,7 +2785,7 @@ struct ExampleSelection
     {
         if (ms_io->RequestClear)        { Clear(); }
         if (ms_io->RequestSelectAll)    { SelectAll(items_count); }
-        if (ms_io->RequestSetRange)     { SetRange((int)(intptr_t)ms_io->RangeSrcItem, (int)(intptr_t)ms_io->RangeDstItem, ms_io->RangeValue ? 1 : 0); }
+        if (ms_io->RequestSetRange)     { SetRange((int)(intptr_t)ms_io->RangeSrcItem, (int)(intptr_t)ms_io->RangeDstItem, ms_io->RangeSelected ? 1 : 0); }
     }
 };
 

imgui_widgets.cpp

@@ -7011,7 +7011,7 @@ static void DebugLogMultiSelectRequests(const char* function, const ImGuiMultiSe
     ImGuiContext& g = *GImGui;
     if (data->RequestClear)     IMGUI_DEBUG_LOG_SELECTION("[selection] %s: RequestClear\n", function);
     if (data->RequestSelectAll) IMGUI_DEBUG_LOG_SELECTION("[selection] %s: RequestSelectAll\n", function);
-    if (data->RequestSetRange)  IMGUI_DEBUG_LOG_SELECTION("[selection] %s: RequestSetRange %p..%p = %d (dir %+d)\n", function, data->RangeSrcItem, data->RangeDstItem, data->RangeValue, data->RangeDirection);
+    if (data->RequestSetRange)  IMGUI_DEBUG_LOG_SELECTION("[selection] %s: RequestSetRange %p..%p = %d (dir %+d)\n", function, data->RangeSrcItem, data->RangeDstItem, data->RangeSelected, data->RangeDirection);
 }
 
 ImGuiMultiSelectIO* ImGui::BeginMultiSelect(ImGuiMultiSelectFlags flags, void* range_ref, bool range_ref_is_selected)
@@ -7036,7 +7036,7 @@ ImGuiMultiSelectIO* ImGui::BeginMultiSelect(ImGuiMultiSelectFlags flags, void* r
     if ((flags & ImGuiMultiSelectFlags_NoMultiSelect) == 0)
     {
         ms->BeginIO.RangeSrcItem = ms->EndIO.RangeSrcItem = range_ref;
-        ms->BeginIO.RangeValue = ms->EndIO.RangeValue = range_ref_is_selected;
+        ms->BeginIO.RangeSelected = ms->EndIO.RangeSelected = range_ref_is_selected;
     }
 
     // Auto clear when using Navigation to move within the selection (we compare SelectScopeId so it possible to use multiple lists inside a same window)
@@ -7085,7 +7085,7 @@ ImGuiMultiSelectIO* ImGui::EndMultiSelect()
 
     // Unwind
     if (ms->Flags & ImGuiMultiSelectFlags_NoUnselect)
-        ms->EndIO.RangeValue = true;
+        ms->EndIO.RangeSelected = true;
     ms->FocusScopeId = 0;
     ms->Window = NULL;
     ms->Flags = ImGuiMultiSelectFlags_None;
@@ -7147,7 +7147,7 @@ void ImGui::MultiSelectItemHeader(ImGuiID id, bool* p_selected)
         if (is_range_dst)
             ms->RangeDstPassedBy = true;
         if (is_range_src || is_range_dst || ms->BeginIO.RangeSrcPassedBy != ms->RangeDstPassedBy)
-            selected = ms->BeginIO.RangeValue;
+            selected = ms->BeginIO.RangeSelected;
         else if ((ms->KeyMods & ImGuiMod_Ctrl) == 0)
             selected = false;
     }
@@ -7217,7 +7217,7 @@ void ImGui::MultiSelectItemFooter(ImGuiID id, bool* p_selected, bool* p_pressed)
             ms->EndIO.RequestSetRange = true;
             ms->EndIO.RangeDstItem = item_data;
             if (!is_ctrl)
-                ms->EndIO.RangeValue = true;
+                ms->EndIO.RangeSelected = true;
             ms->EndIO.RangeDirection = ms->BeginIO.RangeSrcPassedBy ? +1 : -1;
         }
         else
@@ -7225,7 +7225,7 @@ void ImGui::MultiSelectItemFooter(ImGuiID id, bool* p_selected, bool* p_pressed)
             // Ctrl inverts selection, otherwise always select
             selected = (is_ctrl && (ms->Flags & ImGuiMultiSelectFlags_NoUnselect) == 0) ? !selected : true;
             ms->EndIO.RangeSrcItem = ms->EndIO.RangeDstItem = item_data;
-            ms->EndIO.RangeValue = selected;
+            ms->EndIO.RangeSelected = selected;
         }
 
         if (input_source == ImGuiInputSource_Mouse || g.NavActivateId == id)
@@ -7238,7 +7238,7 @@ void ImGui::MultiSelectItemFooter(ImGuiID id, bool* p_selected, bool* p_pressed)
                 // For toggle selection unless there is a Clear request, we can handle it completely locally without sending a RangeSet request.
                 IM_ASSERT(ms->EndIO.RangeSrcItem == ms->EndIO.RangeDstItem); // Setup by else block above
                 ms->EndIO.RequestSetRange = true;
-                ms->EndIO.RangeValue = selected;
+                ms->EndIO.RangeSelected = selected;
                 ms->EndIO.RangeDirection = +1;
             }
             if (!is_multiselect)
@@ -7260,7 +7260,7 @@ void ImGui::MultiSelectItemFooter(ImGuiID id, bool* p_selected, bool* p_pressed)
 
     // Update/store the selection state of the Source item (used by CTRL+SHIFT, when Source is unselected we perform a range unselect)
     if (ms->EndIO.RangeSrcItem == item_data && is_ctrl && is_shift && is_multiselect && !(ms->Flags & ImGuiMultiSelectFlags_NoUnselect))
-        ms->EndIO.RangeValue = selected;
+        ms->EndIO.RangeSelected = selected;
 
     *p_selected = selected;
     *p_pressed = pressed;