PyEUI

PyEUI 是 EUI-NEO C++ GUI 框架的官方 Python 绑定 (Python Bindings)，通过 pybind11 技术将 EUI 的高性能渲染引擎和组件系统完整暴露给 Python 生态，让您能够使用 Python 语言享受高性能的声明式 2D GUI 开发体验。

项目定位

PyEUI 本质上是一个 Python Bindings 项目，它的核心职责是：

• 🔗 桥接 C++ 与 Python: 通过 pybind11 将 EUI-NEO 的 C++ API 映射为 Python 接口
• 🎯 零性能损耗: 底层渲染和布局计算完全由 C++ 引擎执行，Python 仅负责 API 调用
• 🧩 API 一致性: 保持与 EUI-NEO C++ 接口的高度一致性，降低学习成本
• 📦 无缝集成: 作为 EUI 生态的 Python 入口，可直接使用 EUI 的所有功能

特性

• 🚀 高性能渲染: 底层直接调用 EUI-NEO 的 OpenGL + GLFW 渲染引擎
• 🎨 声明式 UI: 通过 Python 绑定使用 EUI 的现代化声明式界面语法
• 🧩 组件化开发: 完整暴露 EUI 的内置组件系统 (panel, button, label, column, row 等)
• 🎯 类型安全: 完整的 Python 类型注解支持 (基于 .pyi 存根文件)
• 🌙 主题支持: 直接调用 EUI 的亮色/暗色主题切换 API
• 📦 现代构建: 基于 Meson + pybind11 的 bindings 构建系统

技术栈

• 绑定层: pybind11 (C++/Python 互操作)
• 核心引擎: EUI-NEO (C++17 + OpenGL + GLFW)
• 构建系统: Meson + meson-python (支持 Python 包分发)
• 字体渲染: stb_truetype (EUI 内置)
• 图形渲染: Glad (OpenGL 加载器，EUI 依赖)

快速开始

环境要求

• Python >= 3.12
• C++17 兼容编译器
• Meson >= 1.2.0
• pybind11 >= 2.12

安装

# 使用 pip 安装
pip install pyeui

# 或使用 uv 安装
uv install pyeui

运行示例

# 基础示例
pyeui-basic-demo

# 计算器示例
pyeui-calc-demo

# 综合功能展示
pyeui-comprehensive-demo

# 闹钟示例
pyeui-clock-demo

# 完整功能展示
pyeui-showcase-demo
pyeui-demos

# 输入组件示例
pyeui-input-demo

# 列表视图示例
pyeui-listview-demo

# 滑块组件示例
pyeui-slider-demo

# 开关组件示例
pyeui-switcher-demo

基础示例

import pyeui

def main():
    config = pyeui.AppConfig(
        title="PyEUI Basic Demo",
        width=960,
        height=640,
        page_id="basic_demo",
        fps=120,
        dark_title_bar=True,
    )

    def compose(ui: pyeui.UIContext, screen: pyeui.RectFrame):
        pyeui.use_light_theme((0.0, 0.0, 0.0, 1.0))

        # 背景面板
        ui.panel(
            "bg",
            position=(0, 0),
            size=(screen.width, screen.height),
            background=(0.07, 0.07, 0.09, 1.0),
        )

        # 居中布局卡片
        ui.column(
            lambda: ui.panel(
                "card",
                size=(400, 200),
                rounding=24.0,
                background=(0.09, 0.09, 0.11, 1.0),
                border=(1.0, (0.22, 0.22, 0.28, 1.0)),
            ),
            position=(0, 0),
            size=(screen.width, screen.height),
            padding=16.0,
            justify_content=pyeui.MainAxisAlignment.Center,
            align_items=pyeui.CrossAxisAlignment.Center,
        )

        # 按钮
        ui.row(
            lambda: ui.button(
                "btn",
                size=(120, 40),
                rounding=12.0,
                style=pyeui.ButtonStyle.Primary,
                text="点击我",
                on_click=lambda: print("按钮被点击了!"),
            ),
            size=(0, 40),
            justify_content=pyeui.MainAxisAlignment.Center,
        )

    return pyeui.run_app(config, compose)

if __name__ == "__main__":
    raise SystemExit(main())

API 概览

注意: 以下所有 API 均为 EUI-NEO C++ 接口的 Python 绑定，函数签名和行为与 C++ 版本保持一致。

核心类型

• Color: 颜色类型 (RGBA 元组)
• RectFrame: 矩形区域 (x, y, width, height)
• Theme: 主题配置

布局枚举

• FlexDirection: 弹性布局方向
• MainAxisAlignment: 主轴对齐方式
• CrossAxisAlignment: 交叉轴对齐方式
• Easing: 动画缓动函数
• ButtonStyle: 按钮样式
• RenderLayer: 渲染层级

主要组件

• ui.panel(): 面板容器
• ui.label(): 文本标签
• ui.button(): 按钮组件
• ui.column(): 垂直布局
• ui.row(): 水平布局
• ui.checkbox(): 复选框组件
• ui.slider(): 滑块组件
• ui.switcher(): 开关组件
• ui.text_input(): 文本输入框
• ui.list_view(): 列表视图
• UIContext: UI 上下文对象

工具函数

• run_app(): 启动应用程序
• use_light_theme(): 使用亮色主题
• use_dark_theme(): 使用暗色主题
• open_url(): 打开URL链接

项目结构

pyeui/
├── csrc/                    # C++ Python Bindings 源码
│   ├── bind_core.cpp        # 核心类型绑定 (Color, RectFrame, Theme 等)
│   ├── bind_app.cpp         # 应用运行时绑定 (AppConfig, run_app 等)
│   ├── bind_context.cpp     # UI 上下文绑定 (UIContext 及其方法)
│   └── bind_components.cpp  # 组件绑定 (panel, button, label 等)
├── src/pyeui/               # Python 包
│   ├── __init__.py          # 包入口 (导出 C++ 绑定模块)
│   ├── _pyeui.pyi           # 类型存根 (为 C++ 绑定提供类型提示)
│   └── py.typed             # PEP 561 标记
├── examples/                # 示例代码
│   ├── basic_demo.py        # 基础示例
│   └── showcase.py          # 功能展示
├── subprojects/             # 子项目依赖
│   ├── eui/                 # EUI-NEO C++ 核心 (被绑定对象)
│   ├── glfw/                # GLFW 窗口库 (EUI 依赖)
│   ├── glad/                # OpenGL 加载器 (EUI 依赖)
│   ├── stb/                 # 图像处理库 (EUI 依赖)
│   └── nanosvg/             # SVG 渲染库 (EUI 依赖)
├── fonts/                   # 字体文件 (EUI 使用)
├── meson.build              # Meson 构建配置 (编译 bindings)
└── pyproject.toml           # Python 项目配置 (包分发)

开发指南

开发环境搭建

# 克隆项目
git clone <repository-url>
cd pyeui

# 创建虚拟环境 (推荐使用 uv)
uv venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# 安装开发依赖
uv pip install -e .[dev]

# 或者使用 meson 直接构建
meson setup build
cd build
meson compile

Bindings 开发

如果您想为 PyEUI 添加新的 API 绑定，请参考以下流程：

1. 定位 C++ 源: 在 subprojects/eui/src/ 中找到对应的 C++ 类/函数
2. 编写绑定代码: 在 csrc/ 目录下添加对应的 bind_*.cpp 文件
3. 更新类型存根: 同步更新 src/pyeui/_pyeui.pyi 以提供类型提示
4. 编译测试: 使用 pip install -e . 重新编译并测试
5. 添加示例: 在 src/pyeui/demos/ 中添加相应的示例代码
6. 注册脚本: 在 pyproject.toml 的 [project.scripts] 中注册新的demo命令

详细 pybind11 绑定语法请参考 pybind11 官方文档。

常见问题

构建失败怎么办?

确保您的系统已安装以下依赖：

• C++17 兼容的编译器 (GCC >= 7, Clang >= 5, MSVC >= 2017)
• Python >= 3.12 开发头文件
• Meson >= 1.2.0
• pybind11 >= 2.12

类型提示不工作?

PyEUI 使用 .pyi 存根文件提供类型提示。确保您的IDE支持PEP 561类型包标准。

在 Linux/macOS 上运行?

当前版本主要针对 Windows 平台优化，其他平台可能需要调整部分依赖配置。

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

致谢

• EUI-NEO - 底层 C++ GUI 框架 (被绑定项目)
• pybind11 - C++/Python bindings 库
• GLFW - 窗口管理库 (EUI 依赖)
• stb - 单文件公共领域库 (EUI 依赖)
• stb - 单文件公共领域库 (EUI 依赖)