Metadata-Version: 2.4
Name: prismqml
Version: 0.4.1.4
Summary: A pure QML multi-skin component engine (Fluent Design + Neobrutalism + Vintage Ticket) with 120fps+ smooth animations
Author: aki-riko
License: MIT License
        
        Copyright (c) 2026 aki-riko
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/aki-riko/PrismQML
Project-URL: Documentation, https://aki-riko.github.io/PrismQML/
Project-URL: Repository, https://github.com/aki-riko/PrismQML
Project-URL: Issues, https://github.com/aki-riko/PrismQML/issues
Keywords: qml,fluent,neobrutalism,vintage-ticket,ui,pyside6,qt,design,skin
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6>=6.9.0
Requires-Dist: qrcode>=7.0
Provides-Extra: macos
Requires-Dist: pyobjc-framework-Cocoa>=9.0; extra == "macos"
Provides-Extra: dev
Requires-Dist: pytest>=8.4; extra == "dev"
Requires-Dist: opencv-python-headless<5,>=4.8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: maturin>=1.0; extra == "dev"
Provides-Extra: rust
Requires-Dist: prismqml-rs>=0.1.0; extra == "rust"
Dynamic: license-file

# PrismQML（棱镜映界）

**简体中文** | [English](./README.en.md)

> **一套 QML 控件，多种设计语言一键切换。**
> PrismQML（棱镜映界）是基于 PySide6 + QML 的**多皮肤 UI 引擎**：同一套控件，运行时自由切换 **流畅设计（Fluent Design）**、**新粗野主义（Neobrutalism）**、**复古票据（Vintage Ticket）**与**新拟态（Neumorphism）**，120fps+ 流畅动画。

![PrismQML（棱镜映界）四套皮肤组件实景对比](docs/images/prismqml-skins.png)

- **安装**：`pip install prismqml`
- **文档**：[aki-riko.github.io/PrismQML](https://aki-riko.github.io/PrismQML/)
- **适合**：想用 Python + QML 做现代桌面应用，同时需要统一控件、主题 token、运行时换肤和跨平台窗口能力的项目。

```python
from prismqml import setSkin, Skin
setSkin(Skin.NEOBRUTALISM)   # 一行切换整个应用的设计语言
```

## ✨ 特性

- **🎨 多皮肤引擎**：同一套控件，`setSkin()` 一键切换流畅设计 / 新粗野主义 / 复古票据 / 新拟态，四套皮肤均支持 light/dark
- **🧩 token 驱动架构**：颜色、几何、阴影全走 token —— 新增皮肤几乎**零控件改动**
- **⚡ 纯 QML 渲染**：无帧率限制，120fps+ 流畅动画
- **🐍 PySide6 原生**：无缝集成，Python 侧管理业务逻辑，无需为业务界面编写 C++
- **📦 180+ QML 类型**：按钮 / 输入 / 卡片 / 对话框 / 表格 / 图表 / 导航等全套
- **💾 配置系统**：JSON 持久化 + 原子写入 + QML Property 桥接
- **🔄 响应式状态**：细粒度 Store 状态管理，支持 watch / batch 模式
- **🪟 窗口管理**：多种窗口布局 + 懒加载 + 云母效果 + 系统托盘
- **🌍 跨平台**：Windows、macOS、Linux

## 📦 安装

```bash
pip install prismqml
```

> 分发名与导入名一致：`pip install prismqml` 后 `from prismqml import ...`。
> 运行环境要求 Python 3.9+ 与 PySide6 6.9+（Qt 6.9+）。
> Windows 宿主在创建首个 `QQuickWindow` 前固定使用 D3D11；macOS 与 Linux
> 保留 Qt 的平台默认图形后端。

开发模式安装：

```bash
git clone https://github.com/aki-riko/PrismQML.git
cd PrismQML
pip install -e ".[dev]"
```

## 🚀 快速开始

```python
from prismqml import App, WindowType

app = App()
window = app.create_window(WindowType.BAR)
window.setWindowTitle("我的应用")
window.resize(1200, 800)

window.show()
app.exec()
```

需要导航内容时，通过 `window.addPage(PageClass, icon, title)` 添加应用自己的
页面类、页面工厂或页面实例；异步 QML 页面可使用 `AsyncQmlPage`。

## 🏗️ 架构

```
prismqml/
├── PrismQML/              # QML 组件（模块名 PrismQML）
│   ├── controls/           # UI 控件
│   ├── _internal/          # 内部窗口实现
│   └── PrismEnums/        # 枚举与常量
└── python/                 # Python 模块
    ├── config/             # 配置管理系统
    ├── core/               # 核心引擎（主题/日志/图标/阴影）
    ├── runtime/            # 运行时装配（注册/外观持久化边界）
    ├── window/             # 窗口管理（懒加载/云母/托盘）
    ├── state/              # 响应式状态存储
    ├── providers/          # 功能提供者（SVG/二维码/取色器）
    └── models/             # 数据模型（高性能表格）
```

## 📐 窗口类型

| 类型 | 枚举值 | 说明 |
|------|--------|------|
| `WindowType.BAR` | 1 | 紧凑侧边导航（默认） |
| `WindowType.SPLIT` | 0 | 展开式侧边导航 |
| `WindowType.FILLED` | 2 | 填充式分割窗口 |

```python
from prismqml import App, WindowType

app = App()

# 紧凑侧边导航（默认）
window = app.create_window(WindowType.BAR)

# 展开式侧边导航
window = app.create_window(WindowType.SPLIT)
```

## 🎨 皮肤系统（核心）

棱镜映界的招牌能力：**皮肤与明暗正交**。`skin` 控制设计语言，`theme` 控制明暗，两者独立组合。

```python
from prismqml import setSkin, Skin

setSkin(Skin.FLUENT)          # Fluent Design：圆角、模糊阴影、蓝主色
setSkin(Skin.NEOBRUTALISM)    # 新粗野：粗黑边、硬阴影、橙撞色
setSkin(Skin.VINTAGE_TICKET)  # 复古票据：暖纸、油墨细线、印章语义色
setSkin(Skin.NEUMORPHISM)     # 新拟态：同色表面、双向软阴影、凹凸交互
```

QML 侧通过 `Enums.skin` 与 `Enums.isNeobrutalism` / `isVintageTicket` /
`isNeumorphism` 读取当前皮肤：

```qml
import PrismQML
Rectangle {
    radius: Enums.isVintageTicket ? Enums.ticket.radius : Enums.radius.small
    // 但大多数情况你无需判断——控件已自动适配皮肤
}
```

**架构亮点**：皮肤差异收敛在 token 层（颜色 / 几何 / 阴影），控件本身对皮肤无感知。
新增皮肤主要扩展 token，只在阴影或交互几何确有差异时增加结构分支。

## 🌗 主题系统

### 切换主题

```python
from prismqml import setTheme, Theme

setTheme(Theme.LIGHT)   # 浅色
setTheme(Theme.DARK)    # 深色
setTheme(Theme.AUTO)    # 跟随系统
```

### 自定义主题色

```python
from prismqml import setAccentColor, getAccentColor

setAccentColor("#0078d4")
print(getAccentColor())  # "#0078d4"
```

### QML 中使用

```qml
import PrismQML as Fluent

// Primary 按钮（style_primary 自动使用全局主题色）
Fluent.Button {
    text: "确定"
    style: Fluent.Enums.button.style_primary
}

// 所有主题 token 统一通过 Enums 访问
Rectangle {
    color: Fluent.Enums.accentColor
}
```

> `ComboBox`、`Slider` 已在顶层 `PrismQML` 模块注册。使用
> `import PrismQML as Fluent` 后直接写 `Fluent.ComboBox` / `Fluent.Slider`，
> 无需导入 QtQuick.Controls 或内部目录。

## ⚙️ 配置系统

配置系统采用五层架构：`Validator` → `SettingEntry` → `SettingsCore` → `AppConfig` → `ConfigManager`

- **JSON 持久化**：Window 设置默认存储于 `~/.prismqml/app.json`
- **原子写入**：先写临时文件再替换，防止断电数据丢失
- **QML 桥接**：通过 `ConfigManager` 单例暴露为 QML Property

`App()` 的全局外观默认始终是 Fluent，不会再从共享文件隐式恢复其他应用的
Theme/Skin/Language/AccentColor。需要应用级外观持久化时传入独立
`config_path`；已有自身外观配置的宿主同时传 `persist_appearance=False`。

```python
from prismqml.python.config import AppConfig, getConfigManager

# 获取配置值
config = getConfigManager()
print(config.lazyLoading)   # True
print(config.dpiScale)      # 0（跟随系统）

# 修改配置（自动保存到 JSON）
config.setDpiScale(150)
```

### 自定义配置项

```python
from typing import ClassVar
from prismqml.python.config import (
    SettingsCore, SettingEntry, EnumEntry,
    Validator,
)


class MyAppConfig(SettingsCore):
    auto_save: ClassVar[SettingEntry] = SettingEntry(
        group="Editor", name="AutoSave",
        default=True, validator=Validator.boolean(),
    )
    font_size: ClassVar[EnumEntry] = EnumEntry(
        group="Editor", name="FontSize",
        default=14,
        validator=Validator.choice([12, 14, 16, 18, 20, 24]),
    )
```

## 📊 状态管理

`Store` 提供响应式状态存储，支持细粒度 watch 和批量更新：

```python
from prismqml import Store

class AppStore(Store):
    def __init__(self):
        super().__init__("app")
        self.define("user", None)
        self.define("count", 0)

store = AppStore()

# 监听变化
store.watch("count", lambda new, old: print(f"{old} → {new}"))

# 设置值
store.set("count", 1)     # 输出: 0 → 1

# 批量更新（合并通知）
with store.batch():
    store.set("count", 10)
    store.set("user", "Alice")
# 退出 with 时统一通知

# 字典语法
store["count"] = 20
print(store["count"])      # 20
```

## 🔔 系统托盘

```python
from prismqml import SystemTrayIcon, Icon

tray = SystemTrayIcon(icon="AppIcon.png", toolTip="我的应用")
tray.addAction(text="显示", icon="Visibility", triggered=window.show)
tray.addSeparator()
tray.addAction(text="退出", icon="Power", triggered=app.quit)
tray.show()
```

## 🧩 UI 组件

### 控件
Button · Card · CheckBox · ToggleSwitch · LineEdit · ComboBox · Slider · ProgressBar · SpinBox · TableView · ListView · TreeView

### 导航
NavigationBar · NavigationView · Pivot · Breadcrumb · Windows

### 特效
Shadow · ShadowedRectangle · ColorOverlay · GaussianBlur

> 完整组件清单见[在线文档](https://aki-riko.github.io/PrismQML/components/)。
> `ComboBox`、`Slider` 已在顶层 `PrismQML` 模块注册；使用
> `import PrismQML as Fluent` 后直接写 `Fluent.ComboBox` / `Fluent.Slider`。

## 🧰 开发产物

本地构建产物和缓存统一写入仓库根目录 `.artifacts/`，按用途分为：

- `.artifacts/cpp/`：CMake 桌面、Android、iOS 构建树
- `.artifacts/python/`：Python 构建、分发包、pytest 缓存和字节码缓存
- `.artifacts/rust/`：Cargo target
- `.artifacts/docs/`：MkDocs 站点

历史散落目录已移到各类别的 `legacy/`，不再作为新的构建入口。需要把产物放到仓库外时，设置 `PRISM_ARTIFACT_ROOT`；C++ 脚本仍可用 `PRISM_DESKTOP_BUILD_DIR` 或 `PRISM_ANDROID_BUILD_DIR` 单独覆盖。

## 🧪 测试

```bash
python scripts/test_process.py --qt-platform offscreen --timeout 480 -- python -m pytest
python scripts/test_process.py --qt-platform offscreen --timeout 180 -- python -X utf8 tests/qml/probe_all_components.py
```

自动化 pytest 与 QML probe 始终强制使用 `offscreen`，调用者已有的 `windows` / `minimal` 等平台值也会被覆盖。Windows 下 `test_process.py` 会把完整测试进程树放入私有 Desktop 与关闭即终止的 Job Object，因此测试 UI（包括短暂窗口）不会出现在当前用户桌面；runner 会轮询检测 Job 内持续可见窗口，检测到时记录证据并以 126 失败，正常退出或超时时确认全部后代进程归零。请勿绕过该 runner 裸跑自动化测试。单独运行标注为手工窗口测试的脚本仍可能显示 UI。C++/CTest 的真实 Windows Mica 验证说明见 [`cpp/README.md`](cpp/README.md#运行测试)。

## 📄 License

PrismQML is licensed under the [MIT License](./LICENSE).

Copyright © 2026 aki-riko.

## 🙏 Credits

- Design inspired by the Microsoft Fluent Design System.
- Icons from [Microsoft Fluent UI System Icons](https://github.com/microsoft/fluentui-system-icons) (MIT License).
