Metadata-Version: 2.1
Name: pyeui
Version: 0.1.0
Summary: EUI-NEO GUI 框架的 Python 绑定
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# PyEUI

<p align="center">
  <img src="subprojects/eui/docs/icon.png" width="120" height="120" />
</p>

**PyEUI** 是 [EUI-NEO](https://github.com/sudoevolve/EUI) 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

### 安装

```bash
# 使用 pip 安装
pip install pyeui

# 或使用 uv 安装
uv install pyeui
```

## 运行示例

```bash
# 基础示例
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
```

### 基础示例

```python
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链接

## 项目结构

```bash
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 项目配置 (包分发)
```

## 开发指南

### 开发环境搭建

```bash
# 克隆项目
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 官方文档](https://pybind11.readthedocs.io/)。

## 常见问题

### 构建失败怎么办?

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

- 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](LICENSE) 文件

## 致谢

- [EUI-NEO](https://github.com/sudoevolve/EUI) - 底层 C++ GUI 框架 (被绑定项目)
- [pybind11](https://github.com/pybind/pybind11) - C++/Python bindings 库
- [GLFW](https://www.glfw.org/) - 窗口管理库 (EUI 依赖)
- [stb](https://github.com/nothings/stb) - 单文件公共领域库 (EUI 依赖)
- [stb](https://github.com/nothings/stb) - 单文件公共领域库 (EUI 依赖)
