UI_tree_view.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2023 Blender Authors
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */

 
#pragma once
 
#include <functional>
#include <memory>
#include <string>
 
#include "BLI_function_ref.hh"
#include "BLI_math_vector_types.hh"
#include "BLI_vector.hh"
 
#include "UI_abstract_view.hh"
#include "UI_resources.hh"
 
struct bContext;
struct uiBlock;
struct uiLayout;
 
namespace blender::ui {
 
class AbstractTreeView;
class AbstractTreeViewItem;
class TreeViewItemDropTarget;
 
/* ---------------------------------------------------------------------- */

class TreeViewItemContainer {
  friend class AbstractTreeView;
  friend class AbstractTreeViewItem;
 
  /* Private constructor, so only the friends above can create this! */
  TreeViewItemContainer() = default;
 
 protected:
  Vector<std::unique_ptr<AbstractTreeViewItem>> children_;
  TreeViewItemContainer *root_ = nullptr;
  AbstractTreeViewItem *parent_ = nullptr;

  bool is_flat_ = false;
 
 public:
  enum class IterOptions {
    None = 0,
    SkipCollapsed = 1 << 0,
    SkipFiltered = 1 << 1,
 
    /* Keep ENUM_OPERATORS() below updated! */
  };
  using ItemIterFn = FunctionRef<void(AbstractTreeViewItem &)>;

  template<class ItemT, typename... Args> inline ItemT &add_tree_item(Args &&...args);
  AbstractTreeViewItem &add_tree_item(std::unique_ptr<AbstractTreeViewItem> item);
 
 protected:
  void foreach_item_recursive(ItemIterFn iter_fn, IterOptions options = IterOptions::None) const;
  void foreach_parent(ItemIterFn iter_fn) const;
};
 
ENUM_OPERATORS(TreeViewItemContainer::IterOptions,
               TreeViewItemContainer::IterOptions::SkipCollapsed);

using TreeViewOrItem = TreeViewItemContainer;

 
/* ---------------------------------------------------------------------- */
 
class AbstractTreeView : public AbstractView, public TreeViewItemContainer {
  /* Shared pointer so the pointer can be kept persistent over redraws. The grip button gets a
   * pointer to modify the value on resizing, and it uses it to identify the button over redraws.
   */
  /* TODO support region zoom. */
  std::shared_ptr<int> custom_height_ = nullptr;
  std::shared_ptr<int> scroll_value_ = nullptr;
  int last_tot_items_ = 0;
 
  bool scroll_active_into_view_on_draw_ = false;
  std::shared_ptr<char> show_display_options_ = std::make_shared<char>(0);
  /* `char[UI_MAX_NAME_STR]` wrapped in shared pointer, to keep a stable pointer over
   * reconstruction that can be passed to buttons. */
  std::shared_ptr<char[]> search_string_{new char[256 /*UI_MAX_NAME_STR*/]{}};
 
  friend class AbstractTreeViewItem;
  friend class TreeViewBuilder;
  friend class TreeViewLayoutBuilder;
  friend class TreeViewItemDropTarget;
 
 public:
  /* virtual */ ~AbstractTreeView() override = default;
 
  void draw_overlays(const ARegion &region, const uiBlock &block) const override;
 
  void foreach_item(ItemIterFn iter_fn, IterOptions options = IterOptions::None) const;
  void foreach_root_item(ItemIterFn iter_fn) const;
 
  bool is_fully_visible() const override;
  void scroll(ViewScrollDirection direction) override;
  /* Scroll to the active element when state is changed. */

  AbstractTreeViewItem *find_hovered(const ARegion &region, const int2 &xy);

  void set_default_rows(int default_rows);
 
 protected:
  virtual void build_tree() = 0;
 
  std::optional<uiViewState> persistent_state() const override;
  void persistent_state_apply(const uiViewState &state) override;
 
 private:
  void foreach_view_item(FunctionRef<void(AbstractViewItem &)> iter_fn) const final;
  void update_children_from_old(const AbstractView &old_view) override;
  static void update_children_from_old_recursive(const TreeViewOrItem &new_items,
                                                 const TreeViewOrItem &old_items);
  static AbstractTreeViewItem *find_matching_child(
      const AbstractTreeViewItem &lookup_item, const Span<AbstractTreeViewItem *> possible_items);
  std::optional<int> tot_visible_row_count() const;
 
  bool supports_scrolling() const override;
 
  void draw_hierarchy_lines(const ARegion &region, const uiBlock &block) const;
  void get_hierarchy_lines(const ARegion &region,
                           const TreeViewOrItem &parent,
                           const float aspect,
                           Vector<std::pair<int2, int2>> &lines,
                           int &visible_item_index) const;
 
  int count_visible_descendants(const AbstractTreeViewItem &parent) const;
  void scroll_active_into_view();
};

 
/* ---------------------------------------------------------------------- */

class AbstractTreeViewItem : public AbstractViewItem, public TreeViewItemContainer {
  friend class AbstractTreeView;
  friend class TreeViewLayoutBuilder;
  /* Higher-level API. */
  friend class TreeViewItemAPIWrapper;
 
 private:
  bool is_open_ = false;
 
 protected:
  std::string label_;
 
 public:
  /* virtual */ ~AbstractTreeViewItem() override = default;
 
  virtual void build_row(uiLayout &row) = 0;
 
  /* virtual */ std::optional<std::string> debug_name() const override;
 
  std::unique_ptr<DropTargetInterface> create_item_drop_target() final;
  virtual std::unique_ptr<TreeViewItemDropTarget> create_drop_target();
 
  AbstractTreeView &get_tree_view() const;
  std::optional<rctf> get_win_rect(const ARegion &region) const;
 
  void begin_renaming();

  bool toggle_collapsed();
  virtual bool set_collapsed(bool collapsed);
  virtual void on_collapse_change(bContext &C, bool is_collapsed);
  virtual std::optional<bool> should_be_collapsed() const;

  void uncollapse_by_default();

  bool is_collapsed() const;
  bool is_collapsible() const;
 
  int count_parents() const;
 
  void on_filter_change() override;
 
 protected:
  /* virtual */ StringRef get_rename_string() const override;
  /* virtual */ bool rename(const bContext &C, StringRefNull new_name) override;

  virtual bool supports_collapsing() const;

  void toggle_collapsed_from_view(bContext &C);
 
  void change_state_delayed() override;

  /* virtual */ bool matches(const AbstractViewItem &other) const override;

  /* virtual */ void update_from_old(const AbstractViewItem &old) override;

  virtual bool matches_single(const AbstractTreeViewItem &other) const;

  bool is_hovered() const;
 
  void ensure_parents_uncollapsed();
 
 private:
  static void collapse_chevron_click_fn(bContext *, void *but_arg1, void *);

  bool set_state_active() final;
 
  void add_treerow_button(uiBlock &block);
  int indent_width() const;
  void add_indent(uiLayout &row) const;
  void add_collapse_chevron(uiBlock &block) const;
  void add_rename_button(uiLayout &row);
 
  bool has_active_child() const;
};

 
/* ---------------------------------------------------------------------- */

class BasicTreeViewItem : public AbstractTreeViewItem {
 public:
  using IsActiveFn = std::function<bool()>;
  using ActivateFn = std::function<void(bContext &C, BasicTreeViewItem &new_active)>;
  BIFIconID icon;
 
  explicit BasicTreeViewItem(StringRef label, BIFIconID icon = ICON_NONE);
 
  void build_row(uiLayout &row) override;
  void add_label(uiLayout &layout, StringRefNull label_override = "");
  void set_on_activate_fn(ActivateFn fn);
  void set_is_active_fn(IsActiveFn is_active_fn);
 
 protected:
  ActivateFn activate_fn_;
 
  IsActiveFn is_active_fn_;
 
 private:
  std::optional<bool> should_be_active() const override;
  void on_activate(bContext &C) override;
};

 
/* ---------------------------------------------------------------------- */

class TreeViewItemDropTarget : public DropTargetInterface {
 protected:
  AbstractTreeViewItem &view_item_;
  const DropBehavior behavior_;
 
 public:
  TreeViewItemDropTarget(AbstractTreeViewItem &view_item,
                         DropBehavior behavior = DropBehavior::Insert);
 
  std::optional<DropLocation> choose_drop_location(const ARegion &region,
                                                   const wmEvent &event) const override;

  template<class ViewType> inline ViewType &get_view() const;
};

 
/* ---------------------------------------------------------------------- */
 
class TreeViewBuilder {
 public:
  static void build_tree_view(const bContext &C,
                              AbstractTreeView &tree_view,
                              uiLayout &layout,
                              bool add_box = true);
 
 private:
  static void ensure_min_rows_items(AbstractTreeView &tree_view);
};

 
/* ---------------------------------------------------------------------- */
 
template<class ItemT, typename... Args>
inline ItemT &TreeViewItemContainer::add_tree_item(Args &&...args)
{
  static_assert(std::is_base_of_v<AbstractTreeViewItem, ItemT>,
                "Type must derive from and implement the AbstractTreeViewItem interface");
 
  return dynamic_cast<ItemT &>(
      add_tree_item(std::make_unique<ItemT>(std::forward<Args>(args)...)));
}
 
template<class ViewType> ViewType &TreeViewItemDropTarget::get_view() const
{
  static_assert(std::is_base_of_v<AbstractTreeView, ViewType>,
                "Type must derive from and implement the ui::AbstractTreeView interface");
  return dynamic_cast<ViewType &>(view_item_.get_tree_view());
}
 
}  // namespace blender::ui