# ukui-quick-gallery

**Repository Path**: iaom/ukui-quick-gallery

## Basic Information

- **Project Name**: ukui-quick-gallery
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ukui-quick-gallery

`org.ukui.quick.items` 插件所携带 QML 控件的展示工具（gallery）。

对 14 个控件逐个展示，全部功能都可在界面上设置：

- DtThemeBackground、DtThemeScrollBar、TouchSlider、DtThemeText、
  DtThemeButton、IconButton、DtDropShadow、HoverButton、SearchLineEdit、
  KBallonTip、BorderlessButton、Icon、Tooltip（可创建的 `Tooltip`，不包含
  attached `ToolTip`）、LottieItem（随包内置 14 个 dotLottie 素材，经 qrc 提供给
  `LottieItem` 与 `Lottie` 附加属性展示）

## 界面

- 左侧：控件导航列表 + “Translucent window” 开关：窗口 `setColor(Qt::transparent)`，
  背景铺一层 `GlobalTheme.windowActive`，并由 `GalleryWindow`（继承
  `QQuickWindow`）内部的 `WindowProxy` 设置毛玻璃区域，透明度跟随主题，
  便于观察控件半透明效果
- 中间：舞台区，存放一个可自由交互的控件实例，背景为
  `GlobalTheme.windowActive`，随系统主题明暗自动切换
- 右侧：属性面板，即时生效；token 型属性只能从 GlobalTheme
  的 token 中选择，ShadowData 型属性只能选择 `kShadow*` token；
  方法型功能（如 `KBallonTip.popup()`）通过操作按钮触发；
  每页提供“恢复默认”，切换控件时编辑状态保留

## 国际化

界面文案为英文，随包安装中文翻译（`translations/ukui-quick-gallery_zh_CN.ts`
经 lrelease 生成 `.qm`，安装到 `/usr/share/ukui-quick-gallery/translations/`），
按系统 locale 自动加载。

## 构建

目录结构：

```
src/            C++ 入口 + GalleryWindow（QQuickWindow 子类，内部用
                ukui-quick 的 WindowProxy 设置毛玻璃区域）
qml/            主界面、单例（TokenLibrary/GallerySettings）、GalleryPage、PickerPanel
qml/editors/    属性编辑器组件
qml/pages/      14 个控件页
assets/lottie/  随包 dotLottie 动画素材（经 qrc 打包，供 LottieItem 页选择）
translations/   zh_CN 翻译
debian/         打包
```

依赖系统已安装的 ukui-quick（运行时 QML 模块
`qml-module-org-ukui-quick-items` / `qml-module-org-ukui-quick-platform`，
以及链接 `libukui-quick-platform`，开发包 `libukui-quick-dev`），
不链接 build-tree 中的库——gallery 的目标是展示“真实交付版本”的控件。

```
cmake -S . -B build
cmake --build build -j$(nproc)
./build/ukui-quick-gallery
```

deb 打包：

```
dpkg-buildpackage -us -uc -b
```

## 开发辅助

- `GALLERY_PAGE=<0..13>`：启动时直接跳到指定控件页
- `GALLERY_SCREENSHOT=<path.png>`：启动 1.5 秒后抓取窗口图像并退出
- `GALLERY_TRANSLUCENT=1`：启动时打开“Translucent window”
- `GALLERY_TRANSLATIONS=<dir/>`：从指定目录加载翻译（.qm）