UIHost.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "common/BorrowedRef.h"
#include "common/ECS.h"
#include "ui/Theme.h"
 
#include <cstdint>
#include <functional>
#include <string>
#include <vector>
 
namespace eve::ui {
 
using UIHostHandle = ecs::EntityHandle;
 
enum class NodeType : uint8_t {
    Window = 0,
    Text = 1,
    Button = 2,
    SameLine = 3,
    Group = 4,
    Separator = 5,
    Checkbox = 6,
    Slider = 7,
    Progress = 8,
    InputText = 9,
    CollapsingHeader = 10,
    Child = 11,
    Flex = 12,    // elastic row/column container
    Spacer = 13,  // flexible empty space (default flexGrow=1)
    Image = 14,   // colored rect or engine texture (nine-patch capable)
    ImageButton = 15,  // clickable image
    Combo = 16,   // dropdown; options newline-separated in valueText, index in value
    ScrollList = 17,  // virtualized scrollable list (uniform itemHeight)
    Viewport = 18,  // embedded render target: offscreen Canvas shown + input routed
    SearchField = 19,   // compact input with a search hint/icon
    Switch = 20,        // modern boolean toggle
    Badge = 21,         // compact status/category pill
    Card = 22,          // bordered surface container
    SectionHeader = 23, // non-collapsible editor section heading
    MenuBar = 24,       // native ImGui window menu bar
    Menu = 25,          // popup menu container
    MenuItem = 26,      // selectable menu command
    Toolbar = 27,       // horizontal editor command strip
    Toolbox = 28,       // wrapping grid of editor tools
    Sidebar = 29,       // vertical editor side panel
    StatusBar = 30,     // compact horizontal status strip
    SplitPane = 31,      // two resizable panes
    NinePatchPanel = 32, // .9.png-backed stretchable content container
    ColorPalette = 33,   // color editor + swatch grid; RGBA lives in tint*
    Grid = 34,           // fixed-column retained grid container
};
 
enum class FlexDirection : uint8_t { Row = 0, Column = 1 };
 
enum class FlexWrap : uint8_t { NoWrap = 0, Wrap = 1 };
 
enum class OverflowMode : uint8_t { Visible = 0, Clip = 1, Scroll = 2 };
 
enum class FlexAlign : uint8_t { Start = 0, Center = 1, End = 2, Stretch = 3 };
 
enum class FlexJustify : uint8_t {
    Start = 0,
    Center = 1,
    End = 2,
    SpaceBetween = 3,
    SpaceAround = 4,
};
 
enum class FocusMode : uint8_t { None = 0, Click = 1, All = 2 };
 
enum class FocusDirection : uint8_t { Next = 0, Previous, Left, Right, Up, Down };
 
enum class MouseFilter : uint8_t { Stop = 0, Pass = 1, Ignore = 2 };
 
enum class ThemePreset : uint8_t { Inherit = 0, Dark = 1, Light = 2 };
 
enum class WorldAnchorState : uint8_t {
    Disabled = 0,
    Visible,
    BehindCamera,
    OutsideViewport,
    NoCamera,
    Crowded
};
 
enum class WorldAnchorEdgePolicy : uint8_t { Hide = 0, Clamp };
 
enum class WorldAnchorOverlapPolicy : uint8_t { Allow = 0, Avoid };
 
enum class AccessibilityRole : uint8_t {
    Auto = 0,
    Button,
    Checkbox,
    Slider,
    Text,
    TextInput,
    List,
    ListItem,
    Menu,
    MenuItem,
    Progress,
    Region,
    Tab,
    Window
};
 
struct UINode {
    NodeType type = NodeType::Text;
    std::string id;
    std::string key;
    std::string text;       // label / title
    std::string valueText;  // InputText content
    std::string tooltip;    // hover help; empty disables the tooltip
    bool visible = true;
    bool enabled = true;
    bool checked = false;
    bool open = true;  // CollapsingHeader default-open hint
    FocusMode focusMode = FocusMode::All;
    MouseFilter mouseFilter = MouseFilter::Stop;
    ThemePreset themePreset = ThemePreset::Inherit;
    std::string styleClass;
    StyleClass resolvedStyle;
    bool hasResolvedStyle = false;
    float opacity = 1.f;  // transient visual state; animation never changes persistent style data
    int tabIndex = 0;
    std::string focusNext;
    std::string focusPrevious;
    std::string focusLeft;
    std::string focusRight;
    std::string focusUp;
    std::string focusDown;
    bool focusRequested = false;
    bool focused = false;
    AccessibilityRole accessibilityRole = AccessibilityRole::Auto;
    std::string accessibilityName;
    std::string accessibilityDescription;
    bool dragSource = false;
    bool dropTarget = false;
    std::string dragPayloadType;
    std::string dragPayloadText;
    std::string acceptedDropType;
    float value = 0.f;
    float minValue = 0.f;
    float maxValue = 1.f;
    float sizeX = 0.f;  // Child / item basis width; 0 = auto
    float sizeY = 0.f;  // Child / item basis height; 0 = auto
    // --- Layout box model (input props; 0 = unset) ---
    float marginL = 0.f;
    float marginT = 0.f;
    float marginR = 0.f;
    float marginB = 0.f;
    float paddingL = 0.f;
    float paddingT = 0.f;
    float paddingR = 0.f;
    float paddingB = 0.f;
    float minSizeX = 0.f;  // 0 = auto
    float minSizeY = 0.f;
    float maxSizeX = 0.f;  // 0 = unlimited
    float maxSizeY = 0.f;
    float percentW = 0.f;  // 0..1 fraction of parent content width; overrides basis
    float percentH = 0.f;  // 0..1 fraction of parent content height
    float aspectRatio = 0.f; // width / height; 0 disables ratio-derived sizing
    float anchorX = 0.f;   // absolute placement inside Flex: anchor point in parent (0..1)
    float anchorY = 0.f;
    float posX = 0.f;      // absolute placement offset (relative to anchor edge)
    float posY = 0.f;
    bool absolute = false; // skip flex flow; placed by anchor/pos
    // --- Image / ImageButton props (NodeType::Image*) ---
    uint64_t textureId = 0;  // opaque id from UIBackend::registerTexture; 0 = solid color
    float tintR = 1.f;
    float tintG = 1.f;
    float tintB = 1.f;
    float tintA = 1.f;
    float uv0x = 0.f;  // source rect in texture (UV)
    float uv0y = 0.f;
    float uv1x = 1.f;
    float uv1y = 1.f;
    float borderL = 0.f;  // nine-patch border (px); all 0 = plain image
    float borderT = 0.f;
    float borderR = 0.f;
    float borderB = 0.f;
    float cornerRadius = 0.f;  // solid-color rounded rect radius
    float wrapWidth = 0.f;     // Text wrap width (0 = no wrap)
    float itemHeight = 0.f;    // ScrollList uniform row height (0 = frame height)
    // --- Computed by measure/arrange pass (per frame) ---
    float measuredW = 0.f;
    float measuredH = 0.f;
    // Flex container props (meaningful on NodeType::Flex)
    FlexDirection flexDirection = FlexDirection::Row;
    FlexAlign alignItems = FlexAlign::Start;
    FlexJustify justifyContent = FlexJustify::Start;
    float gap = -1.f;  // <0 → theme ItemSpacing on that axis
    float columnGap = -1.f;
    float rowGap = -1.f;
    FlexWrap flexWrap = FlexWrap::NoWrap;
    OverflowMode overflow = OverflowMode::Visible;
    int gridColumns = 1;
    // Flex item props (any child inside Flex)
    float flexGrow = 0.f;
    float flexShrink = 1.f;
    float flexBasis = -1.f;  // <0 = measured/automatic basis
    int alignSelf = -1;      // <0 = inherit parent alignItems
    int gridColumnSpan = 1;
    float layoutOverflowX = 0.f;
    float layoutOverflowY = 0.f;
    int parent = -1;
    int firstChild = -1;
    int nextSibling = -1;
    uint32_t handlerClick = 0;   // 1-based → Tree::clickHandlers
    uint32_t handlerToggle = 0;  // 1-based → Tree::toggleHandlers
    uint32_t handlerValue = 0;   // 1-based → Tree::valueHandlers
    uint32_t handlerText = 0;    // 1-based → Tree::textHandlers
};
 
struct WidgetDesc;
 
class EVENGINE_API_WORLD UIHost : public ecs::Entity {
public:
    ENTITY(UIHost, ecs::Entity)
 
    
    void release() override {}
 
    struct Meta {
        bool visible = true;
        int layer = 0;
        bool modal = false;
        bool overlay = false;  // no title bar / chrome (HUD-style)
        bool hasPos = false;
        bool lockPos = true;       // false: initial position only; user may move/persist it
        bool  animDrivePos = false;
        float posX = 0.f;
        float posY = 0.f;
        float pivotX = 0.f;
        float pivotY = 0.f;
        bool hasSize = false;      // explicit window size
        bool lockSize = true;      // false: initial size only; user may resize/persist it
        bool         animDriveSize = false;
        float sizeX = 0.f;
        float sizeY = 0.f;
        float percentW = 0.f;      // 0..1 of display width; overrides sizeX
        float percentH = 0.f;      // 0..1 of display height
        float anchorX = 0.f;       // anchor in display (0..1); with hasPos, posX is offset
        float anchorY = 0.f;
        std::string name;
        float overlayBgAlpha = 0.4f;
        bool overlayFlush = false;  // remove outer WindowPadding for desktop chrome
        uint32_t ownerId = 0;
        UIHostHandle entity{};
        bool hasThemeOverride = false;
        Theme themeOverride;
    };
 
    struct Tree {
        bool dirty = true;
        std::vector<UINode> nodes;
        int root = -1;
        std::vector<std::function<void()>> clickHandlers;
        std::vector<std::function<void(bool)>> toggleHandlers;
        std::vector<std::function<void(float)>> valueHandlers;
        std::vector<std::function<void(const std::string &)>> textHandlers;
    };
 
    struct WorldAnchor {
        bool enabled = false;
        float worldX = 0.f;
        float worldY = 0.f;
        float worldZ = 0.f;
        float offsetX = 0.f;
        float offsetY = 0.f;
        float safeMargin = 8.f;
        WorldAnchorEdgePolicy edgePolicy = WorldAnchorEdgePolicy::Hide;
        bool hideBehindCamera = true;
        bool distanceScale = false;
        float referenceDistance = 10.f;
        float minScale = 0.65f;
        float maxScale = 1.25f;
        WorldAnchorOverlapPolicy overlapPolicy = WorldAnchorOverlapPolicy::Allow;
        int overlapPriority = 0;
        float overlapPadding = 4.f;
        float maxDisplacement = 96.f;
 
        WorldAnchorState state = WorldAnchorState::Disabled;
        float screenX = 0.f;
        float screenY = 0.f;
        float depth = 0.f;
        float scale = 1.f;
        float displacementX = 0.f;
        float displacementY = 0.f;
    };
 
    COMPONENT(Meta, meta)
    COMPONENT(Tree, tree)
    COMPONENT(WorldAnchor, worldAnchor)
 
    
    [[nodiscard]] static UIHostHandle createHost(const std::string &name = "");
 
    [[nodiscard]] static eve::OptionalRef<UIHost> resolve(UIHostHandle handle) noexcept;
 
    [[nodiscard]] UIHostHandle handle() const noexcept { return ecs::handle_of(this); }
 
    void setName(const std::string &name);
    const std::string &getName();
    void setThemeOverride(const Theme &theme);
    void clearThemeOverride();
    bool hasThemeOverride();
    [[nodiscard]] const Theme *themeOverride();
    void setOwnerId(uint32_t id) { meta()->ownerId = id; }
    uint32_t getOwnerId() { return meta()->ownerId; }
 
    void setTree(WidgetDesc root);
    bool setTreeReconcile(WidgetDesc root);
 
    void setSimplePanel(const std::string &title, const std::string &labelText,
                        const std::string &buttonText, const std::string &labelId = "label",
                        const std::string &buttonId = "btn");
 
    void setTextById(const std::string &id, const std::string &text);
    void setVisibleById(const std::string &id, bool visible);
    void setEnabledById(const std::string &id, bool enabled);
    void setCheckedById(const std::string &id, bool checked);
    void setValueById(const std::string &id, float value);
    void setValueTextById(const std::string &id, const std::string &value);
    bool setClickHandler(const std::string &id, std::function<void()> fn);
    bool setToggleHandler(const std::string &id, std::function<void(bool)> fn);
    bool setValueHandler(const std::string &id, std::function<void(float)> fn);
    bool setTextHandler(const std::string &id, std::function<void(const std::string &)> fn);
    [[nodiscard]] eve::OptionalRef<UINode> findById(const std::string &id);
    [[nodiscard]] eve::OptionalRef<UINode> findByKey(const std::string &key);
    bool requestFocusById(const std::string &id);
    bool moveFocus(FocusDirection direction, bool wrap = true);
    std::string focusedId();
    void markDirty() { tree()->dirty = true; }
 
    void setVisible(bool v) { meta()->visible = v; }
    void setLayer(int layer) { meta()->layer = layer; }
    void setModal(bool modal) { meta()->modal = modal; }
 
    void setWorldAnchor(float x, float y, float z);
    void clearWorldAnchor();
};
 
}  // namespace eve::ui