UI / XBase - GTAMODX开发文档

include/XBase/UI.h · XBase::UI

UI 模块在 ImGui 之上提供窗口管理器、Tab 系统、MenuSurface 列表菜单和常用组件封装。宿主只包含 XBase 公共头，不直接引用 ImGui。

生命周期

void Init(const std::string& title = "XBase");
void Process();
void Shutdown();

Init() 通过 Hooks::RegisterDrawCallback() 注册绘制循环，失败时记录错误并保持未初始化。
Process() 为空实现：所有 ImGui 声明只在渲染钩子内执行。
Shutdown() 注销绘制回调并清空窗口、Tab 与 MenuSurface 状态。

窗口管理

void AddWindow(const std::string& name, DrawFn drawFn, bool defaultOpen = false, WindowFlags flags = 0);
void RemoveWindow(const std::string& name);
void SetWindowVisible(const std::string& name, bool visible);
bool IsWindowVisible(const std::string& name);
void ToggleWindow(const std::string& name);

void SetNextWindowPosition(Vec2 position, bool always = false);
void SetNextWindowSize(Vec2 size, bool firstUseOnly = false);
void SetNextWindowBackgroundAlpha(float alpha);

窗口标志使用值类型 WindowFlag 与 Flag() 组合：

XBase::UI::Window("main", "我的菜单", drawFn,
    nullptr, XBase::UI::Flag(XBase::UI::WindowFlag::NoCollapse));

容器与分组

void Window(const char* id, const char* title, const DrawFn& drawFn, bool* open = nullptr, WindowFlags flags = 0);
void Child(const char* id, const DrawFn& drawFn, Vec2 size = {}, bool border = false);
void ChildNoScroll(const char* id, const DrawFn& drawFn, Vec2 size = {}, bool border = false);
void Disabled(bool disabled, const DrawFn& drawFn);
void Indented(const DrawFn& drawFn, float width = 0.0f);
void Group(const char* label, const DrawFn& drawFn, Vec2 size = {});
void Tree(const char* label, const DrawFn& drawFn, bool defaultOpen = false);
void OpenModal(const char* id);
void Modal(const char* id, const DrawFn& drawFn, Vec2 size = {}, bool autoResize = false);
void CloseModal();

表格

struct TableColumn {
    const char* label = "";
    float weight = 1.0f;
};

void Table(const char* id, const TableColumn* columns, std::size_t columnCount, const DrawFn& drawFn, Vec2 size = {});
void TableNextRow();
void TableNextCell();

Tab 系统

void Tabs(const char* id, const DrawFn& drawFn);
void Tab(const char* id, const char* label, const DrawFn& drawFn);

void BeginTabBar(const std::string& name);
void AddTab(const std::string& label, DrawFn drawFn);
bool RenderTabBar(float height = 0.0f);
void EndTabBar();

Tabs / Tab 是作用域式写法，菜单页面优先使用；BeginTabBar 系列用于需要独立控制渲染时机的场景。

MenuSurface 列表菜单

struct MenuSurfaceState {
    int selectedIndex = 0;
    int itemCount = 0;
};

struct MenuSurfaceResult {
    bool backRequested = false;
    bool selectionCanAdjust = false;
};

MenuSurfaceResult MenuSurface(
    const char* id,
    const char* title,
    const char* subtitle,
    MenuSurfaceState& state,
    bool allowMouse,
    bool showBackHint,
    const DrawFn& drawFn);

bool MenuSurfaceButton(const char* label);
bool MenuSurfaceCheckbox(const char* label, bool& value);
bool MenuSurfaceCollapsingSection(const char* label, bool& open);
bool MenuSurfaceSlider(const char* label, float& value, float minValue, float maxValue, const char* format = "%.1f");
bool MenuSurfaceSlider(const char* label, int& value, int minValue, int maxValue);
bool MenuSurfaceInput(const char* label, float& value, float step = 1.0f, float fastStep = 10.0f, const char* format = "%.1f");
bool MenuSurfaceInput(const char* label, int& value, int step = 1, int fastStep = 10);
void MenuSurfaceSection(const char* label);

导航、滚动、指针命中和视觉反馈由 XBase 持有；state 只保存宿主侧持久选中项。
MenuSurfaceInput 按 step 调整，按住 Shift 时使用 fastStep；MenuSurfaceSlider 按量程自动选择步长。
MenuSurfaceResult::backRequested 表示玩家请求返回上一级，由宿主决定页面切换。

基础控件

bool Button(const char* label, Vec2 size = {});
bool StyledButton(const char* label, Vec2 size = {});
void BeginGroupBox(const char* label, Vec2 size = {});
void EndGroupBox();
bool Checkbox(const char* label, bool& value);
bool Choice(const char* label, int& selectedValue, int value);
bool Slider(const char* label, float& value, float minValue, float maxValue, const char* format = "%.1f");
bool Slider(const char* label, int& value, int minValue, int maxValue);
bool Input(const char* label, float& value, float step = 1.0f, float fastStep = 10.0f, const char* format = "%.1f");
bool Input(const char* label, int& value, int step = 1, int fastStep = 10);
bool InputText(const char* label, char* value, std::size_t capacity, const char* hint = nullptr, bool readOnly = false, bool submitOnEnter = false);
bool InputTextMultiline(const char* label, char* value, std::size_t capacity, Vec2 size = {}, bool readOnly = false);
bool Selectable(const char* label, bool selected = false, Vec2 size = {});
bool SelectableCentered(const char* label, bool selected = false, Vec2 size = {});
void Combo(const char* label, const char* preview, const DrawFn& drawFn);
bool MenuItem(const char* label, bool selected = false, bool enabled = true);
bool CollapsingHeader(const char* label, bool defaultOpen = false);
bool CollapsingSection(const char* label, bool& open);
bool InvisibleButton(const char* id, Vec2 size);
void SetClipboardText(const char* text);
void FocusLastItemByDefault();

文本与布局

void Text(const char* text);
void TextWrapped(const char* text);
void TextDisabled(const char* text);
void Spacing();
void Separator();
void SeparatorText(const char* label);
void CenterText(const char* text);
void Tooltip(const char* text);
void HelpMarker(const char* desc, bool* hold = nullptr);
float GetFrameRate();

void SameLine();
void Columns(int count, const char* id = nullptr, bool border = false);
void NextColumn();
void PushItemWidth(float width);
void PopItemWidth();
Vec2 GridItemSize(int columns = 1, bool includeSpacing = true);

Text、TextWrapped、TextDisabled 提供 const char*、int、float 混合重载，用于格式化显示。

鼠标与光标

bool IsLastItemHovered();
bool IsMouseDown(MouseButton button);
Vec2 GetMousePosition();
Vec2 GetCursorScreenPosition();
void SetCursorScreenPos(Vec2 position);
Vec2 GetContentAvailable();
Vec2 GetDisplaySize();

Canvas 绘图

namespace Canvas {
void Line(Vec2 from, Vec2 to, Color color, float thickness = 1.0f);
void Rect(Vec2 min, Vec2 max, Color color, float thickness = 1.0f);
void RectFilled(Vec2 min, Vec2 max, Color color);
void Circle(Vec2 center, float radius, Color color, float thickness = 1.0f);
void CircleFilled(Vec2 center, float radius, Color color);
void Arc(Vec2 center, float radius, float startAngle, float endAngle, Color color, float thickness = 1.0f);
void Polyline(const Vec2* points, std::size_t count, Color color, float thickness = 1.0f);
void Text(Vec2 position, Color color, const char* text);
}

通知 / Toast

struct NotificationSpec {
    const char* message = "";
    float duration = 3.0f;
    Color color = {};
};

void Notify(NotificationSpec spec);
void RenderNotifications(Vec2 screenPosition = {});

Notify — 排队一条 Toast 消息
RenderNotifications — 在背景绘制层渲染所有活跃 Toast（可选屏幕位置，默认左上角）

UI

On this page