Metadata-Version: 2.4
Name: freepygame
Version: 0.1.3
Summary: A Pygame UI controls library providing buttons, text, circles and other widgets
Home-page: https://github.com/freebird/freepygame
Author: freebird
Author-email: freebird <freebird@example.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/freebird/freepygame
Project-URL: Bug-Tracker, https://github.com/freebird/freepygame/issues
Project-URL: Source, https://github.com/freebird/freepygame
Project-URL: Documentation, https://github.com/freebird/freepygame#readme
Keywords: pygame,ui,controls,widgets,buttons,text,circles
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: pygame
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: license.txt
Requires-Dist: pygame>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Provides-Extra: fast
Requires-Dist: numpy>=1.21.0; extra == "fast"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# freepygame

一个为 Pygame 游戏开发提供 UI 控件和工具的 Python 库。

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![PyPI version](https://badge.fury.io/py/freepygame.svg)](https://badge.fury.io/py/freepygame)
[![PyPI downloads](https://img.shields.io/pypi/dm/freepygame.svg)](https://pypi.org/project/freepygame/)
[![Python](https://img.shields.io/badge/Python-3.7%2B-blue)](https://www.python.org/)
[![Pygame](https://img.shields.io/badge/Pygame-2.0%2B-orange)](https://www.pygame.org/)

## 特性

- 🎨 **丰富的 UI 组件**: 按钮、文本、圆形、图标、进度条、滑块、复选框等
- 📝 **表单控件**: 输入框（键盘焦点/光标/密码掩码）、下拉选择、开关、单选组
- 🎭 **主题系统**: 内置 light/dark 调色板，可一键应用到按钮与控件
- 📐 **自动布局**: VBox / HBox / 锚点布局，自动排布任意 `coordinates` 组件
- 🔧 **易于使用**: 简单的 API 和直观的接口
- 🎯 **灵活配置**: 支持颜色、大小、位置等属性动态调整
- ✨ **特效支持**: 粒子系统、图像处理等高级功能

## 安装

```bash
pip install freepygame
```

或者从源代码安装:

```bash
git clone https://github.com/freebird/freebPygame.git
cd freebPygame
pip install -e .
```

## 快速开始

```python
import pygame
from freepygame import FreeButton, FreeText, position_button_class

# 初始化 Pygame
pygame.init()
screen = pygame.display.set_mode((800, 600))
clock = pygame.time.Clock()

# 创建按钮
button = FreeButton(
    screen=screen,
    coordinates=[100, 100],
    button_size=[200, 50],
    msg="点击我",
    button_color=(70, 130, 180),
    text_color=(255, 255, 255)
)

# 创建文本
text = FreeText(
    screen=screen,
    coordinates=[100, 170],
    msg="欢迎使用 freepygame!",
    color=(0, 0, 0)
)

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        elif event.type == pygame.MOUSEBUTTONDOWN:
            if position_button_class(button, pygame.mouse.get_pos()):
                text.set_msg("按钮被点击了!")
    
    # 绘制
    screen.fill((240, 240, 245))
    button.draw()
    text.draw()
    
    pygame.display.flip()
    clock.tick(60)

pygame.quit()
```

## 主要组件

### 按钮组件

#### FreeButton - 矩形按钮
```python
button = FreeButton(
    screen=screen,
    coordinates=[x, y],          # 左上角坐标
    button_size=[width, height], # 按钮尺寸
    msg="按钮文本",              # 显示文本
    button_color=(r, g, b),      # 按钮背景色
    text_color=(r, g, b),        # 文本颜色
    draw_border=True,            # 是否显示边框
    border_width=2,              # 边框宽度
    dsm=1                        # 缩放系数
)
```

#### CircleButton - 圆形按钮
```python
circle_btn = CircleButton(
    screen=screen,
    coordinates=[x, y],          # 圆心坐标
    radius=50,                   # 半径
    msg="圆形按钮",              # 显示文本
    button_color=(r, g, b),      # 按钮颜色
    msg_color=(r, g, b)          # 文本颜色
)
```

### 文本组件

#### FreeText - 基础文本
```python
text = FreeText(
    screen=screen,
    coordinates=[x, y],          # 文本位置
    msg="文本内容",              # 显示文本
    font=None,                   # 字体文件路径或 Pygame 字体对象
    size=24,                     # 字体大小
    color=(r, g, b)              # 文本颜色
)
```

#### SuperText - 超级文本（支持缩放）
```python
super_text = SuperText(
    screen=screen,
    coordinates=[x, y],
    msg="支持缩放的文本",
    size=24,
    color=(r, g, b),
    dsm=1.5  # 1.5倍缩放
)
```

### 图形组件

#### FreeCircle - 圆形/弧形
```python
circle = FreeCircle(
    screen=screen,
    coordinates=[x, y],          # 圆心坐标
    radius=50,                   # 半径
    width=2,                     # 线宽（0为实心）
    angle=(0, 360),              # 角度范围（用于绘制弧）
    aa=True,                     # 是否抗锯齿
    color=(r, g, b)              # 颜色
)
```

#### FreeAllCircle - 静态绘图方法
```python
# 绘制抗锯齿圆
FreeAllCircle.draw_aacircle(screen, (x, y), radius, color)

# 绘制贝塞尔曲线
points = [(100, 100), (200, 50), (300, 150), (400, 100)]
FreeAllCircle.draw_bezier(screen, points, steps=100, color=(128, 128, 128))
```

### 其他组件

#### FreeIcon - 图标
```python
icon = FreeIcon(
    screen=screen,
    coordinates=[x, y],          # 图标位置
    image_1=normal_image,        # 正常状态图像
    image_2=hover_image          # 悬停状态图像
)

# 切换图标状态
icon.set_index(0)  # 显示 image_1
icon.set_index(1)  # 显示 image_2
```

#### ParticleEngine - 粒子系统
```python
engine = ParticleEngine()

# 生成粒子
engine.generate_particles(50, (x, y))

# 更新粒子
engine.update_particles()

# 绘制粒子
engine.draw_particles(screen)
```

### 图像处理

```python
from freepygame import image_blur_processing, array_mean_rgba

# 图像模糊处理
blurred_image = image_blur_processing(image, level=2)

# 计算图像区域的平均颜色
avg_color = array_mean_rgba(pixel_data)
```

## 实用函数

### 点击检测
```python
# 检测点是否在按钮内
if position_button(rect, pos):
    print("点在矩形内")

# 检测点是否在按钮对象内
if position_button_class(button, pos):
    print("点在按钮内")
```

## 控件、主题与布局

### 点击回调（Clickable）

`FreeButton` 与 `CircleButton` 内置 `Clickable` 混入，可注册点击回调，不再需要手动 `position_button_class` 判断：

```python
button = FreeButton(screen, [100, 100], [200, 50], msg="确定")
button.set_callback(lambda btn: print("clicked!", btn.msg))
# 在主循环的事件处理中：
if event.type == pygame.MOUSEBUTTONDOWN:
    button.handle_click(event.pos)   # 命中则触发回调并返回 True
```

`FreeFrame` 会自动承载控件并分发点击事件：

```python
app = FreeFrame(title="Demo")
app.add_widget(button)
# app.run() 时，点击事件会自动派发到已注册的控件
```

### 主题系统

```python
from freepygame import get_theme, apply_theme

apply_theme(button, get_theme("dark"))   # 内置 light / dark
```

### 基础控件

```python
from freepygame import ProgressBar, Slider, CheckBox

pb = ProgressBar(screen, [20, 20], width=200, value=0.5)
pb.set_value(0.8); pb.draw()

sl = Slider(screen, [20, 60], width=200, min_value=0, max_value=100, value=20)
sl.set_from_pos(pygame.mouse.get_pos())   # 根据指针位置设定值

ck = CheckBox(screen, [20, 100], size=24, checked=False)
ck.on_toggle = lambda checked: print("checked:", checked)
```

### 表单控件

```python
from freepygame import InputBox, Dropdown, Switch, RadioButton, RadioGroup

# 文本输入框：点击获得焦点后接收键盘输入
name = InputBox(screen, [20, 140], width=200, placeholder="请输入姓名")
name.on_change = lambda v: print("输入:", v)
name.on_submit = lambda v: print("回车提交:", v)

# 下拉选择框：点击展开，选择后触发回调
dd = Dropdown(screen, [20, 180], width=200, options=["红", "绿", "蓝"])
dd.on_select = lambda i, v: print("选中:", i, v)

# 开关
sw = Switch(screen, [20, 220], checked=False)
sw.on_change = lambda on: print("开关:", on)

# 单选组
group = RadioGroup()
group.add(RadioButton(screen, [20, 260], label="选项A", value="A"))
group.add(RadioButton(screen, [140, 260], label="选项B", value="B"))
```

在 `FreeFrame` 中，输入框的焦点与键盘事件会被自动分发：

```python
app = FreeFrame(title="表单")
app.add_widget(name)        # 点击输入框自动获得焦点
# app.run() 时，KEYDOWN 会自动转发给当前获得焦点的输入框
```

### 布局管理器

```python
from freepygame import VBox, HBox, AnchorLayout

VBox([button, pb, sl], spacing=10, padding=10).arrange(origin=(20, 20))
HBox([button, pb], spacing=8).arrange(origin=(20, 20))
AnchorLayout([pb], align="center").arrange(origin=(400, 300))
```

## 高级特性

### 操作符重载

#### SuperText 的操作符
```python
text = SuperText(screen, [100, 100], "Hello")

# << 操作符快捷设置属性
text << (36,)           # 设置字体大小
text << (200, 150)      # 设置位置
text << (255, 0, 0)     # 设置颜色

# + 操作符拼接文本
text + " World!"        # 文本变为 "Hello World!"
```

#### SuperCircle 的操作符
```python
circle = SuperCircle(screen, [400, 300], 50)

circle << (75,)         # 设置半径
circle << ((80, 60),)   # 设置椭圆半轴（外接矩形 rect）
circle << ((255, 0, 0),) # 设置颜色
```

## 项目结构
```
freepygame/
├── freepygame/          # 主包目录
│   ├── __init__.py     # 包初始化（重导出所有规范实现）
│   ├── freebutton.py   # 按钮组件 + Clickable 回调混入
│   ├── freecircle.py   # 圆形/弧形/曲线组件
│   ├── freetext.py     # 文本组件
│   ├── freeicon.py     # 图标 / 点 / 抗锯齿矩形
│   ├── freeparticle.py # 粒子系统 / 烟花
│   ├── freetransformation.py # 图像处理（模糊/取色）
│   ├── freetheme.py    # 主题系统
│   ├── freewidget.py   # 基础控件（进度条/滑块/复选框/输入框/下拉/开关/单选）
│   ├── freelayout.py   # 布局管理器（盒式/锚点）
│   └── freeframe.py    # 窗口/应用框架
├── tests/              # 测试目录
│   ├── conftest.py    # 测试配置
│   ├── test_components/ # 组件测试
│   └── test_integration/ # 集成测试
├── examples/           # 示例目录
├── setup.py           # 安装配置
├── README.md          # 本文档
└── LICENSE.txt        # 许可证文件
```

## 文档

API 参考由 Sphinx 自动从各模块 docstring 生成，位于 `docs/` 目录：

```bash
pip install -e .[docs]          # 安装 sphinx 等文档依赖
sphinx-build -b html docs docs/_build/html   # 生成 HTML
# 或在 docs/ 目录下使用 Makefile / make.bat：
cd docs && make html
```

生成的文档位于 `docs/_build/html/index.html`。项目已配置 `.readthedocs.yaml`，
可对接 Read the Docs 实现自动构建。

## 许可证

本项目采用 Apache License 2.0 许可证。详见 [LICENSE.txt](LICENSE.txt)。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 作者

freebird

## 致谢

- [Pygame](https://www.pygame.org/) - 游戏开发库

---

**注意**: 本库仍在积极开发中，API 可能会有变动。
