# 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-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# qt-libui

Qt5 自绘通用控件库：滑块开关、环形/扇区菜单、启动画面、进度条族
（圆环 / 圆点 / 沙漏 / 水球）与可换装的标签栏外观（Chrome / Firefox /
Liquid 等 9 种）。只依赖 `Qt5::Widgets`，不携带业务逻辑与资源文件。

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

## 构建

需要 CMake ≥ 3.16 与 Qt5（Widgets 组件）。

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

```bat
scripts\build_ninja.bat            :: 默认 debug (x64)，产物装到 dist\x64-Debug
scripts\build_ninja.bat release    :: 指定构建类型
scripts\build_ninja.bat -t release -s   :: 构建共享库
scripts\build_ninja.bat -a x86     :: 32 位
scripts\build_ninja.bat -h         :: 全部参数
```

Qt 路径由仓库根的 `local.cmake` 提供。该文件不入库：首次 configure 时按
`cmake/local.cmake.in` 生成占位内容并停下，按提示填入本机 Qt 安装路径后
重跑即可（也可改用 `-DCMAKE_PREFIX_PATH`）。构建目录 `build/<preset>`、
安装目录 `dist/<arch>-<BuildType>` 均由 `CMakePresets.json` 定义。

**标准 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=ON` 产出
共享库（Windows 上 DLL 装 `bin/`，导入库装 `lib/`）。

示例程序 `libui_gallery` 演示全部部件，构建产物在 `build/bin/`
（Windows 用生成的 `run_gallery.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` 等必要定义，消费方无需关心差异。

## 与消费方的契约

- `SplashScreen` 的 logo 不由库提供，调用 `setLogo(const QIcon&)` 传入
- `SplashScreen` 各子控件的 objectName（`splashContent` / `splashLogo` /
  `splashTitle` / `splashStatus` / `splashProgressBar`）供消费方 QSS 定位。
  这是跨仓契约：改名会让消费方样式静默失效