使用 CmakeApp 模板创建 SOUI 应用¶

Warning

The current page still doesn't have a translation for this language.

You can read it through google translate.

本教程将指导您如何使用 CmakeApp 模板创建新的 SOUI5 应用程序。CmakeApp 是一个基于 CMake 构建系统的 SOUI5 应用模板，支持跨平台开发。

模板概述¶

CmakeApp 模板提供了一个完整的 SOUI5 应用程序结构，包括：

基于 CMake 的跨平台构建系统
标准的 SOUI5 应用程序框架
资源文件组织结构
预配置的编译选项

准备工作¶

环境要求¶

CMake 3.16 或更高版本
支持的编译器：
Windows: Visual Studio 2015 或更高版本
Linux: GCC 7.0 或 Clang 5.0 或更高版本
macOS: Xcode 10 或更高版本
SOUI5 开发环境：
已安装 SOUI5 库和头文件（ninja install）
正确设置环境变量

环境变量配置¶

在使用 CmakeApp 模板之前，需要设置以下环境变量：

Windows¶

# 32位系统
set SOUI4_INSTALL_32=C:\soui4_install

# 64位系统
set SOUI4_INSTALL_64=C:\soui4_install

Linux/macOS¶

export SOUI4_INSTALL=/path/to/soui4_install

使用模板创建项目¶

1. 复制模板文件¶

首先，将 CmakeApp 目录复制为您的新项目：

# 复制模板到新项目目录
cp -r CmakeApp MyNewProject
cd MyNewProject

2. 项目结构说明¶

复制后的项目结构如下：

MyNewProject/
├── CMakeLists.txt          # CMake 构建配置
├── MainDlg.h               # 主对话框头文件
├── MainDlg.cpp             # 主对话框实现
├── Soui5Wizard.cpp         # 应用程序入口点
├── stdafx.h                # 预编译头文件
├── stdafx.cpp              # 预编译头实现
├── resource.h              # 资源头文件
├── readme.txt              # 项目说明文件
├── uires/                  # UI 资源目录
│   ├── uires.idx           # 资源索引文件
│   ├── xml/                # XML 布局文件
│   │   └── dlg_main.xml    # 主窗口布局
│   └── values/             # 资源值定义
│       ├── color.xml       # 颜色定义
│       ├── skin.xml        # 皮肤定义
│       └── string.xml      # 字符串定义
└── res/                    # 系统资源目录
    └── resource.h          # 系统资源头文件

3. 修改项目名称¶

修改 CMakeLists.txt¶

打开 CMakeLists.txt 文件，修改项目名称：

# 修改项目名称
set(project_name "MyNewProject")

修改主窗口类名¶

重命名 MainDlg.h 和 MainDlg.cpp 中的类名：

// MainDlg.h
class CMyNewProjectDlg : public SHostWnd
{
    // ...
};

// MainDlg.cpp
CMyNewProjectDlg::CMyNewProjectDlg() : SHostWnd(_T("LAYOUT:dlg_main"))
{
    // ...
}

4. 修改资源文件¶

修改资源索引文件¶

编辑 uires/uires.idx 文件，更新资源引用：

<?xml version="1.0" encoding="utf-8"?>
<resource>
  <layout>
    <file name="dlg_main" path="xml\dlg_main.xml" />
  </layout>
</resource>

修改主窗口布局¶

编辑 uires/xml/dlg_main.xml 文件，定义您的主窗口界面：

<?xml version="1.0" encoding="utf-8"?>
<SOUI name="mainWindow" title="MyNewProject" 
      width="800" height="600" 
      wndtype="appmain">
  <root skin="skinBK">
    <!-- 在此处添加您的界面元素 -->
    <text pos="10,10,200,40" class="cls_txt_normal"
          text="Hello SOUI5!" />
  </root>
</SOUI>

5. 构建项目¶

Windows 构建¶

# 创建构建目录
mkdir build
cd build

# 配置项目
cmake .. -G "Visual Studio 16 2019" -A x64

# 构建项目
cmake --build . --config Release

Linux/macOS 构建¶

# 创建构建目录
mkdir build
cd build

# 配置项目
cmake ..

# 构建项目
make -j$(nproc)

自定义应用程序¶

添加新功能¶

1. 添加新的 UI 控件¶

在 uires/xml/dlg_main.xml 中添加控件：

<button pos="10,50,100,80" name="btn_test" text="测试按钮" />

2. 处理控件事件¶

在 MainDlg.h 中添加事件处理函数：

class CMyNewProjectDlg : public SHostWnd
{
protected:
    void OnTestButton();

    // 事件映射
    EVENT_MAP_BEGIN()
        EVENT_NAME_COMMAND(L"btn_test", OnTestButton)
        // 其他事件映射
    EVENT_MAP_END2(SHostWnd)
};

在 MainDlg.cpp 中实现事件处理函数：

void CMyNewProjectDlg::OnTestButton()
{
    SMessageBox(NULL, _T("按钮被点击了！"), _T("提示"), MB_OK);
}

添加新资源¶

1. 添加字符串资源¶

编辑 uires/values/string.xml：

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="app_name">MyNewProject</string>
  <string name="hello_world">Hello World</string>
  <string name="new_string">新字符串</string>
</resources>

2. 使用字符串资源¶

在 XML 布局文件中使用：

<text pos="10,10,200,40" text="@string/new_string" />

跨平台注意事项¶

macOS 特定配置¶

在 CMakeLists.txt 中，macOS 相关配置如下：

if(CMAKE_SYSTEM_NAME MATCHES Darwin)
    # macOS 特定设置
    set(MACOSX_BUNDLE_HIGH_RESOLUTION_CAPABLE "true")
    set(MACOSX_BUNDLE_GUI_IDENTIFIER "com.yourcompany.mynewproject")
    set(MACOSX_BUNDLE_BUNDLE_NAME "MyNewProject")

    # 代码签名设置（根据需要修改）
    set(MACOSX_CODESIGN_IDENTITY "Apple Development")
    set(MACOSX_TEAM_ID "XXXXXXXXXXXX")

    # 设置 Xcode 特定的签名属性
    set_target_properties(${project_name} PROPERTIES
        XCODE_ATTRIBUTE_DEVELOPMENT_TEAM "${MACOSX_TEAM_ID}"
        XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "${MACOSX_CODESIGN_IDENTITY}"
        XCODE_ATTRIBUTE_CODE_SIGN_STYLE "Automatic"
        XCODE_ATTRIBUTE_PROVISIONING_PROFILE_SPECIFIER ""
    )

    # 复制必要的资源文件到应用程序包
    file(GLOB_RECURSE DYLIB_SOUI  ${SOUI_LIBRARY_DIRS}/*.dylib)
    copy_frameworks_to_bundle(${project_name} "${DYLIB_SOUI}")

    add_macos_res_file(${project_name} ${SOUI_ROOT}/resources/soui-sys-resource.zip data) 
    add_macos_res_file(${project_name} ${SOUI_ROOT}/resources/simsun.ttc fonts) 
    add_macos_res_folder(${project_name} ${CMAKE_CURRENT_SOURCE_DIR}/uires data/uires)
    set_macos_icon(${project_name} ${CMAKE_CURRENT_SOURCE_DIR}/res/soui-app.icns ${SOUI_ROOT}/__cmake/plist.in)
endif()

最佳实践¶

1. 项目结构管理¶

建议按照以下结构组织项目：

MyNewProject/
├── CMakeLists.txt
├── src/                    # 源代码目录
│   ├── MainDlg.h/cpp      # 主窗口
│   ├── App.h/cpp          # 应用类
│   └── ...                # 其他源文件
├── res/                    # 系统资源
└── uires/                  # UI 资源
    ├── uires.idx
    ├── xml/               # 布局文件
    ├── values/            # 资源值
    └── image/             # 图片资源

2. 资源管理¶

使用有意义的资源命名
按功能分组资源文件
合理使用资源继承和样式

3. 代码组织¶

遵循 SOUI 的事件处理模式
合理划分窗口和控件类
使用预编译头提高编译速度

故障排除¶

常见问题¶

1. CMake 配置失败¶

确保正确设置了 SOUI 环境变量：

# 检查环境变量
echo $SOUI4_INSTALL

2. 编译错误¶

检查是否正确包含了 SOUI 头文件：

#include <souistd.h>
#include <core/SHostWnd.h>

3. 运行时资源加载失败¶

确保资源文件路径正确，并且在构建时正确复制了资源文件。

下一步¶

完成项目创建后，您可以：