# qt-libui

**Repository Path**: slamdd/qt-libui

## Basic Information

- **Project Name**: qt-libui
- **Description**: qt控件封装吧
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# qt-libui

Qt5 自绘通用控件库：滑块开关、环形/扇区菜单、启动画面、进度条族
（圆环 / 圆点 / 沙漏 / 水球）、可换装的标签栏外观（Chrome / Firefox /
Liquid 等 9 种），外加两种应用级样式方案：QSS 样式底座
（`ApplyStyleSheet`：base 层样式表与少量箭头图标随库内置，项目层由
调用方传入）与自绘 QStyle 风格 `MetalIndustrialStyle`（金属工业风，
整套控件原生绘制，无平台样式兜底）。只依赖 `Qt5::Widgets`，不携带
业务逻辑。

源自 `qt-cmake-base-env` 模板的 `src/libui`，作为独立库抽出。

## 构建

需要 CMake ≥ 3.16（多配置 preset 需 ≥ 3.17）与 Qt5（Widgets 组件）。

**Windows 一键**（自动定位 VS2019、配置、编译、安装）：

```bat
scripts\build_ninja.bat            :: 默认 Debug (x64)，装到 dist\x64
scripts\build_ninja.bat release    :: 指定配置：debug / relwithdebinfo / release
scripts\build_ninja.bat -a x86     :: 32 位
scripts\build_ninja.bat -h         :: 全部参数
```

Qt 路径由仓库根的 `local.cmake` 提供。该文件不入库：首次 configure 时按
`cmake/template/local.cmake.in` 生成占位内容并停下，按提示填入本机 Qt 安装路径后
重跑即可（也可改用 `-DCMAKE_PREFIX_PATH`）。脚本走多配置 preset：构建目录
`build/ninja-multi-<arch>`，三种配置合并安装到 `dist/<arch>`（Debug 库带
`d` 后缀、RelWithDebInfo 带 `rd`、Release 无后缀）；单配置 preset
（`ninja-<type>-<arch>`）保留给手工细粒度构建，仍各装 `dist/<arch>-<BuildType>`。

**标准 CMake 方式**（Linux/macOS 或不想用脚本时）：

```bash
cmake -B build -G Ninja -DCMAKE_PREFIX_PATH=<Qt 安装路径>
cmake --build build
cmake --install build --prefix <安装前缀>
```

目录布局：公共头文件在 `include/qt-libui/`（子目录与 `src/` 镜像），
源文件在 `src/`。默认产出共享库，加 `-DBUILD_SHARED_LIBS=OFF` 产出
静态库（Windows 上 DLL 装 `bin/`，导入库装 `lib/`）。

示例程序：`libui_gallery` 演示全部部件，`just_for_fun`（半色调终端
艺术）演示 `ApplyStyleSheet` 的项目层用法，`metal_style` 是
`MetalIndustrialStyle` 的全应用眼验靶场。构建产物在
`build/bin/<配置>/`（Windows 用各自目录下生成的 `run_*.bat` 启动，
它会设置 Qt DLL 路径）。

## 作为 submodule 使用

本库可被其它 CMake 工程以 git submodule + `add_subdirectory` 内嵌，与宿主
一起编译。此时本库只提供 `qt-libui::libui` 目标，其余一概交给宿主：

- 不读 `local.cmake`（Qt 已由宿主项目找到，再读本机路径只会覆盖宿主的 `Qt5_DIR`）
- 不编 gallery 示例（`BUILD_EXAMPLES` 的默认值就是「仅顶层构建时 ON」）
- 不登记任何 install/export 规则（否则静态库与头文件会混进宿主的安装目录，
  且导出清单里会出现宿主构建目录下不存在的文件，打包会失败）

宿主侧：

```cmake
add_subdirectory(external/qt-libui)
target_link_libraries(my_app PRIVATE qt-libui::libui)
```

引用公共头文件仍写 `#include <qt-libui/buttons/switch_button.h>`：构建树的
`include/` 已通过 `$<BUILD_INTERFACE:...>` 暴露，与安装树写法一致。

## 安装与消费

```bash
cmake --install build --prefix <安装前缀>
```

消费方通过标准 CMake 包引用：

```cmake
find_package(qt-libui CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE qt-libui::libui)
```

```cpp
#include <qt-libui/buttons/switch_button.h>
```

静态与共享两种安装树用法一致：导出目标自动携带
`LIBUI_STATIC_DEFINE` 等必要定义，消费方无需关心差异。

同一安装树内 Debug / RelWithDebInfo / Release 三种配置并存（库文件名靠
`d` / `rd` 后缀 / 无后缀区分）：`find_package` 之后 CMake 按消费方自己的
构建配置自动选中对应的那一份，无需任何额外设置。

## 与消费方的契约

- `SplashScreen` 的 logo 不由库提供，调用 `setLogo(const QIcon&)` 传入
- `SplashScreen` 各子控件的 objectName（`splashContent` / `splashLogo` /
  `splashTitle` / `splashStatus` / `splashProgressBar`）供消费方 QSS 定位。
  这是跨仓契约：改名会让消费方样式静默失效
- `ApplyStyleSheet` 的底座层占用的资源前缀（`:/resources/styles/base/...`
  与 `:/resources/icons/svg/...`）消费方不要撞；调用它还会把应用字体设为
  Microsoft YaHei，不想要这个副作用就自己读 QSS 装载
- `MetalIndustrialStyle` 用法：`app.setStyle(new MetalIndustrialStyle)`
  之后接 `app.setPalette(QApplication::style()->standardPalette())`；
  其 `polish()` 会给所有控件开 `WA_Hover`（悬停效果依赖
  `State_MouseOver`），消费方无需自行设置