Cleanup: Improve API and documentation of interface_view.cc

File documentation was outdated and could use general improvement.
Function names didn't really reflect the level they are operating on.

5 files changed, 21 insertions, 15 deletions

diff --git a/source/blender/editors/include/UI_interface.h b/source/blender/editors/include/UI_interface.h
index 99a1d038cca..a8d25b75036 100644
--- a/source/blender/editors/include/UI_interface.h
+++ b/source/blender/editors/include/UI_interface.h
@@ -3230,9 +3230,9 @@ bool UI_view_item_drop_handle(struct bContext *C,
 /**
  * \param xy: Coordinate to find a view item at, in window space.
  */
-uiViewItemHandle *UI_block_view_find_item_at(const struct ARegion *region, const int xy[2])
+uiViewItemHandle *UI_region_views_find_item_at(const struct ARegion *region, const int xy[2])
     ATTR_NONNULL();
-uiViewItemHandle *UI_block_view_find_active_item(const struct ARegion *region);
+uiViewItemHandle *UI_region_views_find_active_item(const struct ARegion *region);
 
 #ifdef __cplusplus
 }
diff --git a/source/blender/editors/interface/interface_dropboxes.cc b/source/blender/editors/interface/interface_dropboxes.cc
index df488fb9127..b72d8d2c238 100644
--- a/source/blender/editors/interface/interface_dropboxes.cc
+++ b/source/blender/editors/interface/interface_dropboxes.cc
@@ -28,7 +28,7 @@
 static bool ui_view_drop_poll(bContext *C, wmDrag *drag, const wmEvent *event)
 {
   const ARegion *region = CTX_wm_region(C);
-  const uiViewItemHandle *hovered_item = UI_block_view_find_item_at(region, event->xy);
+  const uiViewItemHandle *hovered_item = UI_region_views_find_item_at(region, event->xy);
   if (!hovered_item) {
     return false;
   }
@@ -47,7 +47,7 @@ static char *ui_view_drop_tooltip(bContext *C,
                                   wmDropBox *UNUSED(drop))
 {
   const ARegion *region = CTX_wm_region(C);
-  const uiViewItemHandle *hovered_item = UI_block_view_find_item_at(region, xy);
+  const uiViewItemHandle *hovered_item = UI_region_views_find_item_at(region, xy);
   if (!hovered_item) {
     return nullptr;
   }
diff --git a/source/blender/editors/interface/interface_ops.c b/source/blender/editors/interface/interface_ops.c
index 7a51ed23677..ddd805f6010 100644
--- a/source/blender/editors/interface/interface_ops.c
+++ b/source/blender/editors/interface/interface_ops.c
@@ -2058,7 +2058,7 @@ static bool ui_view_drop_poll(bContext *C)
 {
   const wmWindow *win = CTX_wm_window(C);
   const ARegion *region = CTX_wm_region(C);
-  const uiViewItemHandle *hovered_item = UI_block_view_find_item_at(region, win->eventstate->xy);
+  const uiViewItemHandle *hovered_item = UI_region_views_find_item_at(region, win->eventstate->xy);
 
   return hovered_item != NULL;
 }
@@ -2070,7 +2070,7 @@ static int ui_view_drop_invoke(bContext *C, wmOperator *UNUSED(op), const wmEven
   }
 
   const ARegion *region = CTX_wm_region(C);
-  uiViewItemHandle *hovered_item = UI_block_view_find_item_at(region, event->xy);
+  uiViewItemHandle *hovered_item = UI_region_views_find_item_at(region, event->xy);
 
   if (!UI_view_item_drop_handle(C, hovered_item, event->customdata)) {
     return OPERATOR_CANCELLED | OPERATOR_PASS_THROUGH;
@@ -2105,14 +2105,14 @@ static void UI_OT_view_drop(wmOperatorType *ot)
 static bool ui_view_item_rename_poll(bContext *C)
 {
   const ARegion *region = CTX_wm_region(C);
-  const uiViewItemHandle *active_item = UI_block_view_find_active_item(region);
+  const uiViewItemHandle *active_item = UI_region_views_find_active_item(region);
   return active_item != NULL && UI_view_item_can_rename(active_item);
 }
 
 static int ui_view_item_rename_exec(bContext *C, wmOperator *UNUSED(op))
 {
   ARegion *region = CTX_wm_region(C);
-  uiViewItemHandle *active_item = UI_block_view_find_active_item(region);
+  uiViewItemHandle *active_item = UI_region_views_find_active_item(region);
 
   UI_view_item_begin_rename(active_item);
   ED_region_tag_redraw(region);
diff --git a/source/blender/editors/interface/views/interface_view.cc b/source/blender/editors/interface/views/interface_view.cc
index b35f6d2c969..c568a8cab74 100644
--- a/source/blender/editors/interface/views/interface_view.cc
+++ b/source/blender/editors/interface/views/interface_view.cc
@@ -3,10 +3,16 @@
 /** \file
  * \ingroup edinterface
  *
- * This part of the UI-View API is mostly needed to support persistent state of items within the
- * view. Views are stored in #uiBlock's, and kept alive with it until after the next redraw. So we
- * can compare the old view items with the new view items and keep state persistent for matching
- * ones.
+ * Code to manage views as part of the regular screen hierarchy. E.g. managing ownership of views
+ * inside blocks (#uiBlock.views), looking up items in the region, passing WM notifiers to views,
+ * etc.
+ *
+ * Blocks and their contained views are reconstructed on every redraw. This file also contains
+ * functions related to this recreation of views inside blocks. For example to query state
+ * information before the view is done reconstructing (#AbstractView.is_reconstructed() returns
+ * false), it may be enough to query the previous version of the block/view/view-item. Since such
+ * queries rely on the details of the UI reconstruction process, they should remain internal to
+ * `interface/` code.
  */
 
 #include <memory>
@@ -86,7 +92,7 @@ void UI_block_views_listen(const uiBlock *block, const wmRegionListenerParams *l
   }
 }
 
-uiViewItemHandle *UI_block_view_find_item_at(const ARegion *region, const int xy[2])
+uiViewItemHandle *UI_region_views_find_item_at(const ARegion *region, const int xy[2])
 {
   uiButViewItem *item_but = (uiButViewItem *)ui_view_item_find_mouse_over(region, xy);
   if (!item_but) {
@@ -96,7 +102,7 @@ uiViewItemHandle *UI_block_view_find_item_at(const ARegion *region, const int xy
   return item_but->view_item;
 }
 
-uiViewItemHandle *UI_block_view_find_active_item(const ARegion *region)
+uiViewItemHandle *UI_region_views_find_active_item(const ARegion *region)
 {
   uiButViewItem *item_but = (uiButViewItem *)ui_view_item_find_active(region);
   if (!item_but) {
diff --git a/source/blender/editors/interface/views/tree_view.cc b/source/blender/editors/interface/views/tree_view.cc
index c224226ba17..21078b711c7 100644
--- a/source/blender/editors/interface/views/tree_view.cc
+++ b/source/blender/editors/interface/views/tree_view.cc
@@ -168,7 +168,7 @@ void AbstractTreeViewItem::collapse_chevron_click_fn(struct bContext *C,
 
   const wmWindow *win = CTX_wm_window(C);
   const ARegion *region = CTX_wm_region(C);
-  uiViewItemHandle *hovered_item_handle = UI_block_view_find_item_at(region, win->eventstate->xy);
+  uiViewItemHandle *hovered_item_handle = UI_region_views_find_item_at(region, win->eventstate->xy);
 
   AbstractTreeViewItem *hovered_item = from_item_handle<AbstractTreeViewItem>(hovered_item_handle);
   BLI_assert(hovered_item != nullptr);