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 <optional>
 
#include "BLI_string_ref.hh"
#include "BLI_vector.hh"
 
#include "UI_interface_icons.hh" /* `eAlertIcon` */
#include "UI_interface_types.hh"
 
#include "WM_types.hh" /* `wmOperatorCallContext` */
 
struct bContext;
struct bContextStore;
struct uiBlock;
struct uiBut;
struct uiLayoutRoot;
struct uiStyle;
struct MenuType;
struct PanelType;
struct PointerRNA;
 
/* 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;
}  // namespace blender::ui
 
struct PanelLayout {
  uiLayout *header;
  uiLayout *body;
};

struct uiItem {
  blender::ui::ItemType type_;
  blender::ui::ItemInternalFlag flag_;
 
  uiItem() = default;
  uiItem(const uiItem &) = default;
  virtual ~uiItem() = default;
};
 
enum eUI_Item_Flag : uint16_t;
 
enum class LayoutSeparatorType : int8_t {
  Auto,
  Space,
  Line,
};

struct uiLayout : uiItem {
  // protected:
  uiLayoutRoot *root_;
  bContextStore *context_;
  uiLayout *parent_;
  blender::Vector<uiItem *> items_;
 
  char heading_[UI_MAX_NAME_STR];

  uiLayout *child_items_layout_;
 
  int x_, y_, w_, h_;
  float scale_[2];
  short space_;
  bool align_;
  bool active_;
  bool active_default_;
  bool activate_init_;
  bool enabled_;
  bool redalert_;
  bool keepaspect_;
  bool variable_size_;
  char alignment_;
  blender::ui::EmbossType emboss_;
  float units_[2];
  float search_weight_;
 
 public:
  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::StringRefNull> 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 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_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,
                wmOperatorCallContext 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,
                wmOperatorCallContext context,
                eUI_Item_Flag flag);
  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 separator(float factor = 1.0f, LayoutSeparatorType type = LayoutSeparatorType::Auto);
};
 
enum {
  UI_LAYOUT_HORIZONTAL = 0,
  UI_LAYOUT_VERTICAL = 1,
};
 
enum {
  UI_LAYOUT_PANEL = 0,
  UI_LAYOUT_HEADER = 1,
  UI_LAYOUT_MENU = 2,
  UI_LAYOUT_TOOLBAR = 3,
  UI_LAYOUT_PIEMENU = 4,
  UI_LAYOUT_VERT_BAR = 5,
};
 
enum {
  UI_LAYOUT_ALIGN_EXPAND = 0,
  UI_LAYOUT_ALIGN_LEFT = 1,
  UI_LAYOUT_ALIGN_CENTER = 2,
  UI_LAYOUT_ALIGN_RIGHT = 3,
};
 
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)
 
uiLayout *UI_block_layout(uiBlock *block,
                          int dir,
                          int type,
                          int x,
                          int y,
                          int size,
                          int em,
                          int padding,
                          const uiStyle *style);
void UI_block_layout_set_current(uiBlock *block, uiLayout *layout);
void UI_block_layout_resolve(uiBlock *block, int *r_x, int *r_y);
bool UI_block_layout_needs_resolving(const uiBlock *block);
void UI_block_layout_free(uiBlock *block);

bool UI_block_apply_search_filter(uiBlock *block, const char *search_filter);
 
uiBlock *uiLayoutGetBlock(uiLayout *layout);
 
void uiLayoutSetFunc(uiLayout *layout, uiMenuHandleFunc handlefunc, void *argv);
void uiLayoutSetContextPointer(uiLayout *layout, blender::StringRef name, PointerRNA *ptr);
void uiLayoutSetContextString(uiLayout *layout, blender::StringRef name, blender::StringRef value);
void uiLayoutSetContextInt(uiLayout *layout, blender::StringRef name, int64_t value);
bContextStore *uiLayoutGetContextStore(uiLayout *layout);
void uiLayoutContextCopy(uiLayout *layout, const bContextStore *context);

void uiLayoutSetTooltipFunc(uiLayout *layout,
                            uiButToolTipFunc 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);
 
/* Only for convenience. */
void uiLayoutSetContextFromBut(uiLayout *layout, uiBut *but);
 
void uiLayoutSetOperatorContext(uiLayout *layout, wmOperatorCallContext opcontext);
void uiLayoutSetActive(uiLayout *layout, bool active);
void uiLayoutSetActiveDefault(uiLayout *layout, bool active_default);
void uiLayoutSetActivateInit(uiLayout *layout, bool activate_init);
void uiLayoutSetEnabled(uiLayout *layout, bool enabled);
void uiLayoutSetRedAlert(uiLayout *layout, bool redalert);
void uiLayoutSetAlignment(uiLayout *layout, char alignment);
void uiLayoutSetFixedSize(uiLayout *layout, bool fixed_size);
void uiLayoutSetKeepAspect(uiLayout *layout, bool keepaspect);
void uiLayoutSetScaleX(uiLayout *layout, float scale);
void uiLayoutSetScaleY(uiLayout *layout, float scale);
void uiLayoutSetUnitsX(uiLayout *layout, float unit);
void uiLayoutSetUnitsY(uiLayout *layout, float unit);
void uiLayoutSetEmboss(uiLayout *layout, blender::ui::EmbossType emboss);
void uiLayoutSetPropSep(uiLayout *layout, bool is_sep);
void uiLayoutSetPropDecorate(uiLayout *layout, bool is_sep);
int uiLayoutGetLocalDir(const uiLayout *layout);
void uiLayoutSetSearchWeight(uiLayout *layout, float weight);
 
wmOperatorCallContext uiLayoutGetOperatorContext(uiLayout *layout);
bool uiLayoutGetActive(uiLayout *layout);
bool uiLayoutGetActiveDefault(uiLayout *layout);
bool uiLayoutGetActivateInit(uiLayout *layout);
bool uiLayoutGetEnabled(uiLayout *layout);
bool uiLayoutGetRedAlert(uiLayout *layout);
int uiLayoutGetAlignment(uiLayout *layout);
bool uiLayoutGetFixedSize(uiLayout *layout);
bool uiLayoutGetKeepAspect(uiLayout *layout);
int uiLayoutGetWidth(uiLayout *layout);
float uiLayoutGetScaleX(uiLayout *layout);
float uiLayoutGetScaleY(uiLayout *layout);
float uiLayoutGetUnitsX(uiLayout *layout);
float uiLayoutGetUnitsY(uiLayout *layout);
blender::ui::EmbossType uiLayoutGetEmboss(uiLayout *layout);
bool uiLayoutGetPropSep(uiLayout *layout);
bool uiLayoutGetPropDecorate(uiLayout *layout);
Panel *uiLayoutGetRootPanel(uiLayout *layout);
float uiLayoutGetSearchWeight(uiLayout *layout);
 
int uiLayoutListItemPaddingWidth();
void uiLayoutListItemAddPadding(uiLayout *layout);
 
/* Layout create functions. */
 
bool uiLayoutEndsWithPanelHeader(const uiLayout &layout);
 
/* items */
 
void uiItemEnumO_ptr(uiLayout *layout,
                     wmOperatorType *ot,
                     std::optional<blender::StringRef> name,
                     int icon,
                     blender::StringRefNull propname,
                     int value);
void uiItemEnumO(uiLayout *layout,
                 blender::StringRefNull opname,
                 std::optional<blender::StringRef> name,
                 int icon,
                 blender::StringRefNull propname,
                 int value);
void uiItemEnumO_value(uiLayout *layout,
                       blender::StringRefNull name,
                       int icon,
                       blender::StringRefNull opname,
                       blender::StringRefNull propname,
                       int value);
void uiItemEnumO_string(uiLayout *layout,
                        blender::StringRef name,
                        int icon,
                        blender::StringRefNull opname,
                        blender::StringRefNull propname,
                        const char *value_str);
void uiItemsEnumO(uiLayout *layout,
                  blender::StringRefNull opname,
                  blender::StringRefNull propname);
 
void uiItemFullOMenuHold_ptr(uiLayout *layout,
                             wmOperatorType *ot,
                             std::optional<blender::StringRef> name,
                             int icon,
                             wmOperatorCallContext context,
                             eUI_Item_Flag flag,
                             const char *menu_id, /* extra menu arg. */
                             PointerRNA *r_opptr);

void uiItemFullR_with_popover(uiLayout *layout,
                              PointerRNA *ptr,
                              PropertyRNA *prop,
                              int index,
                              int value,
                              eUI_Item_Flag flag,
                              std::optional<blender::StringRefNull> name,
                              int icon,
                              const char *panel_type);
void uiItemFullR_with_menu(uiLayout *layout,
                           PointerRNA *ptr,
                           PropertyRNA *prop,
                           int index,
                           int value,
                           eUI_Item_Flag flag,
                           std::optional<blender::StringRefNull> name,
                           int icon,
                           const char *menu_type);
void uiItemEnumR_prop(uiLayout *layout,
                      std::optional<blender::StringRefNull> name,
                      int icon,
                      PointerRNA *ptr,
                      PropertyRNA *prop,
                      int value);
void uiItemEnumR_string_prop(uiLayout *layout,
                             PointerRNA *ptr,
                             PropertyRNA *prop,
                             const char *value,
                             std::optional<blender::StringRefNull> name,
                             int icon);
void uiItemEnumR_string(uiLayout *layout,
                        PointerRNA *ptr,
                        blender::StringRefNull propname,
                        const char *value,
                        std::optional<blender::StringRefNull> name,
                        int icon);
void uiItemsEnumR(uiLayout *layout, PointerRNA *ptr, blender::StringRefNull propname);
void uiItemPointerR_prop(uiLayout *layout,
                         PointerRNA *ptr,
                         PropertyRNA *prop,
                         PointerRNA *searchptr,
                         PropertyRNA *searchprop,
                         std::optional<blender::StringRefNull> name,
                         int icon,
                         bool results_are_suggestions);
void uiItemPointerR(uiLayout *layout,
                    PointerRNA *ptr,
                    blender::StringRefNull propname,
                    PointerRNA *searchptr,
                    blender::StringRefNull searchpropname,
                    std::optional<blender::StringRefNull> name,
                    int icon);

void uiItemsFullEnumO(uiLayout *layout,
                      blender::StringRefNull opname,
                      blender::StringRefNull propname,
                      IDProperty *properties,
                      wmOperatorCallContext context,
                      eUI_Item_Flag flag,
                      const int active = -1);
void uiItemsFullEnumO_items(uiLayout *layout,
                            wmOperatorType *ot,
                            const PointerRNA &ptr,
                            PropertyRNA *prop,
                            IDProperty *properties,
                            wmOperatorCallContext context,
                            eUI_Item_Flag flag,
                            const EnumPropertyItem *item_array,
                            int totitem,
                            int active = -1);
 
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);
void uiItemMContents(uiLayout *layout, blender::StringRef menuname);
 
/* Decorators. */

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

void uiItemSpacer(uiLayout *layout);
 
enum eButProgressType {
  UI_BUT_PROGRESS_TYPE_BAR = 0,
  UI_BUT_PROGRESS_TYPE_RING = 1,
};
 
void uiItemProgressIndicator(uiLayout *layout,
                             const char *text,
                             float factor,
                             eButProgressType progress_type);
 
/* popover */
void uiItemPopoverPanel_ptr(uiLayout *layout,
                            const bContext *C,
                            PanelType *pt,
                            std::optional<blender::StringRef> name_opt,
                            int icon);
void uiItemPopoverPanel(uiLayout *layout,
                        const bContext *C,
                        blender::StringRef panel_type,
                        std::optional<blender::StringRef> name_opt,
                        int icon);
void uiItemPopoverPanelFromGroup(uiLayout *layout,
                                 bContext *C,
                                 int space_id,
                                 int region_id,
                                 const char *context,
                                 const char *category);

void uiItemMenuEnumFullO_ptr(uiLayout *layout,
                             const bContext *C,
                             wmOperatorType *ot,
                             blender::StringRefNull propname,
                             std::optional<blender::StringRefNull> name,
                             int icon,
                             PointerRNA *r_opptr);
void uiItemMenuEnumFullO(uiLayout *layout,
                         const bContext *C,
                         blender::StringRefNull opname,
                         blender::StringRefNull propname,
                         blender::StringRefNull name,
                         int icon,
                         PointerRNA *r_opptr);
void uiItemMenuEnumO(uiLayout *layout,
                     const bContext *C,
                     blender::StringRefNull opname,
                     blender::StringRefNull propname,
                     blender::StringRefNull name,
                     int icon);
void uiItemMenuEnumR_prop(uiLayout *layout,
                          PointerRNA *ptr,
                          PropertyRNA *prop,
                          std::optional<blender::StringRefNull>,
                          int icon);
void uiItemTabsEnumR_prop(uiLayout *layout,
                          bContext *C,
                          PointerRNA *ptr,
                          PropertyRNA *prop,
                          PointerRNA *ptr_highlight,
                          PropertyRNA *prop_highlight,
                          bool icon_only);
 
/* 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);