跨平台开发指南¶

SOUI5 基于先进的 swinx 框架实现了真正的跨平台支持，让您可以使用一套代码在 Windows、Linux、macOS 等多个平台上运行应用程序。

swinx 框架概述¶

什么是 swinx¶

swinx (Simple Window X-platform) 是一个现代化的跨平台窗口和 UI 抽象框架，专为 SOUI5 设计：

轻量级: 最小化的平台抽象层
高性能: 直接调用平台原生 API
现代化: 使用现代 C++ 特性
可扩展: 支持自定义平台适配器

架构设计¶

graph TB
    subgraph "SOUI5 应用层"
        A[用户应用]
        B[SOUI5 Controls]
        C[SOUI5 Core]
    end

    subgraph "swinx 抽象层"
        D[Window Manager]
        E[Event System]
        F[Render Backend]
        G[Resource Manager]
    end

    subgraph "平台实现层"
        H[Windows API]
        I[X11/Wayland]
        J[Cocoa]
    end

    A --> B
    B --> C
    C --> D
    C --> E
    C --> F
    C --> G

    D --> H
    D --> I
    D --> J

    E --> H
    E --> I
    E --> J

    F --> H
    F --> I
    F --> J

平台支持详情¶

Windows 支持¶

支持版本¶

Windows 7 SP1 及以上
Windows Server 2008 R2 及以上
Windows 10/11 (推荐)

技术特性¶

渲染: Direct2D、GDI+、软件渲染
窗口系统: Win32 API
输入法: TSF (Text Services Framework)
高DPI: Per-Monitor DPI Aware v2

特有功能¶

#include <swinx/platform/windows.h>

// Windows 特有功能
if (swinx::Platform::Current().IsWindows()) {
    auto winPlatform = swinx::Platform::AsWindows();

    // 启用 Aero Glass 效果
    winPlatform.EnableAeroGlass(true);

    // 设置任务栏预览
    winPlatform.SetTaskbarPreview(thumbnailBitmap);

    // 注册文件关联
    winPlatform.RegisterFileAssociation(".myfile", "MyApp");
}

Linux 支持¶

支持的发行版¶

Ubuntu 18.04 LTS 及以上
CentOS 7 及以上
Fedora 30 及以上
Debian 10 及以上
Arch Linux (滚动更新)

窗口系统支持¶

X11: 完全支持，稳定成熟
Wayland: 实验性支持

技术依赖¶

# Ubuntu/Debian 依赖
sudo apt-get install \
    libxcb1-dev libgl1-mesa-dev freeglut3-dev

# CentOS/RHEL 依赖
sudo yum install \
    libxcb-devel mesa-libGL-devel libuuid-devel

Linux 特性示例¶

#include <swinx/platform/linux.h>

if (swinx::Platform::Current().IsLinux()) {
    auto linuxPlatform = swinx::Platform::AsLinux();

    // 设置应用程序图标
    linuxPlatform.SetApplicationIcon("app-icon.svg");

    // 集成系统托盘
    linuxPlatform.CreateSystemTrayIcon();

    // 使用原生文件对话框
    auto filePath = linuxPlatform.ShowNativeFileDialog(
        FileDialogType::Open, "Select File");
}

macOS 支持¶

支持版本¶

macOS 10.12 (Sierra) 及以上
推荐 macOS 11 (Big Sur) 及以上

技术特性¶

渲染: Core Graphics、Metal
窗口系统: Cocoa/AppKit
外观: 自动适配浅色/深色主题
通知: 用户通知框架

macOS 特性示例¶

#include <swinx/platform/macos.h>

if (swinx::Platform::Current().IsMacOS()) {
    auto macosPlatform = swinx::Platform::AsMacOS();

    // 设置 Dock 图标
    macosPlatform.SetDockIcon("dock-icon.icns");

    // 添加菜单栏
    auto menuBar = macosPlatform.CreateMenuBar();
    menuBar.AddMenu("File");
    menuBar.AddMenu("Edit");

    // 启用深色模式检测
    macosPlatform.EnableDarkModeDetection([](bool isDark) {
        // 主题切换回调
        Application::SetTheme(isDark ? Theme::Dark : Theme::Light);
    });
}

跨平台开发最佳实践¶

1. 统一的代码结构¶

// Platform-agnostic code
class MyApplication : public soui5::Application
{
public:
    MyApplication() 
    {
        // 通用初始化代码
        InitializeCommon();

        // 平台特定初始化
        InitializePlatformSpecific();
    }

private:
    void InitializeCommon()
    {
        // 所有平台通用的初始化
        LoadResources();
        SetupEventHandlers();
    }

    void InitializePlatformSpecific()
    {
        auto platform = swinx::Platform::Current();

        if (platform.IsWindows()) {
            InitializeWindows();
        } else if (platform.IsLinux()) {
            InitializeLinux();
        } else if (platform.IsMacOS()) {
            InitializeMacOS();
        }
    }

    void InitializeWindows();
    void InitializeLinux();
    void InitializeMacOS();
};

2. 资源管理策略¶

平台特定资源¶

resources/
├── common/                 # 通用资源
│   ├── layouts/           # XML 布局文件
│   ├── styles/            # 样式定义
│   └── scripts/           # 脚本文件
├── windows/               # Windows 特定
│   ├── icons/             # .ico 文件
│   └── cursors/           # .cur 文件
├── linux/                 # Linux 特定
│   ├── icons/             # .svg 文件
│   └── desktop/           # .desktop 文件
└── macos/                 # macOS 特定
    ├── icons/             # .icns 文件
    └── plist/             # Info.plist 文件

资源加载代码¶

class ResourceManager
{
public:
    void LoadPlatformResources()
    {
        // 加载通用资源
        LoadCommonResources();

        // 加载平台特定资源
        auto platform = swinx::Platform::Current();
        std::string platformDir = GetPlatformDirectory(platform);

        LoadResourcesFromDirectory(platformDir);
    }

private:
    std::string GetPlatformDirectory(const swinx::Platform& platform)
    {
        if (platform.IsWindows()) return "resources/windows/";
        if (platform.IsLinux()) return "resources/linux/";
        if (platform.IsMacOS()) return "resources/macos/";
        return "resources/common/";
    }
};

3. 字体和文本处理¶

class FontManager
{
public:
    void SetupPlatformFonts()
    {
        auto platform = swinx::Platform::Current();

        if (platform.IsWindows()) {
            SetDefaultFont("Segoe UI", 9);
            SetMonospaceFont("Consolas", 9);
        } else if (platform.IsLinux()) {
            SetDefaultFont("Ubuntu", 10);
            SetMonospaceFont("Ubuntu Mono", 10);
        } else if (platform.IsMacOS()) {
            SetDefaultFont("SF Pro Text", 13);
            SetMonospaceFont("SF Mono", 13);
        }
    }

private:
    void SetDefaultFont(const std::string& family, int size);
    void SetMonospaceFont(const std::string& family, int size);
};

4. 文件路径处理¶

#include <filesystem>
#include <swinx/filesystem.h>

class PathHelper
{
public:
    static std::filesystem::path GetAppDataPath()
    {
        auto platform = swinx::Platform::Current();

        if (platform.IsWindows()) {
            return swinx::GetKnownFolderPath(FOLDERID_RoamingAppData) / "MyApp";
        } else if (platform.IsLinux()) {
            return swinx::GetHomeDirectory() / ".config" / "myapp";
        } else if (platform.IsMacOS()) {
            return swinx::GetHomeDirectory() / "Library" / "Application Support" / "MyApp";
        }

        return std::filesystem::current_path() / "data";
    }

    static std::filesystem::path GetTempPath()
    {
        return swinx::GetTemporaryDirectory() / "myapp";
    }
};

性能优化¶

1. 平台特定优化¶

class PerformanceOptimizer
{
public:
    void OptimizeForPlatform()
    {
        auto platform = swinx::Platform::Current();

        if (platform.IsWindows()) {
            // Windows 优化
            EnableDirectComposition();
            SetProcessDPIAware();
        } else if (platform.IsLinux()) {
            // Linux 优化
            EnableHardwareAcceleration();
            OptimizeForX11();
        } else if (platform.IsMacOS()) {
            // macOS 优化
            EnableMetalRendering();
            OptimizeForRetina();
        }
    }

private:
    void EnableDirectComposition();
    void EnableHardwareAcceleration();
    void EnableMetalRendering();
    // ... 其他优化方法
};

2. 内存管理¶

// 使用 swinx 提供的内存管理工具
class MemoryManager
{
public:
    void* AllocateAligned(size_t size, size_t alignment)
    {
        return swinx::AllocateAligned(size, alignment);
    }

    void Deallocate(void* ptr)
    {
        swinx::Deallocate(ptr);
    }

    // 平台特定的内存优化
    void OptimizeMemoryUsage()
    {
        auto platform = swinx::Platform::Current();

        if (platform.IsWindows()) {
            // Windows 内存优化
            SetProcessWorkingSetSize(GetCurrentProcess(), 
                                   MIN_WORKING_SET, MAX_WORKING_SET);
        } else if (platform.IsLinux()) {
            // Linux 内存优化
            mallopt(M_MMAP_THRESHOLD, 128 * 1024);
        }
    }
};

调试和测试¶

1. 跨平台调试¶

#include <swinx/debug.h>

class DebugHelper
{
public:
    static void LogPlatformInfo()
    {
        auto platform = swinx::Platform::Current();

        SWINX_LOG_INFO("Platform: {}", platform.GetName());
        SWINX_LOG_INFO("Version: {}", platform.GetVersion());
        SWINX_LOG_INFO("Architecture: {}", platform.GetArchitecture());

        // 平台特定信息
        if (platform.IsWindows()) {
            LogWindowsInfo();
        } else if (platform.IsLinux()) {
            LogLinuxInfo();
        } else if (platform.IsMacOS()) {
            LogMacOSInfo();
        }
    }

private:
    static void LogWindowsInfo();
    static void LogLinuxInfo();
    static void LogMacOSInfo();
};

2. 自动化测试¶

// 跨平台单元测试
class CrossPlatformTests
{
public:
    void RunAllTests()
    {
        // 通用测试
        TestCommonFunctionality();

        // 平台特定测试
        auto platform = swinx::Platform::Current();
        if (platform.IsWindows()) {
            TestWindowsFeatures();
        } else if (platform.IsLinux()) {
            TestLinuxFeatures();
        } else if (platform.IsMacOS()) {
            TestMacOSFeatures();
        }
    }

private:
    void TestCommonFunctionality();
    void TestWindowsFeatures();
    void TestLinuxFeatures();
    void TestMacOSFeatures();
};

部署指南¶

1. Windows 部署¶

# 创建 Windows 安装包
cpack -G NSIS -C Release

# 或创建便携版
cpack -G ZIP -C Release

2. Linux 部署¶

# 创建 DEB 包 (Ubuntu/Debian)
cpack -G DEB -C Release

# 创建 RPM 包 (CentOS/Fedora)
cpack -G RPM -C Release

# 创建 AppImage
cpack -G External -C Release

3. macOS 部署¶

# 创建 DMG 包
cpack -G DragNDrop -C Release

# 创建应用程序包
cpack -G Bundle -C Release

故障排除¶

常见问题¶

编译错误: 检查平台特定依赖是否安装
运行时错误: 验证资源文件路径
性能问题: 启用平台特定优化
显示问题: 检查DPI设置和字体配置

平台特定问题¶

Windows¶

高DPI问题: 确保启用 Per-Monitor DPI Aware
权限问题: 以管理员身份运行或使用UAC提升

Linux¶

依赖问题: 使用包管理器安装缺失的库
显示问题: 检查X11配置和GPU驱动

macOS¶

签名问题: 配置开发者证书
沙盒限制: 调整 entitlements 配置

总结¶

SOUI5 通过 swinx 框架提供了强大的跨平台能力，让开发者能够：

统一开发体验: 一套代码，多平台运行
平台原生体验: 充分利用各平台特性
高性能渲染: 自动选择最佳渲染后端
现代化工具链: 支持 CMake、包管理器等

通过遵循本指南的最佳实践，您可以开发出高质量的跨平台应用程序。

更多资源： - swinx API 参考 - 平台特定功能