Outliner: Add generic label element type

No user visible changes expected.

NOTE: This is committed to the 3.3 branch as part of D15606, which we
decided should go to this release still (by Bastien, Dalai and me). That
is because these are important usability fixes/improvements to have for
the LTS release.

We have a bunch of "base" element types, just to show a label element
for grouping together other elements. There is no reason to have these
tied to a case, just have a generic label type for this. It requires a
string to display, and can display an icon too. The new element type
isn't used yet, but will be in one of the following commits. Would be
nice if the existing base elements can be replaced by this.

Part of D15606.

8 files changed, 132 insertions, 18 deletions

diff --git a/source/blender/editors/space_outliner/CMakeLists.txt b/source/blender/editors/space_outliner/CMakeLists.txt
index 97d2957eed2..78ec057f921 100644
--- a/source/blender/editors/space_outliner/CMakeLists.txt
+++ b/source/blender/editors/space_outliner/CMakeLists.txt
@@ -48,6 +48,7 @@ set(SRC
   tree/tree_element_anim_data.cc
   tree/tree_element_collection.cc
   tree/tree_element_driver.cc
+  tree/tree_element_label.cc
   tree/tree_element_gpencil_layer.cc
   tree/tree_element_id.cc
   tree/tree_element_id_library.cc
@@ -67,6 +68,7 @@ set(SRC
   tree/tree_element_anim_data.hh
   tree/tree_element_collection.hh
   tree/tree_element_driver.hh
+  tree/tree_element_label.hh
   tree/tree_element_gpencil_layer.hh
   tree/tree_element_id.hh
   tree/tree_element_id_library.hh
diff --git a/source/blender/editors/space_outliner/outliner_draw.cc b/source/blender/editors/space_outliner/outliner_draw.cc
index 6bab0b938e8..fd38bcfc5e2 100644
--- a/source/blender/editors/space_outliner/outliner_draw.cc
+++ b/source/blender/editors/space_outliner/outliner_draw.cc
@@ -2828,10 +2828,20 @@ TreeElementIcon tree_element_get_icon(TreeStoreElem *tselem, TreeElement *te)
     data.icon = tree_element_get_icon_from_id(tselem->id);
   }
 
+  if (!te->abstract_element) {
+    /* Pass */
+  }
+  else if (auto icon = te->abstract_element->getIcon()) {
+    data.icon = *icon;
+  }
+
   return data;
 }
 
-static void tselem_draw_icon(uiBlock *block,
+/**
+ * \return Return true if the element has an icon that was drawn, false if it doesn't have an icon.
+ */
+static bool tselem_draw_icon(uiBlock *block,
                              int xmax,
                              float x,
                              float y,
@@ -2842,7 +2852,7 @@ static void tselem_draw_icon(uiBlock *block,
 {
   TreeElementIcon data = tree_element_get_icon(tselem, te);
   if (data.icon == 0) {
-    return;
+    return false;
   }
 
   const bool is_collection = outliner_is_collection_tree_element(te);
@@ -2866,7 +2876,7 @@ static void tselem_draw_icon(uiBlock *block,
                         0.0f,
                         btheme->collection_color[collection->color_tag].color,
                         true);
-        return;
+        return true;
       }
     }
 
@@ -2898,6 +2908,8 @@ static void tselem_draw_icon(uiBlock *block,
                  alpha,
                  (data.drag_id && ID_IS_LINKED(data.drag_id)) ? data.drag_id->lib->filepath : "");
   }
+
+  return true;
 }
 
 /**
@@ -3317,15 +3329,15 @@ static void outliner_draw_tree_element(bContext *C,
     offsx += UI_UNIT_X;
 
     /* Data-type icon. */
-    if (!(ELEM(tselem->type, TSE_RNA_PROPERTY, TSE_RNA_ARRAY_ELEM, TSE_ID_BASE))) {
-      tselem_draw_icon(block,
-                       xmax,
-                       (float)startx + offsx,
-                       (float)*starty,
-                       tselem,
-                       te,
-                       (tselem->flag & TSE_HIGHLIGHTED_ICON) ? alpha_fac + 0.5f : alpha_fac,
-                       true);
+    if (!(ELEM(tselem->type, TSE_RNA_PROPERTY, TSE_RNA_ARRAY_ELEM, TSE_ID_BASE)) &&
+        tselem_draw_icon(block,
+                         xmax,
+                         (float)startx + offsx,
+                         (float)*starty,
+                         tselem,
+                         te,
+                         (tselem->flag & TSE_HIGHLIGHTED_ICON) ? alpha_fac + 0.5f : alpha_fac,
+                         true)) {
       offsx += UI_UNIT_X + 4 * ufac;
     }
     else {
diff --git a/source/blender/editors/space_outliner/outliner_tree.cc b/source/blender/editors/space_outliner/outliner_tree.cc
index aa739758ecb..b2199f18b7b 100644
--- a/source/blender/editors/space_outliner/outliner_tree.cc
+++ b/source/blender/editors/space_outliner/outliner_tree.cc
@@ -817,9 +817,12 @@ TreeElement *outliner_add_element(SpaceOutliner *space_outliner,
     /* idv is the layer itself */
     id = TREESTORE(parent)->id;
   }
+  else if (ELEM(type, TSE_GENERIC_LABEL)) {
+    id = nullptr;
+  }
 
   /* exceptions */
-  if (type == TSE_ID_BASE) {
+  if (ELEM(type, TSE_ID_BASE, TSE_GENERIC_LABEL)) {
     /* pass */
   }
   else if (id == nullptr) {
@@ -869,7 +872,7 @@ TreeElement *outliner_add_element(SpaceOutliner *space_outliner,
   else if (ELEM(type, TSE_LAYER_COLLECTION, TSE_SCENE_COLLECTION_BASE, TSE_VIEW_COLLECTION_BASE)) {
     /* pass */
   }
-  else if (type == TSE_ID_BASE) {
+  else if (ELEM(type, TSE_ID_BASE, TSE_GENERIC_LABEL)) {
     /* pass */
   }
   else if (type == TSE_SOME_ID) {
@@ -895,10 +898,13 @@ TreeElement *outliner_add_element(SpaceOutliner *space_outliner,
     te->idcode = GS(id->name);
   }
 
-  if (expand && te->abstract_element && te->abstract_element->isExpandValid()) {
+  if (!expand) {
+    /* Pass */
+  }
+  else if (te->abstract_element && te->abstract_element->isExpandValid()) {
     tree_element_expand(*te->abstract_element, *space_outliner);
   }
-  else if (expand && (type == TSE_SOME_ID)) {
+  else if (type == TSE_SOME_ID) {
     /* ID types not (fully) ported to new design yet. */
     if (te->abstract_element->expandPoll(*space_outliner)) {
       outliner_add_id_contents(space_outliner, te, tselem, id);
@@ -916,7 +922,8 @@ TreeElement *outliner_add_element(SpaceOutliner *space_outliner,
                 TSE_RNA_ARRAY_ELEM,
                 TSE_SEQUENCE,
                 TSE_SEQ_STRIP,
-                TSE_SEQUENCE_DUP)) {
+                TSE_SEQUENCE_DUP,
+                TSE_GENERIC_LABEL)) {
     BLI_assert_msg(false, "Element type should already use new AbstractTreeElement design");
   }
 
diff --git a/source/blender/editors/space_outliner/tree/tree_element.cc b/source/blender/editors/space_outliner/tree/tree_element.cc
index 94d55b70e3c..9bc65ce572b 100644
--- a/source/blender/editors/space_outliner/tree/tree_element.cc
+++ b/source/blender/editors/space_outliner/tree/tree_element.cc
@@ -17,6 +17,7 @@
 #include "tree_element_driver.hh"
 #include "tree_element_gpencil_layer.hh"
 #include "tree_element_id.hh"
+#include "tree_element_label.hh"
 #include "tree_element_nla.hh"
 #include "tree_element_overrides.hh"
 #include "tree_element_rna.hh"
@@ -52,6 +53,8 @@ std::unique_ptr<AbstractTreeElement> AbstractTreeElement::createFromType(const i
   switch (type) {
     case TSE_SOME_ID:
       return TreeElementID::createFromID(legacy_te, *static_cast<ID *>(idv));
+    case TSE_GENERIC_LABEL:
+      return std::make_unique<TreeElementLabel>(legacy_te, static_cast<const char *>(idv));
     case TSE_ANIM_DATA:
       return std::make_unique<TreeElementAnimData>(legacy_te,
                                                    *reinterpret_cast<IdAdtTemplate *>(idv)->adt);
@@ -105,6 +108,11 @@ StringRefNull AbstractTreeElement::getWarning() const
   return "";
 }
 
+std::optional<BIFIconID> AbstractTreeElement::getIcon() const
+{
+  return {};
+}
+
 void AbstractTreeElement::uncollapse_by_default(TreeElement *legacy_te)
 {
   if (!TREESTORE(legacy_te)->used) {
diff --git a/source/blender/editors/space_outliner/tree/tree_element.hh b/source/blender/editors/space_outliner/tree/tree_element.hh
index 1098068d628..a3598e7740b 100644
--- a/source/blender/editors/space_outliner/tree/tree_element.hh
+++ b/source/blender/editors/space_outliner/tree/tree_element.hh
@@ -7,8 +7,10 @@
 #pragma once
 
 #include <memory>
+#include <optional>
 
 #include "BLI_string_ref.hh"
+#include "UI_resources.h"
 
 struct ListBase;
 struct SpaceOutliner;
@@ -64,6 +66,15 @@ class AbstractTreeElement {
   virtual StringRefNull getWarning() const;
 
   /**
+   * Define the icon to be displayed for this element. If this returns an icon, this will be
+   * displayed. Otherwise, #tree_element_get_icon() may still determine an icon. By default no
+   * value is returned (#std::nullopt).
+   *
+   * All elements should be ported to use this over #tree_element_get_icon().
+   */
+  virtual std::optional<BIFIconID> getIcon() const;
+
+  /**
    * Expand this tree element if it is displayed for the first time (as identified by its
    * tree-store element).
    *
diff --git a/source/blender/editors/space_outliner/tree/tree_element_label.cc b/source/blender/editors/space_outliner/tree/tree_element_label.cc
new file mode 100644
index 00000000000..32fa62c5f5e
--- /dev/null
+++ b/source/blender/editors/space_outliner/tree/tree_element_label.cc
@@ -0,0 +1,36 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+
+/** \file
+ * \ingroup spoutliner
+ */
+
+#include "DNA_listBase.h"
+
+#include "DNA_outliner_types.h"
+
+#include "../outliner_intern.hh"
+
+#include "tree_element_label.hh"
+
+namespace blender::ed::outliner {
+
+TreeElementLabel::TreeElementLabel(TreeElement &legacy_te, const char *label)
+    : AbstractTreeElement(legacy_te), label_(label)
+{
+  BLI_assert(legacy_te_.store_elem->type == TSE_GENERIC_LABEL);
+  /* The draw string is actually accessed via #TreeElement.name, so make sure this always points to
+   * our string. */
+  legacy_te_.name = label_.c_str();
+}
+
+void TreeElementLabel::setIcon(const BIFIconID icon)
+{
+  icon_ = icon;
+}
+
+std::optional<BIFIconID> TreeElementLabel::getIcon() const
+{
+  return icon_;
+}
+
+}  // namespace blender::ed::outliner
diff --git a/source/blender/editors/space_outliner/tree/tree_element_label.hh b/source/blender/editors/space_outliner/tree/tree_element_label.hh
new file mode 100644
index 00000000000..fc730c7b8f4
--- /dev/null
+++ b/source/blender/editors/space_outliner/tree/tree_element_label.hh
@@ -0,0 +1,36 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+
+/** \file
+ * \ingroup spoutliner
+ */
+
+#pragma once
+
+#include <string>
+
+#include "UI_resources.h"
+
+#include "tree_element.hh"
+
+namespace blender::ed::outliner {
+
+/**
+ * A basic, general purpose tree element to just display a label and an icon. Can be used to group
+ * together items underneath as well of course.
+ *
+ * Make sure to give this a unique index, so the element can be identified uniquely. Otherwise
+ * glitches like multiple highlighted elements happen, that share all state (e.g. collapsed,
+ * selected, etc.).
+ */
+class TreeElementLabel final : public AbstractTreeElement {
+  const std::string label_;
+  BIFIconID icon_ = ICON_NONE;
+
+ public:
+  TreeElementLabel(TreeElement &legacy_te, const char *label);
+
+  void setIcon(BIFIconID icon);
+  std::optional<BIFIconID> getIcon() const override;
+};
+
+}  // namespace blender::ed::outliner
diff --git a/source/blender/makesdna/DNA_outliner_types.h b/source/blender/makesdna/DNA_outliner_types.h
index 4a2e3e1ab72..f7a4dbc83d5 100644
--- a/source/blender/makesdna/DNA_outliner_types.h
+++ b/source/blender/makesdna/DNA_outliner_types.h
@@ -114,6 +114,7 @@ typedef enum eTreeStoreElemType {
   TSE_GPENCIL_EFFECT = 43,
   TSE_LIBRARY_OVERRIDE_BASE = 44,
   TSE_LIBRARY_OVERRIDE = 45,
+  TSE_GENERIC_LABEL = 47,              /* No ID */
 } eTreeStoreElemType;
 
 /** Check whether given #TreeStoreElem should have a real ID in #TreeStoreElem.id member. */
@@ -129,7 +130,8 @@ typedef enum eTreeStoreElemType {
          TSE_RNA_PROPERTY, \
          TSE_RNA_ARRAY_ELEM, \
          TSE_ID_BASE, \
-         TSE_GP_LAYER))
+         TSE_GP_LAYER, \
+         TSE_GENERIC_LABEL))
 
 #ifdef __cplusplus
 }