# awtk-zig

**Repository Path**: ufbycd/awtk-zig

## Basic Information

- **Project Name**: awtk-zig
- **Description**: 在Zig中快速使用AWTK，使用Zig的匿名结构体来描述UI，实现便快捷的方式来生成图形界面。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-18
- **Last Updated**: 2026-02-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# AWTK-Zig-Example

## 项目简介

AWTK-Zig-Example 是一个基于 AWTK (Awesome Toolkit) GUI 框架的 Zig 语言示例项目。AWTK 是一个强大的跨平台 GUI 框架，本项目展示了如何使用 Zig 语言来开发 AWTK 应用程序。

## 项目结构

```
awtk-zig-example/
├── build.zig              # Zig 构建配置
├── build.zig.zon          # Zig 包管理配置
├── src/
│   ├── main.zig           # 程序入口点
│   ├── root.zig           # 根组件定义
│   └── zawtk.zig          # AWTK 绑定封装
├── scripts/               # 工具脚本
│   ├── update_res.py      # 资源生成工具
│   ├── release.py         # 发布脚本
│   ├── awtk_locator.py    # AWTK 定位工具
│   ├── app_helper.py      # 应用辅助工具
│   └── *.sh               # Linux 工具脚本
└── design/                # 设计资源
    ├── data/              # 数据文件
    ├── fonts/             # 字体文件
    ├── images/            # 图片资源
    ├── strings/           # 字符串资源
    ├── styles/            # 样式定义
    └── ui/                # UI 布局文件
```

## 主要功能

- **跨平台 GUI 开发**: 基于 AWTK 框架，支持多种操作系统
- **Zig 语言集成**: 展示 Zig 与 AWTK 的完美结合
- **完整资源管理**: 包含字体、图片、字符串、样式等完整资源体系
- **多分辨率支持**: 支持 x1、x2、x3、x4 四种分辨率的图片资源
- **多主题支持**: 可配置不同的主题和样式

## 技术栈

- **编程语言**: Zig
- **GUI 框架**: AWTK
- **构建工具**: Zig Build System
- **资源格式**: 
  - 字体: TTF/字体配置文件
  - 图片: PNG 格式 (多分辨率)
  - 数据: JSON、ANY、DAT 等格式
  - UI: XML 布局文件

## 环境要求

- Zig 编译器 (建议最新稳定版)
- AWTK SDK
- Python 3.x (用于资源生成工具)
- Linux/Windows/macOS 操作系统

## 快速开始

### 1. 安装依赖

```bash
# 安装 Zig 编译器
# 访问 https://ziglang.org/download/ 下载并安装

# 安装 AWTK SDK
git clone https://github.com/zlgopen/awtk.git
```

### 2. 配置项目

```bash
# 设置 AWTK 路径环境变量
export AWTK_ROOT=/path/to/awtk
```

### 3. 构建项目

```bash
# 使用 Zig 构建
zig build

# 或者使用发布模式构建
zig build -Drelease=true
```

### 4. 运行程序

```bash
# 运行调试版本
zig build run

# 运行发布版本
zig build run -Drelease=true
```

## 资源管理

### 资源生成工具

项目提供了强大的资源生成工具，位于 `scripts/update_res.py`。

```bash
# 生成所有资源
python scripts/update_res.py

# 生成特定类型资源
python scripts/update_res.py --type string    # 字符串资源
python scripts/update_res.py --type font      # 字体资源
python scripts/update_res.py --type image     # 图片资源
python scripts/update_res.py --type ui        # UI 布局
python scripts/update_res.py --type style     # 样式资源
```

### 资源结构

- **字体资源**: `design/default/fonts/` - 包含各种字体文件
- **图片资源**: `design/default/images/` - 按分辨率组织
- **UI 布局**: `design/default/ui/` - XML 格式的界面定义
- **样式定义**: `design/default/styles/` - 界面样式配置
- **字符串资源**: `design/default/strings/` - 多语言字符串支持

## 项目配置

### AWTK 路径配置

项目会自动查找 AWTK SDK 路径，也可通过以下方式配置：

```python
# scripts/awtk_locator.py
def getAwtkRoot():
    # 自定义 AWTK 路径获取逻辑
    pass
```

### 发布配置

使用 `scripts/release.py` 进行项目发布：

```bash
python scripts/release.py
```

## 主要组件

### src/main.zig

程序入口点，负责初始化 AWTK 框架并启动应用程序。

### src/root.zig

根组件定义，包含应用程序的主要界面结构和逻辑。

### src/zawtk.zig

AWTK 绑定封装，提供 Zig 语言与 AWTK 框架的接口绑定。

### scripts/app_helper.py

应用辅助工具，提供项目依赖管理和准备工作功能。

## UI 组件

项目包含多种预定义的 UI 布局：

- `win_main.xml` - 主窗口
- `win_edit_user.xml` - 用户编辑窗口
- 多种键盘布局 (`kb_ascii`, `kb_default`, `kb_float`, `kb_hex`, `kb_int`, `kb_phone`, `kb_ufloat`, `kb_uint`)
- `system_bar.xml` - 系统状态栏

## 开发指南

### 添加新资源

1. 将资源文件放入对应的 `design/default/` 子目录
2. 运行资源生成工具更新资源
3. 在代码中引用新资源

### 自定义样式

编辑 `design/default/styles/` 下的样式文件，定义新的界面风格。

### 扩展功能

基于现有的脚本工具，可以轻松扩展项目功能：

```python
# 在 update_res.py 中添加自定义资源处理逻辑
def on_generate_res_before(res_type):
    # 资源生成前的处理逻辑
    pass
```

## 贡献指南

欢迎贡献代码和资源：

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 许可证

本项目遵循 AWTK 相关的许可证协议。

## 联系方式

- 项目地址: https://gitee.com/ufbycd/awtk-zig-example
- AWTK 官网: https://awtk.zlg.cn

## 参考资源

- [AWTK 文档](https://awtk.zlg.cn/docs/)
- [Zig 语言官网](https://ziglang.org/)
- [AWTK GitHub](https://github.com/zlgopen/awtk)

---

**注意**: 确保在构建和运行项目前正确配置 AWTK 环境变量，并安装所有必要的依赖项。