1. 初识AWTK

本章导读：

随着手机、智能手表等便携式设备的普及，用户对GUI的要求越来越高，嵌入式系统对GUI的需求也越来越迫切，本章将为大家介绍一个轻型、占用资源少、高性能、高可靠、便于移植、可配置及美观的GUI编程框架。

1.1 简介

AWTK全称为Toolkit AnyWhere，是ZLG倾心打造的一套基于C语言开发的GUI框架。旨在为用户提供一个功能强大、高效可靠、简单易用、可轻松做出炫酷效果的GUI引擎，并支持跨平台同步开发，一次编程，终生使用。

1.2 跨平台

AWTK目前支持的平台如下：

• 桌面操作系统：

Windows、Linux、macOS

• 嵌入式操作系统：

AWorksOS、嵌入式 Linux、RT-Thread、TencentOS、FreeRTOS、SylixOS、MS-RTOS。

想进一步了解，AWTK支持的平台与芯片请看：awtk_ecology.md (opens new window)

1.3 特色

1. 高效。采用脏矩形裁剪算法，每次只绘制和更新变化的部分，极大提高运行效率。
2. 稳定。通过良好的架构设计、编程风格、单元测试、动态（valgrind）检查和Code Review保证其运行的稳定性。
3. 丰富的GUI组件。提供窗口、对话框和各种常用的组件（用户可以配置自己需要的组件，降低对运行环境的要求）。
4. 支持多种字体格式。内置位图字体（并提供转换工具），也可以使用stb_truetype或freetype加载ttf字体。
5. 支持多种图片格式。内置位图图片（并提供转换工具），也可以使用stb_image加载png/jpg等格式的图片。
6. 支持裸系统，无需OS和文件系统。字体、图片、窗体样式和界面描述数据都编译到代码中，以常量数据的形式存放，运行时无需加载到内存。
7. 内置nanovg实现高质量的矢量动画。
8. 支持窗口动画、控件动画、滑动动画和高清LCD等现代GUI常见特性。
9. 支持国际化（Unicode、字符串翻译和输入法等）。
10. 可移植。支持移植到各种RTOS和嵌入式Linux系统，并通过SDL在各种流行的PC/手机系统上运行。
11. 支持硬件2D加速（目前支持STM32的DMA2D和NXP的PXP）和GPU加速（OpenGL/OpenGLES/DirectX/Metal），充分挖掘硬件潜能。
12. 采用LGPL协议开源发布，在商业软件中使用时无需付费。

1.4 环境搭建

本章节将向大家介绍如何在本地搭建AWTK开发环境。

1.4.1 Windows（x64）

在Windows平台需要安装的软件有：Python（x64版本>=2.7）、Scons（版本>=3.0.0）、Node.js（版本>=10.0.0）和Visual Studio C++（版本>=2015）。需要安装好Python后才能安装SCons。

（1）安装Python时，需要将Python的安装路径添加到系统环境变量，如下图所示，其他按缺省步骤操作。下载 python-3.8.2-amd64.exe (opens new window)。

图1.1 安装Python

（2）下载SCons源码安装包，下载完成后解压并在解压目录打开终端，并执行以下命令，完成安装。下载 SCons-4.3.0.zip (opens new window)。

python setup.py install

如果是安装Visual Studio 2019，需要安装SCons（版本>=3.1.0）。

（3）安装Node.js时，安装程序会自动将Node.js的安装路径添加到系统环境变量，如下图所示，用户只需按缺省步骤操作即可。下载 node-v12.18.1-x64.msi (opens new window)。

图1.2 安装Node.js

（4）安装Visual Studio

• 如果安装的是Visual Studio 2015，请选择自定义安装，然后选择Visual C++，详见下图，其他按缺省步骤操作。

图1.3 安装Visual Studio 2015

• 如果安装的是Visual Studio 2019，安装时请勾选"使用C++的桌面开发"，如下图所示，其他按缺省步骤操作。

图1.4 安装Visual Studio 2019

1.4.2 Linux（x64）

下面以Ubuntu（版本>=16）为例，如果没有安装SCons和其他依赖的软件包，请在终端运行下面的命令：

sudo apt-get install gcc g++ scons
sudo apt-get install libsndio-dev libgtk-3-dev libglu1-mesa 
sudo apt-get install libglu1-mesa-dev libgl1-mesa-glx
sudo apt-get install libgl1-mesa-dev libasound2-dev 
sudo apt-get install libibus-1.0-dev fcitx-libs-dev git vim
sudo apt-get install clang-format libharfbuzz-dev nodejs libreadline-dev

1.4.3 macOS

如果没有安装SCons和SDL2，请在终端运行下面的命令（假定已安装Brew）：

brew install scons sdl2

1.5 编译构建

1.5.1 下载AWTK

在AWTK官网可下载：最新源码、AWTK Designer界面设计器、入门指南与手册、演示例子以及整合发布包等，下载地址如下：

• AWTK官网 (opens new window)：找到资源下载专栏。
• AWTK的VS工程（基于CMake） (opens new window)

下载AWTK源码的时候，不要保存含有中文的路径。另外，如果从github使用"Download ZIP"的方式下载上面的源码，下载的zip文件夹会包含"-master"；如果是这种情况，在解压后请将"-master"去掉，如：将"awtk-master"重命名"awtk"。

1.5.2 编译AWTK

在编译AWTK之前请参考本章1.4的内容，确认已在对应平台上搭建好开发环境，然后下载好AWTK源码后，就可以编译AWTK了，在awtk根目录下打开终端，执行以下命令：

scons

检查Windows下是否已经正确安装Python、SCons和Visual Studio C++相应的版本，请运行AWTK Designer（下载地址请看1.5.1）安装目录下的：Tools/awtk-tools-checker.exe。

1.6 运行示例

AWTK源码中内置了示例程序（demoui），该示例程序演示了AWTK中各个控件及其基本功能的效果，编译源码成功后，可运行awtk/bin/demoui示例，此处以Windows平台为例，在awtk根目录下打开终端，执行以下命令，运行效果下图右侧所示。

bin\demoui.exe

图1.5 demoui所在目录及其运行效果

demoui示例仅做功能展示，其源文件位于awtk/demos/demo_ui_app.c。各个控件的具体用法请参考示例程序 awtk-c-demos (opens new window)。

1.7 AWTK目录

编译AWTK源码后目录如下图所示，其中bin目录和lib目录是编译后新增的，具体说明详见下表。

图1.6 AWTK目录结构

目录/文件	说明
3rd	AWTK使用的第三方库目录
bin	编译AWTK后生成的可执行文件，包括动态链接库（awtk.dll）、示例程序和内置工具
demos	AWTK内置示例程序的代码目录，代码文件对应的示例程序详见目录下的README.md
design	使用AWTK Designer设计demoui所用的资源目录（AWTK Designer详见2.3.2）
dllexports	AWTK动态链接库（awtk.dll）导出表
docs	AWTK帮助文档目录
lib	编译AWTK后生成的静态链接库
res	demoui资源文件目录
scripts	AWTK工具脚本目录，具体使用说明请查阅该目录下的README.md
src	AWTK源代码
staticcheck	静态代码检查，具体说明请查阅该目录下的README.md
tests	AWTK的单元测试代码目录
tools	AWTK内置工具的源代码目录
valgrind	AWTK用于检查内存泄漏的valgrind工具
win32_res	AWTK应用程序在Windows下的图标资源
awtk_config.py	AWTK配置文件，配置方法详见1.8
build.json	特殊平台（Web、Android、IOS）编译配置文件，具体用法请查阅docs/build_config.md
project.json	demoui的项目配置文件，可使用AWTK Designer打开该项目文件做界面设计
README.md	AWTK介绍文档（英文版）
README_zh.md	AWTK介绍文档（中文版）
SConstruct	SCons脚本

AWTK Designer的具体用法请参阅其安装目录下Docs文件夹中的《AWTK Designer用户手册》，下载地址本文 1.5.1。

AWTK的示例程序主要是awtk/bin目录中以demo开头的可执行程序，比如demoui、demotr等。AWTK的内置工具源代码位于awtk/tools，编译后的可执行程序位于awtk/bin，这些工具主要用于生成资源文件，比如xml_to_ui，该工具可将程序界面的xml文件打包生成二进制的bin文件，相关工具详见3.4.2。

1. 上表中的目录下通常都有一个README.md文档，该文档通常包含目录的说明和具体的使用方法。
2. awtk/docs/README.md文档包含了docs目录下AWTK帮助文档的具体说明。
3. awtk/docs/changes.md文档包含了AWTK的最新动态。

1.8 配置文件

在AWTK目录下有个awtk_config.py文件（被SConstruct引用），在这个文件中可以通过定义不同含义的宏实现不同的效果，接下来介绍一些常用的宏及其说明。

1. 修改awtk_config.py文件后，需要重新编译awtk，编译方法请看1.5.2。
2. 修改awtk_config.py文件只在Windows、Linux、macOS平台有效果，在嵌入式平台无效。

1.8.1 渲染模式选择

AWTK支持多种渲染模式，不同的渲染模式适用于不同的硬件平台，显示效果也略有不同。比如：PC操作系统平台Windows、Linux、macOS可以使用OpenGL模式，而普通嵌入式平台则可以使用AGGE模式。通过修改awtk_config.py文件中的渲染模式变量，可以在PC上模拟在不同的渲染模式时应用的运行效果。

常见的渲染模式如下：

• GL3/GLES2/GLES3：基于OpenGL/GLES实现（nanovg内置），由宏WITH_NANOVG_GL决定。适合支持OpenGL硬件加速的平台（比如：Windows、Linux、macOS）使用
• AGGE：基于agge实现。纯软件实现，渲染效果一般，由宏WITH_NANOVG_AGGE决定。适合没有GPU的嵌入式平台使用

awtk_config.py文件中渲染模式变量代码如下：

# awtkawtk_config.py
...
VGCANVAS='NANOVG'
if OS_NAME == 'Windows':
  TK_ROOT=TK_ROOT.replace('\\', '\\\\');
  NANOVG_BACKEND='GLES2'
else:
  NANOVG_BACKEND='GL3'

#VGCANVAS='CAIRO'
#NANOVG_BACKEND='GLES2'
#NANOVG_BACKEND='GLES3'
#NANOVG_BACKEND='AGG'
#NANOVG_BACKEND='BGFX'
#NANOVG_BACKEND='AGGE'
...

当VGCANVAS='NANOVG'时，对于常用的AGGE和OpenGL渲染模式又可以细分为下面几种：

(1) AGGE

• AGGE-BGR565：表示运行时绘图使用AGGE引擎，LCD Frame Buffer的格式为BGR565。
• AGGE-BGRA8888：表示运行时绘图使用AGGE引擎，LCD Frame Buffer的格式为BGRA8888。
• AGGE-MONO：表示运行时绘图使用AGGE引擎，LCD Frame Buffer的格式为MONO（黑白）。

它们在awtk_config.py中的参数设置如下：

# 使用 AGGE 渲染模式
NANOVG_BACKEND='AGGE'
# 基于 Frame Buffer 实现彩色 LCD（BGR565或BGRA8888格式使用该参数）
LCD='SDL_FB'

# 基于 Frame Buffer 实现黑白 LCD（MOMO格式使用该参数）
# LCD='SDL_FB_MONO'


# FRAME_BUFFER_FORMAT='bgr565'   # 帧缓冲颜色格式为 BGR565
# FRAME_BUFFER_FORMAT='bgra8888' # 帧缓冲颜色格式为 BGRA8888

(2) OpenGL

• OpenGL-GLES2：表示运行时绘图使用GLES2引擎，建议在Windows平台使用。
• OpenGL-GL3：表示运行时绘图使用GL3引擎，建议非在Windows平台使用。

它们在awtk_config.py中的参数设置如下：

NANOVG_BACKEND='GLES2'  # 使用 OpenGL-GLES2 渲染模式
# NANOVG_BACKEND='GL3'  # 使用 OpenGL-GL3 渲染模式

LCD='SDL_GPU'  # 基于 GPU 实现 LCD

1.8.2 是否支持png/jpeg图片

如果要支持png/jpeg图片，请定义宏WITH_STB_IMAGE，可以使用下面两种方式加载图片：

（1）有文件系统：即同时定义了宏WITH_FS_RES，AWTK会通过读取文件方式直接读取assets/default/raw/images目录下的原始png/jpeg图片。

（2）无文件系统：即没有定义宏WITH_FS_RES，AWTK会使用assets/default/inc/images目录下"*.res"文件（res文件是未经解码的原始png/jpeg文件数据）

假如宏WITH_FS_RES和WITH_STB_IMAGE都没有定义，则使用assets/inc/images目录下"*.data"文件（data文件是png/jpeg解码后的位图数据）。

1.8.3 是否使用点阵字体

程序默认启用宏WITH_STB_FONT，即使用TrueType字体。如果需要使用点阵字体请定义宏WITH_BITMAP_FONT，一般只在RAM极小时，且需要支持预先解码的图片，才启用本宏。

1.8.4 是否启用软键盘

如果应用程序不需要弹出软键盘，请定义宏WITH_NULL_IM。如果需要使用输入法，请看第7章。

1.8.5 是否启用中文输入法

如果应用程序不需要中文输入法，但又需要软键盘，请定义宏WITH_IME_NULL。

1.8.6 是否启用联想功能

如果启用了软键盘，但不想启用联想功能，请定义宏WITHOUT_SUGGEST_WORDS。

1.8.7 是否有标准的内存分配函数

如果有标准的malloc/free/calloc等函数，请定义本宏HAS_STD_MALLOC。否则将由AWTK自己管理动态内存，如果系统提供了标准的malloc函数建议打开此项。

1.8.8 是否支持文件系统

有文件系统：即在awtk_config.py文件中定义了宏WITH_FS_RES，AWTK将加载应用程序default/raw目录下的资源文件（字体、图片、窗体样式和界面描述数据等），运行应用程序时，依赖default/raw目录下的资源文件。代码如下：

# awtk/awtk_config.py
...
COMMON_CCFLAGS=COMMON_CCFLAGS+' -DWITH_ASSET_LOADER -DWITH_FS_RES -DWITH_ASSET_LOADER_ZIP ' 
...

**无文件系统：即在awtk_config.py文件中没有定义宏WITH_FS_RES，**就无需OS和文件系统，AWTK将加载应用程序default/inc目录下的资源文件，AWTK将这些资源编译到代码中，以常量数据的形式存放，嵌入到固件中，运行应用程序时，无需加载这些资源文件。

1.8.9 是否在嵌入式系统运行

默认程序入口是WinMain()或main()，如果应用程序是在嵌入式系统运行的话，请定义宏USE_GUI_MAIN，这种情况下程序入口点变为gui_app_start()，具体可以看示例HelloWorld.Xml-Demo/src/app_main.c文件。

更多的宏说明请看： awtk/docs/porting_common.md。