# awtk-zig

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

## Basic Information

- **Project Name**: awtk-zig
- **Description**: AWTK-Zig 是一个建立在 AWTK GUI 之上用 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-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AWTK-Zig-Example

## Project Overview

AWTK-Zig-Example is a Zig language example project based on the AWTK (Awesome Toolkit) GUI framework. AWTK is a powerful cross-platform GUI framework, and this project demonstrates how to develop AWTK applications using the Zig language.

## Project Structure

```
awtk-zig-example/
├── build.zig              # Zig build configuration
├── build.zig.zon          # Zig package management configuration
├── src/
│   ├── main.zig           # Program entry point
│   └── root.zig           # Root component definition
├── scripts/               # Utility scripts
│   ├── update_res.py      # Resource generation tool
│   ├── release.py         # Release script
│   ├── awtk_locator.py    # AWTK locator tool
│   ├── app_helper.py      # Application helper tool
│   └── *.sh               # Linux utility scripts
└── design/                # Design resources
    ├── data/              # Data files
    ├── fonts/             # Font files
    ├── images/            # Image resources
    ├── strings/           # String resources
    ├── styles/            # Style definitions
    └── ui/                # UI layout files
```

## Key Features

- **Cross-platform GUI Development**: Built on the AWTK framework, supporting multiple operating systems
- **Zig Language Integration**: Demonstrates seamless integration between Zig and AWTK
- **Comprehensive Resource Management**: Includes a complete resource system for fonts, images, strings, styles, etc.
- **Multi-resolution Support**: Supports image resources in x1, x2, x3, and x4 resolutions
- **Multi-theme Support**: Configurable themes and styles

## Technology Stack

- **Programming Language**: Zig
- **GUI Framework**: AWTK
- **Build Tool**: Zig Build System
- **Resource Formats**:
  - Fonts: TTF / Font configuration files
  - Images: PNG format (multi-resolution)
  - Data: JSON, ANY, DAT, etc.
  - UI: XML layout files

## System Requirements

- Zig compiler (recommended latest stable version)
- AWTK SDK
- Python 3.x (required for resource generation tools)
- Linux / Windows / macOS operating system

## Quick Start

### 1. Install Dependencies

```bash
# Install Zig compiler
# Download and install from https://ziglang.org/download/

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

### 2. Configure Project

```bash
# Set AWTK path environment variable
export AWTK_ROOT=/path/to/awtk
```

### 3. Build Project

```bash
# Build with Zig
zig build

# Or build in release mode
zig build -Drelease=true
```

### 4. Run Application

```bash
# Run debug version
zig build run

# Run release version
zig build run -Drelease=true
```

## Resource Management

### Resource Generation Tool

The project provides a powerful resource generation tool located at `scripts/update_res.py`.

```bash
# Generate all resources
python scripts/update_res.py

# Generate specific resource types
python scripts/update_res.py --type string    # String resources
python scripts/update_res.py --type font      # Font resources
python scripts/update_res.py --type image     # Image resources
python scripts/update_res.py --type ui        # UI layouts
python scripts/update_res.py --type style     # Style resources
```

### Resource Structure

- **Font Resources**: `design/default/fonts/` — Contains various font files
- **Image Resources**: `design/default/images/` — Organized by resolution
- **UI Layouts**: `design/default/ui/` — Interface definitions in XML format
- **Style Definitions**: `design/default/styles/` — UI style configurations
- **String Resources**: `design/default/strings/` — Multi-language string support

## Project Configuration

### AWTK Path Configuration

The project automatically locates the AWTK SDK path. Alternatively, configure it manually:

```python
# scripts/awtk_locator.py
def getAwtkRoot():
    # Custom logic to locate AWTK path
    pass
```

### Release Configuration

Use `scripts/release.py` to perform project releases:

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

## Core Components

### src/main.zig

The program entry point, responsible for initializing the AWTK framework and launching the application.

### src/root.zig

The root component definition, containing the main UI structure and application logic.

### scripts/app_helper.py

An application helper tool providing dependency management and preparation functions.

## UI Components

The project includes multiple predefined UI layouts:

- `win_main.xml` — Main window
- `win_edit_user.xml` — User edit window
- Multiple keyboard layouts (`kb_ascii`, `kb_default`, `kb_float`, etc.)

## Development Guide

### Adding New Resources

1. Place resource files into the corresponding `design/default/` subdirectory
2. Run the resource generation tool to update resources
3. Reference the new resources in your code

### Customizing Styles

Edit the style files under `design/default/styles/` to define new UI themes.

### Extending Functionality

Easily extend project functionality based on existing scripts:

```python
# Add custom resource processing logic in update_res.py
def on_generate_res_before(res_type):
    # Logic executed before resource generation
    pass
```

## Contribution Guide

Contributions of code and resources are welcome:

1. Fork this repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Create a Pull Request

## License

This project follows the license agreements associated with AWTK.

## Contact

- Project URL: https://gitee.com/ufbycd/awtk-zig-example
- AWTK Official Website: https://awtk.zlg.cn

## References

- [AWTK Documentation](https://awtk.zlg.cn/docs/)
- [Zig Language Official Site](https://ziglang.org/)
- [AWTK GitHub](https://github.com/zlgopen/awtk)

---

**Note**: Ensure the AWTK environment variable is correctly configured and all required dependencies are installed before building and running the project.