fluentpy-qt 0.6.9__tar.gz

fluentpy_qt-0.6.9/.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+
+[*.toml]
+indent_size = 2

fluentpy_qt-0.6.9/.gitattributes

@@ -0,0 +1,8 @@
+* text=auto eol=lf
+*.py text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.bat text eol=crlf
+*.txt text eol=lf
+*.svg text eol=lf
+*.png binary

fluentpy_qt-0.6.9/AGENTS.md

@@ -0,0 +1,12 @@
+# FluentPy 开发约定
+
+## 后端运算优先 C，并保留 Python 兼容回退
+
+用户于2026-10-16指定后端使用C、前端无需迁移；于2026-10-17补充：C扩展不可用时自动回退Python，不能让组件失去功能。以下为当前约定。
+
+- 后端运算以C作为首选加速实现，放在`native/`，通过扩展向Python暴露接口；同步维护行为兼容的Python回退。
+- Python 负责公开组件接口、C 绑定与调用，以及 Qt 界面逻辑；保持已有公开 API 的使用方式。
+- C扩展缺失、导入失败或缺少对应接口时自动回退Python，不能因此禁用日期、拖放或快捷键组件；旧扩展可用的其他接口继续使用C。
+- `FLUENTPY_BACKEND=auto`优先C并自动回退，`python`强制所有兼容实现，`native`显式要求C并在对应接口缺失时报错。模式统一作用于文本、日期、时间、拖放和快捷键。回退不隐藏业务参数错误。
+- 前端控件、布局与绘制继续使用现有 Qt/Python 方案，不为本约定专门迁移到 C。
+- 报告实际接入的 C 路径与实测结果，不将该约定表述为全部组件已经完成 C 改造。

fluentpy_qt-0.6.9/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FluentPy contributors
+
+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.

fluentpy_qt-0.6.9/MANIFEST.in

@@ -0,0 +1,15 @@
+include LICENSE THIRD_PARTY_NOTICES.md README.md README-PyPI.md pyproject.toml setup.py
+include UPDATE_LOG.md AGENTS.md
+include 上传到PyPI.bat
+include .editorconfig .gitattributes
+recursive-include src *.py *.svg
+recursive-include native *.c *.h
+recursive-include scripts *.py *.ps1 *.bat
+recursive-include examples *.py *.bat
+recursive-include tests *.py
+include benchmarks/baseline-original-source.json
+include benchmarks/baseline-original.json
+include benchmarks/text-performance*.json
+recursive-include docs *.md *.png
+recursive-include licenses *.txt
+global-exclude *.pyd *.dll *.so *.pyc *.pyo

fluentpy_qt-0.6.9/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: fluentpy-qt
+Version: 0.6.9
+Summary: Independent MIT-licensed Fluent-inspired UI toolkit for Qt for Python.
+Author: 性邓的小馒头
+License-Expression: MIT
+Project-URL: Homepage, https://fluentpy.mcxmcl.cn/
+Project-URL: Documentation, https://fluentpy.mcxmcl.cn/
+Project-URL: Repository, https://github.com/XDDXMT/FluentPy
+Project-URL: Issues, https://github.com/XDDXMT/FluentPy/issues
+Keywords: qt,pyside6,fluent,widgets,desktop
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: licenses/Microsoft-Fluent-System-Icons-LICENSE.txt
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: PySide6>=6.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# FluentPy for Qt
+
+**Fluent 风格的 Qt for Python 桌面组件库，由性邓的小馒头独立开发，采用 MIT 许可证。**
+
+[中文文档](https://fluentpy.mcxmcl.cn/) · [源码与示例](https://github.com/XDDXMT/FluentPy) · [问题反馈](https://github.com/XDDXMT/FluentPy/issues)
+
+## 安装
+
+需要 Python 3.10+。建议在新建的虚拟环境内安装：
+
+```console
+python -m venv .venv
+# Windows
+.venv\Scripts\python -m pip install fluentpy-qt
+# macOS / Linux
+.venv/bin/python -m pip install fluentpy-qt
+```
+
+PyPI 安装名是 **`fluentpy-qt`**，代码导入名仍为 **`fluentpy`**。
+PyPI 上的 `fluentpy` 是其他作者的独立项目，请勿用 `pip install fluentpy` 安装本组件库。
+两个项目的导入名称冲突，应放在不同的虚拟环境中使用。
+
+PySide6 会作为依赖安装。Qt、PySide6 等依赖遵循各自的许可证。
+
+## 第一个窗口
+
+```python
+import sys
+from fluentpy import AccentButton, FluentWindow
+from fluentpy.qt import QtWidgets
+
+app = QtWidgets.QApplication(sys.argv)
+window = FluentWindow("你好，FluentPy")
+window.resize(800, 560)
+window.set_title_bar_enabled(True)
+button = AccentButton("你好，世界")
+window.content_layout.addWidget(button)
+window.show()
+sys.exit(app.exec())
+```
+
+## 组件
+
+- 按钮、输入、前后缀输入、分格密码、复选框和各类下拉选择。
+- 表格、滑块、日期时间滚轮、日历、颜色编辑器和取色。
+- 卡片、可展开容器、导航、流畅窗口、启动页面及主题渐变。
+- 高级右键菜单、消息条、吐司、进度提示和对话框。
+- 拖放、快捷键录制、代码编辑器和音符时间轴。
+
+工作台和独立示例在源码仓库的 `examples/` 中，可从源码运行 `python examples/showcase.py`。
+wheel 安装的是组件库，不包含示例工作台。
+
+## 可选 C 加速
+
+Qt 负责界面和动画；C 扩展加速文本、日期、时间、日历、拖放、快捷键、颜色和输入策略。
+默认优先使用 C，扩展缺失或不兼容时自动回退 Python，基本运行无需 C 编译器。
+
+当前提供 Windows x64 / CPython 3.13 的原生 wheel，以及不含本机二进制的通用 Python wheel。
+其他 Python 版本和平台使用通用 wheel，运行兼容后端；也可从源码编译对应扩展。
+`FLUENTPY_BACKEND=python` 可强制回退，`native` 要求对应 C 接口可用。
+
+当前实际验证环境为 Windows x64、CPython 3.13、PySide6 / Qt 6.11.1。
+其他平台的桌面表现需另行验证。Windows 11 云母效果在系统不支持时回退普通背景。
+
+项目处于早期开发阶段。组件接口、用法及 C 构建说明见[官方文档](https://fluentpy.mcxmcl.cn/)。
+
+## 来源与许可
+
+FluentPy 独立实现组件，仅参考公开的 Fluent 设计与交互思路，不包含参考组件库的源码、样式或示例素材。
+Microsoft Fluent UI System Icons 的 MIT 许可与来源声明随包提供。
+详情见[第三方声明](https://github.com/XDDXMT/FluentPy/blob/main/THIRD_PARTY_NOTICES.md)。

fluentpy_qt-0.6.9/README-PyPI.md

@@ -0,0 +1,71 @@
+# FluentPy for Qt
+
+**Fluent 风格的 Qt for Python 桌面组件库，由性邓的小馒头独立开发，采用 MIT 许可证。**
+
+[中文文档](https://fluentpy.mcxmcl.cn/) · [源码与示例](https://github.com/XDDXMT/FluentPy) · [问题反馈](https://github.com/XDDXMT/FluentPy/issues)
+
+## 安装
+
+需要 Python 3.10+。建议在新建的虚拟环境内安装：
+
+```console
+python -m venv .venv
+# Windows
+.venv\Scripts\python -m pip install fluentpy-qt
+# macOS / Linux
+.venv/bin/python -m pip install fluentpy-qt
+```
+
+PyPI 安装名是 **`fluentpy-qt`**，代码导入名仍为 **`fluentpy`**。
+PyPI 上的 `fluentpy` 是其他作者的独立项目，请勿用 `pip install fluentpy` 安装本组件库。
+两个项目的导入名称冲突，应放在不同的虚拟环境中使用。
+
+PySide6 会作为依赖安装。Qt、PySide6 等依赖遵循各自的许可证。
+
+## 第一个窗口
+
+```python
+import sys
+from fluentpy import AccentButton, FluentWindow
+from fluentpy.qt import QtWidgets
+
+app = QtWidgets.QApplication(sys.argv)
+window = FluentWindow("你好，FluentPy")
+window.resize(800, 560)
+window.set_title_bar_enabled(True)
+button = AccentButton("你好，世界")
+window.content_layout.addWidget(button)
+window.show()
+sys.exit(app.exec())
+```
+
+## 组件
+
+- 按钮、输入、前后缀输入、分格密码、复选框和各类下拉选择。
+- 表格、滑块、日期时间滚轮、日历、颜色编辑器和取色。
+- 卡片、可展开容器、导航、流畅窗口、启动页面及主题渐变。
+- 高级右键菜单、消息条、吐司、进度提示和对话框。
+- 拖放、快捷键录制、代码编辑器和音符时间轴。
+
+工作台和独立示例在源码仓库的 `examples/` 中，可从源码运行 `python examples/showcase.py`。
+wheel 安装的是组件库，不包含示例工作台。
+
+## 可选 C 加速
+
+Qt 负责界面和动画；C 扩展加速文本、日期、时间、日历、拖放、快捷键、颜色和输入策略。
+默认优先使用 C，扩展缺失或不兼容时自动回退 Python，基本运行无需 C 编译器。
+
+当前提供 Windows x64 / CPython 3.13 的原生 wheel，以及不含本机二进制的通用 Python wheel。
+其他 Python 版本和平台使用通用 wheel，运行兼容后端；也可从源码编译对应扩展。
+`FLUENTPY_BACKEND=python` 可强制回退，`native` 要求对应 C 接口可用。
+
+当前实际验证环境为 Windows x64、CPython 3.13、PySide6 / Qt 6.11.1。
+其他平台的桌面表现需另行验证。Windows 11 云母效果在系统不支持时回退普通背景。
+
+项目处于早期开发阶段。组件接口、用法及 C 构建说明见[官方文档](https://fluentpy.mcxmcl.cn/)。
+
+## 来源与许可
+
+FluentPy 独立实现组件，仅参考公开的 Fluent 设计与交互思路，不包含参考组件库的源码、样式或示例素材。
+Microsoft Fluent UI System Icons 的 MIT 许可与来源声明随包提供。
+详情见[第三方声明](https://github.com/XDDXMT/FluentPy/blob/main/THIRD_PARTY_NOTICES.md)。

fluentpy_qt-0.6.9/README.md

@@ -0,0 +1,248 @@
+# FluentPy
+
+**面向 Qt for Python 的 Fluent 风格桌面组件库。**
+
+FluentPy 是面向 Qt for Python 的 Fluent 风格组件库，由 **性邓的小馒头** 独立开发，采用 [MIT 许可证](LICENSE)。从输入框、卡片和日期滚轮，到带动画的导航、代码编辑器和消息浮层，可以逐个使用，也可以组合成完整工作台。
+
+界面由 Qt 控件、绘制与动画实现；计算密集的后端逐步交给 C 扩展。默认使用 PySide6，保留 PyQt6 适配入口。当前版本为 **0.6.9**，仍处于早期开发阶段。
+
+[官方文档](https://fluentpy.mcxmcl.cn/) · [文档源码](https://github.com/XDDXMT/FluentPy-Docs) · [快速开始](#快速开始) · [组件与示例](#组件与示例) · [C 后端与性能](#c-后端与性能) · [问题反馈](https://github.com/XDDXMT/FluentPy/issues)
+
+## 界面展示
+
+组件示例程序包含组件概览、14个组件页面和底部固定的设置页，直接使用 FluentWindow 的导航、标题栏与页面历史。组件页面涵盖按钮与右键菜单、输入、表格、滑块、日期时间、日历、拖放、颜色与取色、快捷键、卡片、导航、消息、代码编辑和音符。搜索和概览固定，中间导航列表独立滚动，底部设置随时可用。
+
+![FluentPy 新版示例工作台，浅色主题](docs/assets/gallery-preview-light.png)
+
+<details>
+<summary>查看深色主题</summary>
+
+![FluentPy 新版示例工作台，深色主题](docs/assets/gallery-preview.png)
+
+</details>
+
+工作台直接使用库内的 `NavigationView`、`NavigationSidebar` 和 `AnimatedStackedWidget`：侧栏展开与收起、选中指示条和页面切换都有动画。Pivot 与文档标签连接实际内容，支持编辑、新建、关闭和保留各页输入。
+
+底部“设置”直接组合已有的 `ComboBox`、`Slider`、`ToggleSwitch`、`Button` 和 `GroupHeaderCardWidget`。主题、强调色、云母效果、侧栏宽度与展开状态、页面动画和后端状态显示均即时生效，使用 Qt 的 `QSettings` 自动保存；恢复默认设置保留文档输入。侧栏分区与自定义插槽见[导航说明](docs/navigation.md)。
+
+卡片保持常规桌面尺寸，主题统一管理颜色和字体；内容区的操作交给内部按钮，折叠卡片通过标题条展开与收起，并保留表单值。组件示例采用 Microsoft Fluent 图标和统一的标题、内容与参数区，主图标与文档站一致。
+
+下拉选择支持普通／可编辑、Qt 模型绑定、多选标签、树形单选与多选、透明样式和系统字体。工作台“文本与选择 → 下拉选择”集中预览与测试，也可运行 `python examples/combo_boxes.py`。详见[下拉选择](docs/combo-boxes.md)。
+
+滑块有独立的侧栏入口，支持竖向、当前数值提示和双端区间；右键菜单支持多级子菜单、原生控件混排与鼠标点击定位，系统托盘使用真正的 QMenu。工作台采用可切换预览与参数区，详见[滑块](docs/sliders.md)和[菜单](docs/menus.md)。
+
+工作台“表格”提供 `TableView` 与 `TableWidget`，支持普通／圆角／细线行、搜索、原生排序、编辑、复选项、多选复制与高级右键菜单；外观设置默认收起。两种 Qt 数据接口各自保留编辑，详见[表格](docs/tables.md)。
+
+`FluentWindow` 保留原生 Qt 主窗口与系统标题栏，可按需注册页面，使用响应式侧栏、顶部导航、前进／后退和底部设置。可选 `FluentTitleBar` 为搜索框、标签与额外操作提供普通 Qt 布局；页面与输入在切换布局时保留。运行 `python examples/fluent_window.py` 体验，详见[流畅窗口](docs/fluent-window.md)。
+
+`SplashScreen` 提供居中图标、可选加载提示和完成渐隐。启动时顶部只保留三个窗口操作，结束后恢复完整标题栏。工作台“页面导航 → 启动页面”可调整并重播，也可运行 `python examples/splash_screen.py`。详见[启动页面](docs/splash-screen.md)。
+
+工作台默认启用整窗深浅色渐变，48px 标题栏、侧栏、背景与控件同步变化。普通窗口可通过 `set_theme_transition_enabled(True)` 开启；使用 `theme.set_theme("dark", accent="#60cdff")` 可一次提交主题与强调色，避免重复刷新。
+
+标题栏与侧栏共用外壳表面，主内容使用独立的不透明背景。工作台默认启用 Windows 11 原生云母，可在“设置 → 外观”关闭；普通 `FluentWindow` 可用 `set_backdrop_enabled(True)` 开启。Windows 11 build 22621 起，在系统合成和透明效果允许时显示材质，否则回退普通背景；失焦后可能显示系统中性色。详见[云母效果与自定义页面背景](docs/fluent-window.md#明暗背景与云母效果)。
+
+## 快速开始
+
+PyPI 发布名为 **`fluentpy-qt`**，代码导入名仍是 **`fluentpy`**。首次上传准备与本机上传助手见[发布说明](docs/publishing.md)。PyPI 上的 `fluentpy` 属于其他项目，不要用它安装本组件库，也不要将两个项目装在同一环境。
+
+需要 **Python 3.10+**。下面以 Windows PowerShell 为例，从本仓库安装到独立环境：
+
+```powershell
+git clone https://github.com/XDDXMT/FluentPy.git
+cd FluentPy
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e .
+```
+
+安装时会尝试构建可选C扩展。默认优先使用C；扩展缺失、无法加载或缺少某个组件的接口时，该组件自动回退到Python兼容后端。**日期／时间滚轮、三种日历选择器、拖放、快捷键选择器和CodeEdit都能在没有C扩展时使用**，无需为运行这些组件安装编译器。需要启用C加速时，再完成下面的构建步骤。
+
+已有兼容当前 Python 的系统 C 编译器时：
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install "setuptools>=77"
+.\.venv\Scripts\python.exe -B scripts/build_native.py
+.\.venv\Scripts\python.exe examples/showcase.py
+```
+
+Windows x64 没有安装 MSVC，也可以使用仓库提供的独立 Zig 工具链：
+
+```powershell
+.\.venv\Scripts\python.exe -B scripts/fetch_zig.py
+.\.venv\Scripts\python.exe -B scripts/build_native.py --zig .toolchains/zig-x86_64-windows-0.14.1/zig.exe
+.\.venv\Scripts\python.exe examples/showcase.py
+```
+
+下载器从 Zig 官方站点获取固定版本并校验 SHA-256，约 82 MB，文件与缓存留在项目目录。原生扩展必须匹配当前 Python 小版本、系统和架构。更多选项见 [C 后端构建与打包](docs/native-build.md)。
+
+以上为源码安装；PyPI 发布完成后可使用 `python -m pip install fluentpy-qt`。当前实际验证环境是 **Windows x64、CPython 3.13、PySide6 / Qt 6.11.1**；其他环境需要自行验证。Windows 系统材质不可用时，窗口使用普通背景。
+
+### 写下第一个窗口
+
+在已安装 FluentPy 的 Python 环境中运行：
+
+```python
+import sys
+
+from fluentpy import AccentButton, FluentWindow, Toast
+from fluentpy.qt import QtWidgets
+
+app = QtWidgets.QApplication(sys.argv)
+window = FluentWindow("我的 FluentPy 应用")
+
+save = AccentButton("保存")
+save.clicked.connect(
+    lambda: Toast.success(
+        "已保存",
+        detail="可以继续下一步。",
+        target=save,
+        parent=window,
+    )
+)
+window.content_layout.addWidget(save)
+window.show()
+
+sys.exit(app.exec())
+```
+
+控件继续使用 Qt 的信号、布局和事件机制。`Toast` 可指向触发按钮，也可放在窗口四角；仅传标题时使用紧凑的单行提示，并带入场与退场动画。
+
+## 组件与示例
+
+| 类别 | 主要组件与能力 |
+| --- | --- |
+| 按钮 | 普通／强调／透明图标、状态切换与胶囊筛选、下拉／拆分操作、`LoadingButton` 与动画 `ActionMenu` |
+| 输入与选择 | `LineEdit`、`AffixLineEdit` 前后缀、`PinCodeEdit` 分格密码／验证码、搜索／密码／多行输入、下拉框、数值输入、复选框和单选按钮 |
+| 日期与时间 | `DatePicker`与`TimePicker`日期／时间滚轮；`CalendarPicker`日历、`DateRangePicker`日期区间、`DateTimePicker`日历与时分秒，支持禁用日期、页内动画与C／Python双后端 |
+| 拖放 | `FileDropWidget`、`FolderDropWidget`、`DropArea`：浏览与拖入本地路径、类型过滤、多选和后台校验 |
+| 快捷键 | `ShortcutPicker`、`ShortcutDialog`：组合键录制、键帽预览、保存／重置／取消与冲突提示 |
+| 颜色与取色 | `ColorPickerButton`、`ColorPaletteButton`、`ColorDialog`、`ColorPickerPanel`、`ColorSwatchGroup`、`EyeDropperButton`：主题色、Hex／RGB／HSV／Alpha、确认／取消与多屏取色 |
+| 代码编辑 | `CodeEdit`：JSON 高亮、行号、当前行、缩进引导、字体设置与 C 扫描后端 |
+| 卡片与设置 | `CardWidget`、`SimpleCardWidget`、`ElevatedCardWidget`、`HeaderCardWidget`、`GroupHeaderCardWidget`；`ExpandableCardWidget` 与 `AccordionWidget` 提供动画折叠及独立／互斥展开 |
+| 导航 | `NavigationView`、`NavigationSidebar`、`AnimatedStackedWidget`、`BreadcrumbBar`、`Pivot`、分段控件、`TabBar` |
+| 表格 | `TableView`、`TableWidget`、`TableItemDelegate`：Qt 模型／项目接口、三种行样式、原生排序和编辑、TSV 复制与高级菜单 |
+| 反馈与状态 | `InfoBar`、`ProgressInfoBar`：横纵消息条、嵌入布局与任务状态；`Toast`、`ColorToast`、`ProgressToast`：顶部色条、操作按钮、六种位置混合堆叠与单段进度；`ToggleSwitch`、`Slider`、`ProgressBar` |
+| 窗口与容器 | `FluentWindow`、无边框对话框、页内遮罩对话框、`FluentScrollBar`、`Card`、`ExamplePanel` |
+| 音符视图 | `NoteTimeline`、`NoteEvent`：单轨／多轨概览、配色、进度游标与时间定位 |
+| 主题与资源 | 浅色／深色主题、强调色、统一字体、107 个 Microsoft Fluent System Icons |
+
+独立 Demo 适合只看一个组件。在已安装依赖的环境中，从仓库根目录运行：
+
+| 示例 | 运行命令 | 说明 |
+| --- | --- | --- |
+| 组件示例程序 | `python examples/showcase.py` | 概览、14个组件页面及底部设置；`--dark` 启动深色，`--page tables` 直接测试表格，`--page settings` 打开可保存的工作台设置 |
+| 表格 | `python examples/tables.py` | 普通／圆角／细线、Qt 模型与项目、搜索、数值排序、编辑、多选复制与高级右键菜单 |
+| 启动页面 | `python examples/splash_screen.py` | 居中图标、可选加载提示、完成渐隐和全窗口预览；工作台“页面导航”页 |
+| 颜色与取色 | `python examples/colors.py` | 色板、RGBA／HSV 编辑、颜色对话框、圆形色块与屏幕取色；工作台 `--page colors` |
+| 按钮与菜单 | `python examples/buttons.py` | 状态过渡、互斥筛选、页内菜单、拆分操作、加载保护与键盘操作 |
+| 前后缀与分格输入 | `python examples/advanced_inputs.py` | 固定前后缀、四格密码、六格验证码、粘贴与退格回删；工作台“文本与选择”页 |
+| 拖放文件 | `python examples/drop.py` | 文件／文件夹、浏览、后台校验与路径结果；C优先，Python兼容 |
+| 快捷键选择器 | `python examples/shortcut_picker.py` | 页内录制、冲突提示与窗口内快捷键触发；C优先，Python兼容 |
+| 带说明复选框 | `python examples/checkbox.py` | Other files／760.0 KB；可选第二行、整项点击、键盘和主题 |
+| 卡片 | `python examples/cards.py` | 应用条目、表情悬浮卡片、标题与分组设置 |
+| 折叠设置卡片 | `python examples/expandable_cards.py` | 混合／色度／锐化参数、平滑展开与收起、应用／重置、明暗主题与互斥展开 |
+| 日期选择器 | `python examples/date_picker.py` | 三列滚轮、空值、回填和日期范围；C优先，Python兼容 |
+| 时间选择器 | `python examples/time_picker.py` | 24／12小时制、AM／PM、独立滚轮、页内弹层和清空；C优先，Python兼容 |
+| 日历与日程 | `python examples/calendar_picker.py` | 单日、日期区间、日期时间、月／年视图、禁用端点、圆弧区间底色与平滑动画 |
+| 代码编辑器 | `python examples/code_editor.py` | 编辑 JSON，查看高亮与缩进引导 |
+| 消息浮层 | `python examples/toast.py` | 紧凑消息、带箭头消息、位置与动画 |
+| 顶部色条通知 | `python examples/color_toast.py` | 自定义颜色、标题／正文、操作按钮、宽度和六种位置；复用现有Toast堆叠动画 |
+| 消息条 | `python examples/info_bar.py` | 横向／纵向、状态背景、自定义控件、嵌入布局、任务进度；复用已有通知和ProgressBar |
+| 任务进度提示 | `python examples/progress_toast.py` | 四角定位、平滑进度、循环条、完成／失败和悬停暂停 |
+| 性能对照 | `python examples/text_performance.py` | 完整 1k／10k／50k 行 JSON，对照原始版本、Python 与 C |
+| 音符时间轴 | `python examples/note_timeline.py` | 单轨、多轨、空状态与进度演示 |
+
+Windows 也可使用 `examples/run_showcase.bat` 及对应组件的 `run_*.bat`。音符时间轴负责可视化，文件解析和声音播放由应用处理。
+
+新增输入接口用法见[前后缀与分格输入](docs/inputs.md)；角落提示支持底部向上、顶部向下堆叠和关闭后平滑补位。
+
+[顶部色条通知](docs/color-toast.md)提供成功、失败、警告、注意、信息及自定义颜色，支持操作按钮与顶部／底部居中。
+
+[消息条](docs/info-bars.md)补充状态背景、横纵排列和布局内嵌；原有吐司及进度控件继续复用。
+
+工作台“消息与对话框”采用统一的自定义测试界面：左侧实时预览，右侧修改内容，状态和位置通过下拉选择，进度用滑块调整，更多设置默认收起。嵌入示例与对话框在顶部页签切换，独立组件示例仍保留完整用例。
+
+接口与用法：[颜色与取色](docs/colors.md) · [按钮与菜单](docs/buttons.md) · [快捷键选择器](docs/shortcut-picker.md) · [任务进度提示](docs/progress-toast.md) · [拖放组件](docs/drag-drop.md) · [卡片](docs/cards.md) · [日期选择器](docs/date-picker.md) · [时间选择器](docs/time-picker.md) · [日历与日程](docs/calendar-picker.md) · [代码编辑器](docs/code-editor.md) · [音符时间轴](docs/note-timeline.md)
+
+## C 后端与性能
+
+Python 负责公开接口、Qt 交互和 C 绑定，C 扩展负责已接入的计算路径，目前包括：
+
+- **JSON 词元扫描与 UTF-16 位置映射**：供 `CodeEdit` 高亮使用，缺少扩展时可回退 Python。
+- **日期运算**：供 `DatePicker` 处理日历与日期范围。
+- **时间运算**：供 `TimePicker` 校验时／分、转换12／24小时制、计算独立滚轮和AM／PM候选。
+- **日历与日程**：供三种日历组件生成42格公历、限制与禁用策略、日期平移、区间端点规范化、日期时间夹紧和时分秒候选。
+- **拖放选择策略**：规范化后缀、过滤类型、批量去重和限制选择数量。
+- **快捷键策略**：组合合法性、修饰键顺序与占用冲突检查。
+- **颜色运算**：Hex 解析与格式化、RGB／HSV 转换，自动兼容缺少颜色接口的旧扩展；界面与屏幕采样由 Qt 处理。
+- **分格输入策略**：密码／验证码字符合法性、Unicode 分格和长度截断；Qt 输入与布局继续复用 LineEdit。
+
+以上路径均以C为首选加速实现，同时提供行为兼容的Python回退。旧版扩展缺少某组接口时，仅该组回退；仍然有效的C接口继续使用。
+
+启用 C 后端无需替换前端组件类名。可以查看编辑器实际使用的后端：
+
+```python
+from fluentpy import CodeEdit
+
+editor = CodeEdit()  # 在 QApplication 创建后使用
+editor.set_code('{"project": "FluentPy", "enabled": true}')
+print(editor.acceleration_backend())  # native 或 python
+```
+
+`FLUENTPY_BACKEND=auto`默认优先C并自动回退；`python`强制使用Python兼容实现；`native`明确要求C，在对应接口不可用时给出构建提示。这三种模式统一作用于文本、日期、时间、拖放和快捷键。`native_available()`检查二进制是否具备相应能力，组件的`acceleration_backend()`返回实际选择的`native`或`python`。详见[后端选择与回退](docs/backends.md)。
+
+以下为同一台 Windows x64 电脑、AMD Ryzen 9 9950X3D、CPython 3.13.1、Qt 6.11.1 的历史实测。10,000 行取五轮、50,000 行取三轮独立进程中位数，均处理完整输入。
+
+| 数据量 | 测量项目 | 原始版本 | C 后端 | 加速比 |
+| --- | --- | ---: | ---: | ---: |
+| 10,000 行 JSON | JSON 逐行扫描 | 25.28 ms | 1.91 ms | 13.21× |
+| 10,000 行 JSON | 完整载入与首帧 | 64.93 ms | 42.73 ms | 1.52× |
+| 50,000 行 JSON | JSON 逐行扫描 | 127.21 ms | 10.73 ms | 11.85× |
+| 50,000 行 JSON | 完整载入与首帧 | 292.60 ms | 180.12 ms | 1.62× |
+
+扫描的加速比只适用于扫描路径。文档创建、排版、绘制和交互仍有各自开销，整库不会因此获得相同倍数的提升。万行 JSON 应放入多行的 `CodeEdit`，而不是单行 `LineEdit`。
+
+[完整结果与测量方法](docs/performance.md) · [10k 原始报告](benchmarks/text-performance-10000.json) · [50k 原始报告](benchmarks/text-performance-50000.json) · [构建说明](docs/native-build.md)
+
+## 本地文档
+
+仓库附带中文文档站，提供分类组件目录、名称筛选、接口搜索与图标搜索。简介先展示实际组件示例程序，再用 JS 动画演示 Qt → FluentPy 输入框过渡以及 Python → C → Qt 的处理流程；支持暂停和重播。组件页将“示例与用法”和“API 参考”分开，代码与 GIF 按需展开，常见问题逐项阅读。网页跟随系统主题，组件媒体保持亮色。
+
+从仓库根目录启动静态服务：
+
+```powershell
+python -m http.server 8767 --bind 0.0.0.0 --directory sites/fluentpy-docs/dist
+```
+
+浏览器打开 [本地文档](http://127.0.0.1:8767/#/introduction)。也可双击 `sites/fluentpy-docs/启动本地文档.bat`；局域网设备使用服务器实际 IP 访问。重新生成接口和截图的方法见 [文档站说明](sites/fluentpy-docs/README.md)。
+
+文档网站的源码、完整静态页面和控件媒体也在独立的 [FluentPy-Docs](https://github.com/XDDXMT/FluentPy-Docs) 仓库以 MIT 许可公开。只预览或部署网站无需安装 Qt；重新提取 API 或录制控件时，通过 `FLUENTPY_SOURCE_ROOT` 指向本组件库源码。
+
+## 开发与验证
+
+```powershell
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+常规行为测试可在无C环境运行；完整C／Python差分测试需要当前解释器对应的C扩展。测试包含日期边界、缺失／不兼容／旧扩展的独立进程、实际录制与拖放、组件生命周期、快速导航和动画中断。构建原生／纯Python wheel和源码包的方法见[打包说明](docs/native-build.md)。
+
+| 目录 | 内容 |
+| --- | --- |
+| `src/fluentpy/` | Python 接口、Qt 控件、主题与 SVG 资源 |
+| `native/` | C文本、日期、时间、拖放与快捷键策略 |
+| `examples/` | 工作台与独立 Demo |
+| `docs/`、`sites/fluentpy-docs/` | Markdown 文档、图片与本地文档站 |
+| `tests/` | 正确性、生命周期与交互测试 |
+| `scripts/`、`benchmarks/` | 构建工具、性能复现脚本与报告 |
+
+后续后端运算以C作为首选加速实现，并维护可用的Python兼容路径；Python同时保持公开接口、绑定和Qt界面逻辑。扩展缺失不能导致组件不可用，详见[开发约定](AGENTS.md)。
+
+欢迎通过 [Issues](https://github.com/XDDXMT/FluentPy/issues) 提交问题与建议。使用场景可参考 [FluentMelody](https://github.com/XDDXMT/FluentMelody)。
+
+## 许可证与资源来源
+
+FluentPy 自身源码采用 **MIT**：允许使用、修改、分发和商用，保留版权声明与许可证文本即可；软件按原样提供。完整条款见 [LICENSE](LICENSE)。
+
+组件在本仓库独立实现。微软图标来自 [Microsoft Fluent UI System Icons](https://github.com/microsoft/fluentui-system-icons)，保留其 MIT 许可证与来源记录。Qt、PySide6 和可选 PyQt6 适配依赖分别遵循各自许可证。
+
+[第三方声明](THIRD_PARTY_NOTICES.md) · [图标许可证](licenses/Microsoft-Fluent-System-Icons-LICENSE.txt) · [图标来源](src/fluentpy/assets/icons/SOURCE.md) · [实现与许可边界](docs/licensing-boundaries.md)

fluentpy_qt-0.6.9/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,54 @@
+# Third-Party Notices
+
+## Table interaction reference
+
+- Reference: https://qfluentwidgets.com/zh/pages/components/tableview/
+- Usage: publicly visible table organization and interaction categories only (item/model interfaces, ordinary/rounded/lined rows and right-click selection).
+- FluentPy implements these independently using Qt's public model/view APIs, its existing controls, ActionMenu and theme tokens. No external source, stylesheet, screenshot, demonstration wording or data is included.
+
+## Fluent window interaction reference
+
+- Reference: https://qfluentwidgets.com/zh/pages/components/fluentwindow/
+- Usage: public window-organization and interaction categories only (page navigation, history, responsive layouts, settings placement and title-bar extension).
+- FluentPy implements these independently with its existing navigation and controls, ordinary Qt layouts, and Qt system move/resize APIs. Native window chrome remains the default; optional Windows frame-material requests keep the Qt client area opaque.
+- No source code, screenshots, stylesheets or example wording from this reference are included.
+
+## Slider and menu interaction references
+
+- References: https://qfluentwidgets.com/zh/pages/components/slider/ and https://qfluentwidgets.com/zh/pages/components/menu/
+- Usage: public interaction categories only. Slider and ActionMenu are extended independently; the new tooltip/range sliders and native tray menu use Qt APIs and the project's existing UI components.
+- No source code, screenshots, stylesheets or example wording from these references are included.
+
+## Combo box interaction reference
+
+- Reference: https://qfluentwidgets.com/zh/pages/components/combobox/
+- Usage: public interaction categories only (editable, model-backed, multiple, hierarchical, transparent and font choices).
+- FluentPy implements these independently using Qt models/views and its existing ActionMenu, inputs and buttons. No source code, stylesheets, screenshots or example text from this reference are included.
+
+FluentPy may use or adapt resources from third-party open-source projects only when their license is compatible with this project.
+
+## Microsoft Fluent UI System Icons
+
+- Source: https://github.com/microsoft/fluentui-system-icons
+- Copyright (c) 2020 Microsoft Corporation.
+- License: MIT; complete text in `licenses/Microsoft-Fluent-System-Icons-LICENSE.txt`.
+- Usage: bundled SVG icons for `IconButton`, examples, and future controls.
+- Bundled files: `src/fluentpy/assets/icons/ic_fluent_*_24_regular.svg` (107 icons).
+- Eyedropper: original Microsoft `assets/Eyedropper/SVG/ic_fluent_eyedropper_24_regular.svg`, bundled unchanged as `FluentIcon.EYEDROPPER`; download URL and checksum in `src/fluentpy/assets/icons/SOURCE.md`.
+- Music Note 2: original `assets/Music Note 2/SVG/ic_fluent_music_note_2_24_regular.svg` from the official Microsoft repository, bundled unchanged as `FluentIcon.MUSIC_NOTE_2`. Its pinned source and checksum are recorded in `src/fluentpy/assets/icons/SOURCE.md`.
+
+## Qt for Python
+
+Qt, PySide6 and the optional PyQt6 fallback are third-party dependencies. This source project does not vendor their binaries. Their own licenses apply separately; FluentPy's MIT license does not replace them.
+
+## Microsoft WinUI Gallery
+
+- Source: https://github.com/microsoft/WinUI-Gallery
+- License: MIT
+- Usage: reference for component gallery organization and Fluent control presentation patterns.
+
+## Microsoft WinUI
+
+- Source: https://github.com/microsoft/microsoft-ui-xaml
+- License: MIT
+- Usage: reference for WinUI control behavior, theme resources, and state model where individual files are covered by the repository license. Current reference: `controls/dev/CommonStyles/Button_themeresources.xaml`.