Cleanup: Rename Outliner "tree-view" types to "tree-display" & update comments

See https://developer.blender.org/D9499.

"View" leads to weird names like `TreeViewViewLayer` and after all they are
specific to what we call a "display mode", so "display" is more appropriate.

Also add, update and correct comments.

8 files changed, 87 insertions, 79 deletions

diff --git a/source/blender/editors/space_outliner/CMakeLists.txt b/source/blender/editors/space_outliner/CMakeLists.txt
index bbcd5a32ad6..ec95b0da39f 100644
--- a/source/blender/editors/space_outliner/CMakeLists.txt
+++ b/source/blender/editors/space_outliner/CMakeLists.txt
@@ -45,12 +45,12 @@ set(SRC
   outliner_utils.c
   space_outliner.c
   tree/common.cc
-  tree/tree_view.cc
-  tree/tree_view_libraries.cc
-  tree/tree_view_view_layer.cc
+  tree/tree_display.cc
+  tree/tree_display_libraries.cc
+  tree/tree_display_view_layer.cc
 
   outliner_intern.h
-  tree/tree_view.hh
+  tree/tree_display.hh
 )
 
 set(LIB
diff --git a/source/blender/editors/space_outliner/outliner_intern.h b/source/blender/editors/space_outliner/outliner_intern.h
index adcbcb5a310..0459d669789 100644
--- a/source/blender/editors/space_outliner/outliner_intern.h
+++ b/source/blender/editors/space_outliner/outliner_intern.h
@@ -50,7 +50,7 @@ typedef struct SpaceOutliner_Runtime {
   /**
    * Internal C++ object to create and manage the tree for a specific display type (View Layers,
    * Scenes, Blender File, etc.). */
-  struct TreeView *tree_view;
+  struct TreeDisplay *tree_display;
 } SpaceOutliner_Runtime;
 
 typedef enum TreeElementInsertType {
diff --git a/source/blender/editors/space_outliner/outliner_tree.c b/source/blender/editors/space_outliner/outliner_tree.c
index 67616db6b3a..26871ef14a0 100644
--- a/source/blender/editors/space_outliner/outliner_tree.c
+++ b/source/blender/editors/space_outliner/outliner_tree.c
@@ -85,7 +85,7 @@
 #include "UI_interface.h"
 
 #include "outliner_intern.h"
-#include "tree/tree_view.hh"
+#include "tree/tree_display.hh"
 
 #ifdef WIN32
 #  include "BLI_math_base.h" /* M_PI */
@@ -2214,22 +2214,22 @@ void outliner_build_tree(Main *mainvar,
 
   outliner_free_tree(&space_outliner->tree);
   outliner_storage_cleanup(space_outliner);
-  outliner_tree_view_destroy(&space_outliner->runtime->tree_view);
+  outliner_tree_display_destroy(&space_outliner->runtime->tree_display);
 
-  space_outliner->runtime->tree_view = outliner_tree_view_create(space_outliner->outlinevis,
-                                                                 space_outliner);
-  if (space_outliner->runtime->tree_view) {
+  space_outliner->runtime->tree_display = outliner_tree_display_create(space_outliner->outlinevis,
+                                                                       space_outliner);
+  if (space_outliner->runtime->tree_display) {
     TreeSourceData source_data = {.bmain = mainvar, .scene = scene, .view_layer = view_layer};
-    space_outliner->tree = outliner_tree_view_build_tree(space_outliner->runtime->tree_view,
-                                                         &source_data);
+    space_outliner->tree = outliner_tree_display_build_tree(space_outliner->runtime->tree_display,
+                                                            &source_data);
   }
 
-  if (space_outliner->runtime->tree_view) {
-    /* Skip if there's a tree view that's responsible for adding all elements. */
+  if (space_outliner->runtime->tree_display) {
+    /* Skip if there's a tree-display that's responsible for adding all elements. */
   }
   /* options */
   else if (space_outliner->outlinevis == SO_LIBRARIES) {
-    /* Ported to new tree-view, should be built there already. */
+    /* Ported to new tree-display, should be built there already. */
     BLI_assert(false);
   }
   else if (space_outliner->outlinevis == SO_SCENES) {
@@ -2291,7 +2291,7 @@ void outliner_build_tree(Main *mainvar,
     outliner_add_orphaned_datablocks(mainvar, space_outliner);
   }
   else if (space_outliner->outlinevis == SO_VIEW_LAYER) {
-    /* Ported to new tree-view, should be built there already. */
+    /* Ported to new tree-display, should be built there already. */
     BLI_assert(false);
   }
 
diff --git a/source/blender/editors/space_outliner/tree/common.cc b/source/blender/editors/space_outliner/tree/common.cc
index 56b5d62195e..65c9448634c 100644
--- a/source/blender/editors/space_outliner/tree/common.cc
+++ b/source/blender/editors/space_outliner/tree/common.cc
@@ -17,14 +17,14 @@
 /** \file
  * \ingroup spoutliner
  *
- * Functions and helpers shared between tree-view types or other tree related code.
+ * Functions and helpers shared between tree-display types or other tree related code.
  */
 
 #include "BKE_idtype.h"
 
 #include "RNA_access.h"
 
-#include "tree_view.hh"
+#include "tree_display.hh"
 
 /* -------------------------------------------------------------------- */
 /** \name ID Helpers.
diff --git a/source/blender/editors/space_outliner/tree/tree_view.cc b/source/blender/editors/space_outliner/tree/tree_display.cc
index 7eefae7124c..12599733275 100644
--- a/source/blender/editors/space_outliner/tree/tree_view.cc
+++ b/source/blender/editors/space_outliner/tree/tree_display.cc
@@ -22,39 +22,39 @@
 
 #include "DNA_listBase.h"
 
-#include "tree_view.hh"
+#include "tree_display.hh"
 
 using namespace blender::ed::outliner;
 
-TreeView *outliner_tree_view_create(eSpaceOutliner_Mode mode, SpaceOutliner *space_outliner)
+TreeDisplay *outliner_tree_display_create(eSpaceOutliner_Mode mode, SpaceOutliner *space_outliner)
 {
-  AbstractTreeView *tree_view = nullptr;
+  AbstractTreeDisplay *tree_display = nullptr;
 
   switch (mode) {
     case SO_SCENES:
       break;
     case SO_LIBRARIES:
-      tree_view = new TreeViewLibraries(*space_outliner);
+      tree_display = new TreeDisplayLibraries(*space_outliner);
       break;
     case SO_SEQUENCE:
     case SO_DATA_API:
     case SO_ID_ORPHANS:
       break;
     case SO_VIEW_LAYER:
-      tree_view = new TreeViewViewLayer(*space_outliner);
+      tree_display = new TreeDisplayViewLayer(*space_outliner);
       break;
   }
 
-  return reinterpret_cast<TreeView *>(tree_view);
+  return reinterpret_cast<TreeDisplay *>(tree_display);
 }
 
-void outliner_tree_view_destroy(TreeView **tree_view)
+void outliner_tree_display_destroy(TreeDisplay **tree_display)
 {
-  delete reinterpret_cast<AbstractTreeView *>(*tree_view);
-  *tree_view = nullptr;
+  delete reinterpret_cast<AbstractTreeDisplay *>(*tree_display);
+  *tree_display = nullptr;
 }
 
-ListBase outliner_tree_view_build_tree(TreeView *tree_view, TreeSourceData *source_data)
+ListBase outliner_tree_display_build_tree(TreeDisplay *tree_display, TreeSourceData *source_data)
 {
-  return reinterpret_cast<AbstractTreeView *>(tree_view)->buildTree(*source_data);
+  return reinterpret_cast<AbstractTreeDisplay *>(tree_display)->buildTree(*source_data);
 }
diff --git a/source/blender/editors/space_outliner/tree/tree_view.hh b/source/blender/editors/space_outliner/tree/tree_display.hh
index 63a0826b440..1aefc49d8e8 100644
--- a/source/blender/editors/space_outliner/tree/tree_view.hh
+++ b/source/blender/editors/space_outliner/tree/tree_display.hh
@@ -17,8 +17,19 @@
 /** \file
  * \ingroup spoutliner
  *
- * For now all sub-class declarations of #AbstractTreeView are in this file. They could be moved
- * into own headers of course.
+ * \brief Establish and manage Outliner trees for different display modes.
+ *
+ * Each Outliner display mode (e.g View Layer, Scenes, Blender File) is implemented as a
+ * tree-display class with the #AbstractTreeDisplay interface.
+ *
+ * Their main responsibility is building the Outliner tree for a display mode. For that, they
+ * implement the #buildTree() function, which based on Blender data (#TreeSourceData), builds a
+ * custom tree of whatever data it wants to visualize.
+ * Further, they can implement display mode dependent queries and general operations using the
+ * #AbstractTreeDisplay abstraction as common interface.
+ *
+ * Outliners keep the current tree-display object alive until the next full tree rebuild to keep
+ * access to it.
  */
 
 #pragma once
@@ -36,26 +47,23 @@ struct TreeSourceData;
 namespace blender::ed::outliner {
 
 /* -------------------------------------------------------------------- */
-/* Tree-View Interface */
+/* Tree-Display Interface */
 
 /**
- * \brief Base Class For Tree-Views
+ * \brief Base Class For Tree-Displays
  *
- * Abstract base class defining the interface for tree-view variants. For each Outliner display
- * type (e.g View Layer, Scenes, Blender File), a derived class implements a #buildTree() function,
- * that based on Blender data (#TreeSourceData), builds a custom tree of whatever data it wants to
- * visualize.
+ * Abstract base class defining the interface for tree-display variants.
  */
-class AbstractTreeView {
+class AbstractTreeDisplay {
  public:
-  AbstractTreeView(SpaceOutliner &space_outliner) : space_outliner_(space_outliner)
+  AbstractTreeDisplay(SpaceOutliner &space_outliner) : space_outliner_(space_outliner)
   {
   }
-  virtual ~AbstractTreeView() = default;
+  virtual ~AbstractTreeDisplay() = default;
 
   /**
-   * Build a tree for this view with the Blender context data given in \a source_data and the view
-   * settings in \a space_outliner.
+   * Build a tree for this display mode with the Blender context data given in \a source_data and
+   * the view settings in \a space_outliner.
    */
   virtual ListBase buildTree(const TreeSourceData &source_data) = 0;
 
@@ -65,17 +73,17 @@ class AbstractTreeView {
 };
 
 /* -------------------------------------------------------------------- */
-/* View Layer Tree-View */
+/* View Layer Tree-Display */
 
 /**
- * \brief Tree-View for the View Layer display mode.
+ * \brief Tree-Display for the View Layer display mode.
  */
-class TreeViewViewLayer final : public AbstractTreeView {
+class TreeDisplayViewLayer final : public AbstractTreeDisplay {
   ViewLayer *view_layer_ = nullptr;
   bool show_objects_ = true;
 
  public:
-  TreeViewViewLayer(SpaceOutliner &space_outliner);
+  TreeDisplayViewLayer(SpaceOutliner &space_outliner);
 
   ListBase buildTree(const TreeSourceData &source_data) override;
 
@@ -87,14 +95,14 @@ class TreeViewViewLayer final : public AbstractTreeView {
 };
 
 /* -------------------------------------------------------------------- */
-/* Library Tree-View */
+/* Library Tree-Display */
 
 /**
- * \brief Tree-View for the Libraries display mode.
+ * \brief Tree-Display for the Libraries display mode.
  */
-class TreeViewLibraries final : public AbstractTreeView {
+class TreeDisplayLibraries final : public AbstractTreeDisplay {
  public:
-  TreeViewLibraries(SpaceOutliner &space_outliner);
+  TreeDisplayLibraries(SpaceOutliner &space_outliner);
 
   ListBase buildTree(const TreeSourceData &source_data) override;
 
@@ -112,8 +120,8 @@ extern "C" {
 /* -------------------------------------------------------------------- */
 /* C-API */
 
-/** There is no actual implementation of this, it's the C name for an #AbstractTreeView handle. */
-typedef struct TreeView TreeView;
+/** C alias for an #AbstractTreeDisplay handle. */
+typedef struct TreeDisplay TreeDisplay;
 
 /**
  * \brief The data to build the tree from.
@@ -124,12 +132,12 @@ typedef struct TreeSourceData {
   struct ViewLayer *view_layer;
 } TreeSourceData;
 
-TreeView *outliner_tree_view_create(eSpaceOutliner_Mode mode, SpaceOutliner *space_outliner);
-void outliner_tree_view_destroy(TreeView **tree_view);
+TreeDisplay *outliner_tree_display_create(eSpaceOutliner_Mode mode, SpaceOutliner *space_outliner);
+void outliner_tree_display_destroy(TreeDisplay **tree_display);
 
-ListBase outliner_tree_view_build_tree(TreeView *tree_view, TreeSourceData *source_data);
+ListBase outliner_tree_display_build_tree(TreeDisplay *tree_display, TreeSourceData *source_data);
 
-/* The following functions are needed to build the tree. These are calls back into C; the way
+/* The following functions are needed to build the tree. They are calls back into C; the way
  * elements are created should be refactored and ported to C++ with a new design/API too. */
 struct TreeElement *outliner_add_element(struct SpaceOutliner *space_outliner,
                                          ListBase *lb,
diff --git a/source/blender/editors/space_outliner/tree/tree_view_libraries.cc b/source/blender/editors/space_outliner/tree/tree_display_libraries.cc
index bd75bba83eb..bd0870c837c 100644
--- a/source/blender/editors/space_outliner/tree/tree_view_libraries.cc
+++ b/source/blender/editors/space_outliner/tree/tree_display_libraries.cc
@@ -27,19 +27,19 @@
 #include "BLT_translation.h"
 
 #include "../outliner_intern.h"
-#include "tree_view.hh"
+#include "tree_display.hh"
 
 namespace blender::ed::outliner {
 
 /* Convenience/readability. */
 template<typename T> using List = ListBaseWrapper<T>;
 
-TreeViewLibraries::TreeViewLibraries(SpaceOutliner &space_outliner)
-    : AbstractTreeView(space_outliner)
+TreeDisplayLibraries::TreeDisplayLibraries(SpaceOutliner &space_outliner)
+    : AbstractTreeDisplay(space_outliner)
 {
 }
 
-ListBase TreeViewLibraries::buildTree(const TreeSourceData &source_data)
+ListBase TreeDisplayLibraries::buildTree(const TreeSourceData &source_data)
 {
   ListBase tree = {nullptr};
 
@@ -103,9 +103,9 @@ ListBase TreeViewLibraries::buildTree(const TreeSourceData &source_data)
   return tree;
 }
 
-TreeElement *TreeViewLibraries::add_library_contents(Main &mainvar,
-                                                     ListBase &lb,
-                                                     Library *lib) const
+TreeElement *TreeDisplayLibraries::add_library_contents(Main &mainvar,
+                                                        ListBase &lb,
+                                                        Library *lib) const
 {
   const short filter_id_type = id_filter_get();
 
@@ -176,7 +176,7 @@ TreeElement *TreeViewLibraries::add_library_contents(Main &mainvar,
   return tenlib;
 }
 
-short TreeViewLibraries::id_filter_get() const
+short TreeDisplayLibraries::id_filter_get() const
 {
   if (space_outliner_.filter & SO_FILTER_ID_TYPE) {
     return space_outliner_.filter_id_type;
@@ -184,7 +184,7 @@ short TreeViewLibraries::id_filter_get() const
   return 0;
 }
 
-bool TreeViewLibraries::library_id_filter_poll(Library *lib, ID *id) const
+bool TreeDisplayLibraries::library_id_filter_poll(Library *lib, ID *id) const
 {
   if (id->lib != lib) {
     return false;
diff --git a/source/blender/editors/space_outliner/tree/tree_view_view_layer.cc b/source/blender/editors/space_outliner/tree/tree_display_view_layer.cc
index 8895673f060..123c47b8556 100644
--- a/source/blender/editors/space_outliner/tree/tree_view_view_layer.cc
+++ b/source/blender/editors/space_outliner/tree/tree_display_view_layer.cc
@@ -32,7 +32,7 @@
 #include "BLT_translation.h"
 
 #include "../outliner_intern.h"
-#include "tree_view.hh"
+#include "tree_display.hh"
 
 namespace blender::ed::outliner {
 
@@ -58,16 +58,16 @@ class ObjectsChildrenBuilder {
 };
 
 /* -------------------------------------------------------------------- */
-/** \name Tree View for a View Layer.
+/** \name Tree-Display for a View Layer.
  *
  * \{ */
 
-TreeViewViewLayer::TreeViewViewLayer(SpaceOutliner &space_outliner)
-    : AbstractTreeView(space_outliner)
+TreeDisplayViewLayer::TreeDisplayViewLayer(SpaceOutliner &space_outliner)
+    : AbstractTreeDisplay(space_outliner)
 {
 }
 
-ListBase TreeViewViewLayer::buildTree(const TreeSourceData &source_data)
+ListBase TreeDisplayViewLayer::buildTree(const TreeSourceData &source_data)
 {
   ListBase tree = {nullptr};
 
@@ -104,7 +104,7 @@ ListBase TreeViewViewLayer::buildTree(const TreeSourceData &source_data)
   return tree;
 }
 
-void TreeViewViewLayer::add_view_layer(ListBase &tree, TreeElement &parent)
+void TreeDisplayViewLayer::add_view_layer(ListBase &tree, TreeElement &parent)
 {
   /* First layer collection is for master collection, don't show it. */
   LayerCollection *lc = static_cast<LayerCollection *>(view_layer_->layer_collections.first);
@@ -118,9 +118,9 @@ void TreeViewViewLayer::add_view_layer(ListBase &tree, TreeElement &parent)
   }
 }
 
-void TreeViewViewLayer::add_layer_collections_recursive(ListBase &tree,
-                                                        ListBase &layer_collections,
-                                                        TreeElement &parent_ten)
+void TreeDisplayViewLayer::add_layer_collections_recursive(ListBase &tree,
+                                                           ListBase &layer_collections,
+                                                           TreeElement &parent_ten)
 {
   for (LayerCollection *lc : List<LayerCollection>(layer_collections)) {
     const bool exclude = (lc->flag & LAYER_COLLECTION_EXCLUDE) != 0;
@@ -155,9 +155,9 @@ void TreeViewViewLayer::add_layer_collections_recursive(ListBase &tree,
   }
 }
 
-void TreeViewViewLayer::add_layer_collection_objects(ListBase &tree,
-                                                     LayerCollection &lc,
-                                                     TreeElement &ten)
+void TreeDisplayViewLayer::add_layer_collection_objects(ListBase &tree,
+                                                        LayerCollection &lc,
+                                                        TreeElement &ten)
 {
   for (CollectionObject *cob : List<CollectionObject>(lc.collection->gobject)) {
     Base *base = BKE_view_layer_base_find(view_layer_, cob->ob);
@@ -171,7 +171,7 @@ void TreeViewViewLayer::add_layer_collection_objects(ListBase &tree,
   }
 }
 
-void TreeViewViewLayer::add_layer_collection_objects_children(TreeElement &collection_tree_elem)
+void TreeDisplayViewLayer::add_layer_collection_objects_children(TreeElement &collection_tree_elem)
 {
   /* Call helper to add children. */
   ObjectsChildrenBuilder child_builder{space_outliner_};
@@ -181,7 +181,7 @@ void TreeViewViewLayer::add_layer_collection_objects_children(TreeElement &colle
 /** \} */
 
 /* -------------------------------------------------------------------- */
-/** \name Object Chilren helper.
+/** \name Object Children helper.
  *
  * Helper to add child objects to the sub-tree of their parent, recursively covering all nested
  * collections.