UI_interface_layout.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2025 Blender Authors
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */
 
#pragma once
 
#include <functional>
#include <optional>
 
#include "BLI_math_vector_types.hh"
#include "BLI_string_ref.hh"
#include "BLI_utility_mixins.hh"
#include "BLI_vector.hh"
 
#include "UI_interface_icons.hh" /* `eAlertIcon` */
#include "UI_interface_types.hh"
 
struct bContext;
struct bContextStore;
struct EnumPropertyItem;
struct IDProperty;
struct uiBlock;
struct uiBut;
struct uiLayoutRoot;
struct uiList;
struct uiStyle;
struct MenuType;
struct PanelType;
struct Panel;
struct PointerRNA;
struct PropertyRNA;
struct StructRNA;
struct wmOperatorType;
 
/* Layout
 *
 * More automated layout of buttons. Has three levels:
 * - Layout: contains a number templates, within a bounded width or height.
 * - Template: predefined layouts for buttons with a number of slots, each
 *   slot can contain multiple items.
 * - Item: item to put in a template slot, being either an RNA property,
 *   operator, label or menu. Also regular buttons can be used when setting
 *   uiBlockCurLayout. */
 
namespace blender::ui {
enum class ItemType : int8_t;
enum class ItemInternalFlag : uint8_t;
enum class EmbossType : uint8_t;
enum class LayoutAlign : int8_t;
enum class ButProgressType : int8_t;
enum class LayoutDirection : int8_t;
 
struct ItemInternal;
struct LayoutInternal;
}  // namespace blender::ui
 
namespace blender::wm {
enum class OpCallContext : int8_t;
}
 
struct PanelLayout {
  uiLayout *header;
  uiLayout *body;
};
 
struct uiItem {
 
  uiItem(blender::ui::ItemType type);
  uiItem(const uiItem &) = default;
  virtual ~uiItem() = default;
 
  [[nodiscard]] bool fixed_size() const;
  void fixed_size_set(bool fixed_size);
 
  [[nodiscard]] blender::ui::ItemType type() const;
 
 protected:
  blender::ui::ItemInternalFlag flag_ = {};
  blender::ui::ItemType type_ = {};
 
  friend struct blender::ui::ItemInternal;
};
 
enum eUI_Item_Flag : uint16_t;
 
enum class LayoutSeparatorType : int8_t {
  Auto,
  Space,
  Line,
};
 
enum class NodeAssetMenuOperatorType : int8_t {
  Add,
  Swap,
};

struct uiLayout : public uiItem, blender::NonCopyable, blender::NonMovable {
  // protected:
 
  int x_ = 0, y_ = 0, w_ = 0, h_ = 0;
  short space_ = 0;
 
 protected:
  uiLayoutRoot *root_ = nullptr;
  bContextStore *context_ = nullptr;
  uiLayout *parent_ = nullptr;
  std::string heading_;
 
  blender::Vector<uiItem *> items_;

  uiLayout *child_items_layout_ = nullptr;
 
  float scale_[2] = {0.0f, 0.0f};
  bool align_ = false;
  bool active_ = false;
  bool active_default_ = false;
  bool activate_init_ = false;
  bool enabled_ = false;
  bool redalert_ = false;
  bool variable_size_ = false;
  blender::ui::LayoutAlign alignment_ = {};
  blender::ui::EmbossType emboss_ = {};
  float units_[2] = {0.0f, 0.0f};
  float search_weight_ = 0.0f;
 
 public:
  uiLayout(blender::ui::ItemType type, uiLayoutRoot *root);
 
  [[nodiscard]] bool active() const;
  void active_set(bool active);
 
  [[nodiscard]] bool active_default() const;
  void active_default_set(bool active_default);
 
  [[nodiscard]] bool activate_init() const;
  void activate_init_set(bool activate_init);
 
  [[nodiscard]] blender::ui::LayoutAlign alignment() const;
  void alignment_set(blender::ui::LayoutAlign alignment);
 
  [[nodiscard]] uiBlock *block() const;
 
  void context_copy(const bContextStore *context);
 
  [[nodiscard]] const PointerRNA *context_ptr_get(const blender::StringRef name,
                                                  const StructRNA *type) const;
  void context_ptr_set(blender::StringRef name, const PointerRNA *ptr);
 
  [[nodiscard]] std::optional<blender::StringRefNull> context_string_get(
      const blender::StringRef name) const;
  void context_string_set(blender::StringRef name, blender::StringRef value);
 
  [[nodiscard]] std::optional<int64_t> context_int_get(const blender::StringRef name) const;
  void context_int_set(blender::StringRef name, int64_t value);

  void context_set_from_but(const uiBut *but);
 
  [[nodiscard]] bContextStore *context_store() const;
 
  [[nodiscard]] bool enabled() const;
  void enabled_set(bool enabled);
 
  [[nodiscard]] blender::ui::EmbossType emboss() const;
  void emboss_set(blender::ui::EmbossType emboss);
 
  [[nodiscard]] blender::ui::LayoutDirection local_direction() const;
 
  [[nodiscard]] blender::wm::OpCallContext operator_context() const;
  void operator_context_set(blender::wm::OpCallContext opcontext);
 
  [[nodiscard]] bool red_alert() const;
  void red_alert_set(bool red_alert);
 
  [[nodiscard]] Panel *root_panel() const;
 
  [[nodiscard]] float scale_x() const;
  void scale_x_set(float scale);
 
  [[nodiscard]] float scale_y() const;
  void scale_y_set(float scale);
 
  [[nodiscard]] float search_weight() const;
  void search_weight_set(float weight);
 
  [[nodiscard]] float ui_units_x() const;
  void ui_units_x_set(float width);
 
  [[nodiscard]] float ui_units_y() const;
  void ui_units_y_set(float height);
 
  [[nodiscard]] bool use_property_split() const;
  void use_property_split_set(bool value);
 
  [[nodiscard]] bool use_property_decorate() const;
  void use_property_decorate_set(bool is_sep);
 
  [[nodiscard]] int width() const;

 
  uiLayout &absolute(bool align);
  uiBlock *absolute_block();

  uiLayout &box();
  uiLayout &column(bool align);
  uiLayout &column(bool align, blender::StringRef heading);

  uiLayout &row(bool align);
  uiLayout &row(bool align, blender::StringRef heading);

  uiLayout &column_flow(int number, bool align);
  uiLayout &grid_flow(
      bool row_major, int columns_len, bool even_columns, bool even_rows, bool align);

  uiLayout &list_box(uiList *ui_list, PointerRNA *actptr, PropertyRNA *actprop);

  uiLayout &menu_pie();

  uiLayout &overlap();

  PanelLayout panel_prop(const bContext *C,
                         PointerRNA *open_prop_owner,
                         blender::StringRefNull open_prop_name);
  uiLayout *panel_prop(const bContext *C,
                       PointerRNA *open_prop_owner,
                       blender::StringRefNull open_prop_name,
                       blender::StringRef label);
  PanelLayout panel_prop_with_bool_header(const bContext *C,
                                          PointerRNA *open_prop_owner,
                                          blender::StringRefNull open_prop_name,
                                          PointerRNA *bool_prop_owner,
                                          blender::StringRefNull bool_prop_name,
                                          std::optional<blender::StringRef> label);
  PanelLayout panel(const bContext *C, blender::StringRef idname, bool default_closed);

  uiLayout *panel(const bContext *C,
                  blender::StringRef idname,
                  bool default_closed,
                  blender::StringRef label);

  uiLayout &split(float percentage, bool align);


  void decorator(PointerRNA *ptr, PropertyRNA *prop, int index);
  void decorator(PointerRNA *ptr, std::optional<blender::StringRefNull> propname, int index);

  void label(blender::StringRef name, int icon);

  void menu(MenuType *mt, std::optional<blender::StringRef> name, int icon);
  void menu(blender::StringRef menuname, std::optional<blender::StringRef> name, int icon);

  void menu_contents(blender::StringRef menuname);

  void menu_fn(blender::StringRefNull name, int icon, uiMenuCreateFunc func, void *arg);
  void menu_fn_argN_free(blender::StringRefNull name, int icon, uiMenuCreateFunc func, void *argN);
  PointerRNA op(wmOperatorType *ot,
                std::optional<blender::StringRef> name,
                int icon,
                blender::wm::OpCallContext context,
                eUI_Item_Flag flag);

  PointerRNA op(wmOperatorType *ot, std::optional<blender::StringRef> name, int icon);

  PointerRNA op(blender::StringRefNull opname, std::optional<blender::StringRef> name, int icon);

  PointerRNA op(blender::StringRefNull opname,
                std::optional<blender::StringRef> name,
                int icon,
                blender::wm::OpCallContext context,
                eUI_Item_Flag flag);
  void op_enum(blender::StringRefNull opname,
               blender::StringRefNull propname,
               IDProperty *properties,
               blender::wm::OpCallContext context,
               eUI_Item_Flag flag,
               const int active = -1);

  void op_enum(blender::StringRefNull opname, blender::StringRefNull propname);
  void op_enum_items(wmOperatorType *ot,
                     const PointerRNA &ptr,
                     PropertyRNA *prop,
                     IDProperty *properties,
                     blender::wm::OpCallContext context,
                     eUI_Item_Flag flag,
                     const EnumPropertyItem *item_array,
                     int totitem,
                     int active = -1);

  PointerRNA op_menu_enum(const bContext *C,
                          wmOperatorType *ot,
                          blender::StringRefNull propname,
                          std::optional<blender::StringRefNull> name,
                          int icon);
  PointerRNA op_menu_enum(const bContext *C,
                          blender::StringRefNull opname,
                          blender::StringRefNull propname,
                          blender::StringRefNull name,
                          int icon);
  PointerRNA op_menu_hold(wmOperatorType *ot,
                          std::optional<blender::StringRef> name,
                          int icon,
                          blender::wm::OpCallContext context,
                          eUI_Item_Flag flag,
                          const char *menu_id);
 
  void progress_indicator(const char *text,
                          float factor,
                          blender::ui::ButProgressType progress_type);

  void prop(PointerRNA *ptr,
            PropertyRNA *prop,
            int index,
            int value,
            eUI_Item_Flag flag,
            std::optional<blender::StringRef> name_opt,
            int icon,
            std::optional<blender::StringRef> placeholder = std::nullopt);
  void prop(PointerRNA *ptr,
            blender::StringRefNull propname,
            eUI_Item_Flag flag,
            std::optional<blender::StringRef> name,
            int icon);
 
  void popover(const bContext *C,
               PanelType *pt,
               std::optional<blender::StringRef> name_opt,
               int icon);
  void popover(const bContext *C,
               blender::StringRef panel_type,
               std::optional<blender::StringRef> name_opt,
               int icon);
  void popover_group(
      bContext *C, int space_id, int region_id, const char *context, const char *category);

  void prop_enum(PointerRNA *ptr,
                 PropertyRNA *prop,
                 int value,
                 std::optional<blender::StringRefNull> name,
                 int icon);
  void prop_enum(PointerRNA *ptr,
                 PropertyRNA *prop,
                 const char *value,
                 std::optional<blender::StringRefNull> name,
                 int icon);
  void prop_enum(PointerRNA *ptr,
                 blender::StringRefNull propname,
                 const char *value,
                 std::optional<blender::StringRefNull> name,
                 int icon);

  void prop_menu_enum(PointerRNA *ptr,
                      PropertyRNA *prop,
                      std::optional<blender::StringRefNull> name,
                      int icon);

  void prop_tabs_enum(bContext *C,
                      PointerRNA *ptr,
                      PropertyRNA *prop,
                      PointerRNA *ptr_highlight,
                      PropertyRNA *prop_highlight,
                      bool icon_only);

  void props_enum(PointerRNA *ptr, blender::StringRefNull propname);

  void prop_search(PointerRNA *ptr,
                   PropertyRNA *prop,
                   PointerRNA *searchptr,
                   PropertyRNA *searchprop,
                   PropertyRNA *item_searchpropname,
                   std::optional<blender::StringRefNull> name,
                   int icon,
                   bool results_are_suggestions);
  void prop_search(PointerRNA *ptr,
                   blender::StringRefNull propname,
                   PointerRNA *searchptr,
                   blender::StringRefNull searchpropname,
                   std::optional<blender::StringRefNull> name,
                   int icon);

  void prop_with_popover(PointerRNA *ptr,
                         PropertyRNA *prop,
                         int index,
                         int value,
                         eUI_Item_Flag flag,
                         std::optional<blender::StringRefNull> name,
                         int icon,
                         const char *panel_type);

  void prop_with_menu(PointerRNA *ptr,
                      PropertyRNA *prop,
                      int index,
                      int value,
                      eUI_Item_Flag flag,
                      std::optional<blender::StringRefNull> name,
                      int icon,
                      const char *menu_type);

  uiBut *button(blender::StringRef name,
                int icon,
                std::function<void(bContext &)> func,
                std::optional<blender::StringRef> tooltip = std::nullopt);

  void separator(float factor = 1.0f, LayoutSeparatorType type = LayoutSeparatorType::Auto);

  void separator_spacer();
 
  friend struct blender::ui::LayoutInternal;
 
  [[nodiscard]] uiLayoutRoot *root() const;
  [[nodiscard]] const bContextStore *context() const;
  [[nodiscard]] uiLayout *parent() const;
  [[nodiscard]] blender::StringRef heading() const;
  void heading_reset();
  [[nodiscard]] blender::Span<uiItem *> items() const;
  [[nodiscard]] bool align() const;
  [[nodiscard]] bool variable_size() const;
  [[nodiscard]] blender::ui::EmbossType emboss_or_undefined() const;
 
 protected:
  void estimate();
  virtual void estimate_impl();
  void resolve();
  virtual void resolve_impl();
};
 
inline bool uiLayout::active() const
{
  return active_;
}
inline void uiLayout::active_set(bool active)
{
  active_ = active;
}
 
inline bool uiLayout::active_default() const
{
  return active_default_;
}
inline void uiLayout::active_default_set(bool active_default)
{
  active_default_ = active_default;
}
 
inline bool uiLayout::activate_init() const
{
  return activate_init_;
}
inline void uiLayout::activate_init_set(bool activate_init)
{
  activate_init_ = activate_init;
}
 
inline blender::ui::LayoutAlign uiLayout::alignment() const
{
  return alignment_;
}
 
inline void uiLayout::alignment_set(blender::ui::LayoutAlign alignment)
{
  alignment_ = alignment;
}
 
inline bContextStore *uiLayout::context_store() const
{
  return context_;
}
 
inline bool uiLayout::enabled() const
{
  return enabled_;
}
inline void uiLayout::enabled_set(bool enabled)
{
  enabled_ = enabled;
}
 
inline bool uiLayout::red_alert() const
{
  return redalert_;
}
inline void uiLayout::red_alert_set(bool red_alert)
{
  redalert_ = red_alert;
}
 
inline float uiLayout::search_weight() const
{
  return search_weight_;
}
inline void uiLayout::search_weight_set(float weight)
{
  search_weight_ = weight;
}
 
inline float uiLayout::scale_x() const
{
  return scale_[0];
};
inline void uiLayout::scale_x_set(float scale)
{
  scale_[0] = scale;
};
 
inline float uiLayout::scale_y() const
{
  return scale_[1];
};
inline void uiLayout::scale_y_set(float scale)
{
  scale_[1] = scale;
};
 
inline float uiLayout::ui_units_x() const
{
  return units_[0];
};
inline void uiLayout::ui_units_x_set(float width)
{
  units_[0] = width;
};
 
inline float uiLayout::ui_units_y() const
{
  return units_[1];
};
inline void uiLayout::ui_units_y_set(float height)
{
  units_[1] = height;
};
 
inline int uiLayout::width() const
{
  return this->w_;
}
 
namespace blender::ui {
enum class LayoutDirection : int8_t {
  Horizontal = 0,
  Vertical = 1,
};
 
enum class LayoutType : int8_t {
  Panel = 0,
  Header = 1,
  Menu = 2,
  Toolbar = 3,
  PieMenu = 4,
  VerticalBar = 5,
};
 
enum class LayoutAlign : int8_t {
  Expand = 0,
  Left = 1,
  Center = 2,
  Right = 3,
};
enum class ButProgressType : int8_t {
  Bar = 0,
  Ring = 1,
};
 
uiLayout &block_layout(uiBlock *block,
                       LayoutDirection direction,
                       LayoutType type,
                       int x,
                       int y,
                       int size,
                       int em,
                       int padding,
                       const uiStyle *style);
int2 block_layout_resolve(uiBlock *block);
 
void block_layout_set_current(uiBlock *block, uiLayout *layout);
bool block_layout_needs_resolving(const uiBlock *block);
void block_layout_free(uiBlock *block);
 
}  // namespace blender::ui
 
enum eUI_Item_Flag : uint16_t {
  /* UI_ITEM_O_RETURN_PROPS = 1 << 0, */ /* UNUSED */
  UI_ITEM_R_EXPAND = 1 << 1,
  UI_ITEM_R_SLIDER = 1 << 2,
  UI_ITEM_R_TOGGLE = 1 << 3,
  UI_ITEM_R_ICON_NEVER = 1 << 4,
  UI_ITEM_R_ICON_ONLY = 1 << 5,
  UI_ITEM_R_EVENT = 1 << 6,
  UI_ITEM_R_FULL_EVENT = 1 << 7,
  UI_ITEM_R_NO_BG = 1 << 8,
  UI_ITEM_R_IMMEDIATE = 1 << 9,
  UI_ITEM_O_DEPRESS = 1 << 10,
  UI_ITEM_R_COMPACT = 1 << 11,
  UI_ITEM_R_CHECKBOX_INVERT = 1 << 12,
  UI_ITEM_R_FORCE_BLANK_DECORATE = 1 << 13,
  /* Even create the property split layout if there's no name to show there. */
  UI_ITEM_R_SPLIT_EMPTY_NAME = 1 << 14,
  UI_ITEM_R_TEXT_BUT_FORCE_SEMI_MODAL_ACTIVE = 1 << 15,
};
ENUM_OPERATORS(eUI_Item_Flag, UI_ITEM_R_TEXT_BUT_FORCE_SEMI_MODAL_ACTIVE)
#define UI_ITEM_NONE eUI_Item_Flag(0)

bool UI_block_apply_search_filter(uiBlock *block, const char *search_filter);
 
void uiLayoutSetFunc(uiLayout *layout, uiMenuHandleFunc handlefunc, void *argv);

void uiLayoutSetTooltipFunc(uiLayout *layout,
                            uiButToolTipFunc func,
                            void *arg,
                            uiCopyArgFunc copy_arg,
                            uiFreeArgFunc free_arg);

void uiLayoutSetTooltipCustomFunc(uiLayout *layout,
                                  uiButToolTipCustomFunc func,
                                  void *arg,
                                  uiCopyArgFunc copy_arg,
                                  uiFreeArgFunc free_arg);
 
void UI_menutype_draw(bContext *C, MenuType *mt, uiLayout *layout);

void UI_paneltype_draw(bContext *C, PanelType *pt, uiLayout *layout);
 
int uiLayoutListItemPaddingWidth();
void uiLayoutListItemAddPadding(uiLayout *layout);
 
/* Layout create functions. */
 
bool uiLayoutEndsWithPanelHeader(const uiLayout &layout);
 
struct uiPropertySplitWrapper {
  uiLayout *label_column;
  uiLayout *property_row;
  uiLayout *decorate_column;
};

uiPropertySplitWrapper uiItemPropertySplitWrapperCreate(uiLayout *parent_layout);
 
uiBut *uiItemL_ex(
    uiLayout *layout, blender::StringRef name, int icon, bool highlight, bool redalert);
uiLayout *uiItemL_respect_property_split(uiLayout *layout, blender::StringRef text, int icon);
void uiItemLDrag(uiLayout *layout, PointerRNA *ptr, blender::StringRef name, int icon);
 
/* Only for testing, inspecting layouts. */
const char *UI_layout_introspect(uiLayout *layout);

uiLayout *uiItemsAlertBox(uiBlock *block,
                          const uiStyle *style,
                          const int dialog_width,
                          const eAlertIcon icon,
                          const int icon_size);
uiLayout *uiItemsAlertBox(uiBlock *block, const int size, const eAlertIcon icon);