SOUI - 轻量级跨平台 C++ GUI 开发框架

Platforms

一套代码，六大平台

SOUI 通过 swinx 在不同系统上重建 Windows API 语义，让上层 C++ 代码保持一致。

原生

Windows

原生支持，无需 swinx

直接使用系统 Windows SDK
渲染：GDI / Direct2D / Skia
资源可内嵌 PE，绿色单文件

桌面

Linux

xcb 事件循环 + Cairo

poll() + xcb_poll_for_event
swinx 2D 后端：Cairo
托盘 / XDND / X11 剪贴板 / D-Bus

桌面

macOS

NSApplication + Core Graphics

SwinXApplication 自有启动器
swinx 2D 后端：Core Graphics
支持 Bundle 资源与 Xcode 工程

移动端

iOS

swinx 内部自实现，自带启动器

swinx_ios_entry() 托管 UIApplicationMain
HWND 载体：SUIView 指针，零查表
swinx 2D 后端：Core Graphics

移动端

Android

JVM 启动 · PlatformAPI 桥接

HWND 载体：jobject 全局引用地址
资源：SResProviderAndroidAsset
swinx 2D 后端：Cairo

移动端

鸿蒙 OHOS

ArkTS 启动 · PlatformAPI 桥接

HWND 载体：C++ native 句柄
资源：SResProviderOhosRawFile
swinx 2D 后端：Cairo

Mobile

移动端适配：Android / iOS / 鸿蒙

SOUI 已完整适配三大移动端系统。桌面端既有工程可沿用同一套 C++ 业务代码，仅需接入对应平台的入口与资源提供器。

swinx 分层：为什么移动端需要 `platform_api`

swinx 是一套在各平台重新实现 Windows API 的框架（windows.h / winuser.h / gdi.h 均由 swinx/include 提供）。不同系统的接入方式并不相同：

Windows

不编译 swinx，直接调用系统 Windows SDK。原生平台，零适配成本。

Linux / macOS / iOS

在 swinx 模块内部自实现平台 API，且各自拥有自己的启动器与消息循环（xcb poll()、SwinXApplication、swinx_ios_entry），因此不需要 platform_api。

Android / 鸿蒙

进程由 JVM / ArkTS 运行时启动，没有自己的启动器。平台能力（clipboard / window / ime / audio / path）由 AndroidPlatformAPIReg、OhosPlatformAPIReg 填入 C 结构体 PlatformAPI，再经 PlatformAPI_Init 注册。

注：g_platformAPI 的消费点仅限 src/platform/mobile/ 及少数 #if defined(__ANDROID__)||defined(__OHOS__) 分支（如 GetTempPathA、特殊文件夹、PlaySound），并非全平台通用分发表。

三端实现对照

能力	Android	iOS	鸿蒙（OHOS）
swinx 平台层	`src/platform/mobile`	`src/platform/ios`	`src/platform/mobile`
是否用 platform_api	是	否（swinx 内部自实现）	是
启动器归属	JVM（`GameActivity` 等）	`UIApplicationMain`（`swinx_ios_entry` 托管）	ArkTS 运行时（`EntryAbility`）
HWND 载体	`jobject` 全局引用地址	`SUIView` 指针（零查表）	C++ native 句柄（ArkTS 侧 `mWindowMap` 反查）
swinx 2D 后端	Cairo	Core Graphics	Cairo
SOUI 渲染工厂	`Render_Skia`	`Render_Skia`	`Render_Skia`
资源提供器	`SResProviderAndroidAsset` APK assets · `AAssetManager`	Bundle 资源	`SResProviderOhosRawFile` HAP rawfile · `NativeResourceManager`
上屏方式	`AndroidBitmap_lockPixels` → `Canvas.drawBitmap`	`SUIView drawRect:` → `CGContext`	缓冲同步到 `PixelMap` → `drawImage`
虚拟 HWND	支持（`ENABLE_VIRTUAL_HWND`）	不适用	支持（`ENABLE_VIRTUAL_HWND`）

注意区分两层概念：swinx 2D 后端（Cairo / Core Graphics）负责位图光栅化， SOUI 渲染工厂（Render_Skia）负责上层控件绘制，二者不是同一件事。

为移动端专门做的优化

1 SModalView 模态视图

桌面端常用的 SHostDialog::DoModal 依赖 GetMsgLoop 拉起嵌套消息循环，而移动端进程由系统运行时启动、无法自行拉起 msgloop。为此 SOUI 引入 SModalView：由 SModalRoot 全屏遮罩拦截输入、SModalView 承载可见对话框（支持进出场动画）， SHostWnd 维护模态栈，退出时通过 EventExitModalView 带回退出码。

BeginModalViewSession / EndModalViewSession · 支持 quitOnClick 点背景关闭

2 Fling 惯性滑动

SPanel 及其子类的滚动条新增 fling（惯性滑动）支持：记录松手前速度，用 SFloatAnimator 做减速滚动，让手指滑动体验贴近原生。 fling 进行中会立即消费左键消息以停止惯性。

迁移要点：SPanel::OnLButtonDown/Up 会先走 HandleMouseDrag 拦截拖拽，未命中才转调 OnLButtonDownEx / OnLButtonUpEx（OnMouseMove 对应 OnMouseMoveEx）。自定义子控件需改重写这两个 Ex 虚函数，SListCtrl / SListbox / STreeCtrl 已完成迁移。

3 虚拟 HWND

Android 与鸿蒙没有真实窗口句柄概念。SOUI 通过 ENABLE_VIRTUAL_HWND 编译开关启用虚拟 HWND 机制，提供 RegisterVirtualHWND / UnregisterVirtualHWND，让上层仍然可以用熟悉的 HWND 语义操作窗口。

定义于 mobile.cmake，声明位于 swinx/include/wnd.h

4 资源免拷贝直读

移动端资源无需先复制到沙箱：SResProviderAndroidAsset 通过 AAssetManager 直接从 APK assets 读取，SResProviderOhosRawFile 通过 NativeResourceManager 直接从 HAP rawfile 读取，两者都带 .idx 索引与 m_mapFiles 缓存。

只读资源走包内直读；需要可写的资源（如主题）再落到沙箱 filesDir

Features

为什么选择 SOUI？

从 Windows 桌面到移动端，同一套设计理念贯穿始终。

真正跨平台

一套代码覆盖 Windows / Linux / macOS / iOS / Android / 鸿蒙。既有 Windows 工程最快十分钟即可移植到 Linux、macOS。

高性能渲染

渲染引擎经过充分优化，低配置设备上依然流畅。可按需选择 GDI、Direct2D 或 Skia 渲染后端。

体积小巧

功能模块插件式设计、按需装配，最小配置编译后体积可小于 2MB，核心库约 1MB。

丰富的组件

提供按钮、列表、树形控件、表格等常用组件，并内置完善的虚表（虚拟列表）支持，轻松应对大数据量展示。

XML 布局

用 XML 描述界面，实现界面与逻辑彻底分离。支持线性布局、相对布局、网格布局等多种布局模式。

完全开源

核心代码、全部组件以及跨平台支持模块 swinx 全部开源，所有代码尽在掌控，可放心用于商业项目。

Showcase

SOUI 自研作品

以下作品均由 SOUI 团队完全自主研发，展示框架在不同应用场景下的能力。

XMusic 音乐播放器

基于 SOUI4 + SDL3 + SDL_mixer3 的开源跨平台音乐播放器，独创 .rc 资源编译技术实现真正的绿色单文件发布。

跨平台单文件开源免费

查看详情 »

XPlayer 视频播放器

基于 SOUI5 + SDL3 的跨平台高性能视频播放器，采用 SDL3 硬件加速上屏，通过 IHostPresenter 实现 UI 与视频融合。

硬件加速跨平台视频录制

查看详情 »

Ai快寻智能视频分析

AI 驱动的智能视频分析平台，基于 YOLO 提供物品识别与人脸识别，支持帧缩放查看与视频帧定位。

AI识别物品检测人脸识别

查看详情 »

🎹

启程输入法

完全免费、功能强大的中文输入法，采用 SOUI 构建精美界面，支持拼音、五笔、智能联想与皮肤定制。

完全免费智能联想皮肤定制

访问官网 »

Cases

案例展示

以下是使用 SOUI 开发的实际应用案例。

迅游游戏加速器

基于 SOUI 开发的界面效果非常炫的游戏加速器，具有精美的 UI 界面和流畅的动画效果。除迅游外，还有很多游戏加速器选择 SOUI 作为 UI 引擎。

视频播放器

深受用户喜爱的视频播放器，同样具有精美的 UI 界面和流畅的动画效果，与视频播放完美结合。

百度网盘

使用 SOUI 开发的百度网盘客户端，SOUI 完整支撑了网盘的各种复杂交互场景。

查看更多案例

Get Started

快速开始

使用 CMake 构建，几行代码即可跑起第一个 SOUI 程序 —— 同一份代码可编译到六大平台。

main.cpp

// 一个最简单的 SOUI 程序：界面由 XML 描述，逻辑用 C++ 编写
#include "souistd.h"

class CMainDlg : public SOUI::SHostDialog {
public:
    CMainDlg() : SHostDialog(_T("LAYOUT:XML_MAINWND")) {}

    void OnClick() {
        SOUI::SMessageBox(NULL, _T("Hello SOUI!"), _T("Greeting"), MB_OK);
    }

    EVENT_MAP_BEGIN()
        EVENT_ID_COMMAND(1, OnClick)   // 按钮 ID 为 1 时触发 OnClick
    EVENT_MAP_END()
};

int WINAPI _tWinMain(HINSTANCE hInst, HINSTANCE, LPTSTR lpCmdLine, int nShowCmd) {
    SOUI::SApplication *theApp = new SOUI::SApplication(hInst);
    // ... 配置 app：渲染工厂（Render_Skia）、图像解码器等
    // ... 初始化 SOUI 资源（文件 / PE / zip / assets / rawfile）
    {
        CMainDlg dlgMain;
        dlgMain.DoModal();
    }
    delete theApp;
    return 0;
}

获取源代码在线帮助文档示例仓库合集

Articles

技术文章

了解 SOUI 的最新开发动态、技术解析和最佳实践。

从 Windows 到鸿蒙：一个 C++ DirectUI 框架是怎么吃下五个平台的

2026年8月31日

从 Windows 到鸿蒙：一个 C++ DirectUI 框架是怎么吃下五个平台的当”自主可控”从口号变成刚需，一个老问题再次摆在国内 C++ 客户端团队面前：我们的界面代码，能不能也跑在鸿蒙上？一、为什么是现在鸿蒙（HarmonyOS / OHOS）的本体语言是 ArkTS，UI 体系…

阅读全文 »

SOUI5：全网首款全平台原生兼容的 C++ GUI 框架——一套代码终结多端多团队维护噩梦

2026年8月24日

SOUI5：全网首款全平台原生兼容的 C++ GUI 框架——一套代码终结多端多团队维护噩梦你的 App 是否还在 iOS、Android 各养一个团队、各维护一套代码？逻辑对不齐、bug 翻倍、功能上线永远不同步？本文介绍全网第一款覆盖 Win/Linux/macOS/Android/iOS 五大…

阅读全文 »

一套 C++ 代码，桌面与移动端通吃：SOUI for Android 实战移植中国象棋

2026年8月3日

一套 C++ 代码，桌面与移动端通吃：SOUI for Android 实战移植中国象棋我最近把一个原本运行在 Windows、Linux、macOS 桌面端的中国象棋联网游戏，使用 SOUI for Android 移植到了 Android 平台。整个移植过程几乎没有改动业务代码，C++ 主窗口类、游戏逻…

阅读全文 »

SOUI for Android：一套 C++ 代码，实现真正的跨平台 UI

2026年7月22日

SOUI for Android：一套 C++ 代码，实现真正的跨平台 UI 本文介绍 SOUI 框架的 Android 适配方案，展示如何用 C++ 开发高性能、安全、跨平台的移动应用，同时与 Android 原生系统无缝集成。🔥 为什么选择 SOUI for Android？在移动开发领域，跨平台方案层…

阅读全文 »