消息框子系统（CategoryMessagebox）

SDL 提供了一套简洁的消息框 API，适用于展示轻量提示信息——比如程序启动时发生致命错误（无需搭建完整 UI 即可告知用户），或在自定义 UI 加载完成前向用户展示关键提示。

这些消息框会尽可能使用系统原生对话框样式，保证与操作系统的视觉一致性。

SDL 提供两种消息框接口：

1. 自定义消息框（SDL_ShowMessageBox()）：支持丰富的配置选项（如多按钮、自定义颜色、图标类型），并能返回用户的选择结果；
2. 简易消息框（SDL_ShowSimpleMessageBox()）：极简接口，仅需传入提示文本和标题，等待用户点击「确定」按钮即可，满足大部分基础提示场景。

函数

• SDL_ShowMessageBox：显示自定义样式的消息框，接收 SDL_MessageBoxData 配置结构体，返回用户点击的按钮索引（失败返回非0，可通过 SDL_GetError() 获取错误）
• SDL_ShowSimpleMessageBox：显示简易消息框，指定消息类型（提示/警告/错误）、标题和内容，无返回值（阻塞至用户点击「确定」）

数据类型

• SDL_MessageBoxButtonFlags：消息框按钮标志类型（用于标记默认按钮、退出按钮等，如 SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT）
• SDL_MessageBoxFlags：消息框全局标志类型（用于指定消息框类型/样式，如 SDL_MESSAGEBOX_ERROR/SDL_MESSAGEBOX_WARNING）

结构体

• SDL_MessageBoxButtonData：单个按钮的配置结构体，包含按钮标志、按钮索引、按钮文本
• SDL_MessageBoxColor：消息框颜色结构体，包含红/绿/蓝（RGB）三个分量（取值 0~255）
• SDL_MessageBoxColorScheme：消息框配色方案结构体，定义按钮、背景、文本等区域的颜色
• SDL_MessageBoxData：自定义消息框的核心配置结构体，包含全局标志、父窗口、标题、内容、按钮数组、配色方案等

枚举

• SDL_MessageBoxColorType：消息框颜色类型枚举，标识配色方案中不同区域的颜色，常见值：
  • SDL_MESSAGEBOX_COLOR_BACKGROUND：背景色
  • SDL_MESSAGEBOX_COLOR_TEXT：文本色
  • SDL_MESSAGEBOX_COLOR_BUTTON_BORDER：按钮边框色
  • SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND：按钮背景色
  • SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED：按钮选中色

宏

• （无）

FreeBASIC 示例代码

' 引入 SDL 相关声明（需确保 FreeBASIC 已链接 SDL3 库）
#Include "SDL.bi"

' 补充枚举/类型/结构体声明（FreeBASIC 绑定可能缺失）
Enum SDL_MessageBoxFlags
    SDL_MESSAGEBOX_ERROR = 1 Shl 0      ' 错误类型消息框
    SDL_MESSAGEBOX_WARNING = 1 Shl 1    ' 警告类型消息框
    SDL_MESSAGEBOX_INFORMATION = 1 Shl 2 ' 信息类型消息框
End Enum

Enum SDL_MessageBoxButtonFlags
    SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT = 1 Shl 0 ' 回车默认按钮
    SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT = 1 Shl 1 ' ESC 默认按钮
End Enum

Enum SDL_MessageBoxColorType
    SDL_MESSAGEBOX_COLOR_BACKGROUND = 0    ' 背景色
    SDL_MESSAGEBOX_COLOR_TEXT = 1          ' 文本色
    SDL_MESSAGEBOX_COLOR_BUTTON_BORDER = 2 ' 按钮边框色
    SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND = 3 ' 按钮背景色
    SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED = 4 ' 按钮选中色
    SDL_MESSAGEBOX_COLOR_MAX = 5           ' 颜色类型总数
End Enum

Type SDL_MessageBoxColor
    r As UByte   ' 红色分量 (0-255)
    g As UByte   ' 绿色分量 (0-255)
    b As UByte   ' 蓝色分量 (0-255)
End Type

Type SDL_MessageBoxColorScheme
    colors(0 To SDL_MESSAGEBOX_COLOR_MAX-1) As SDL_MessageBoxColor
End Type

Type SDL_MessageBoxButtonData
    flags As Uint32       ' 按钮标志
    buttonid As Integer   ' 按钮索引（自定义）
    text As ZString Ptr   ' 按钮文本
End Type

Type SDL_MessageBoxData
    flags As Uint32                       ' 消息框全局标志
    window As SDL_Window Ptr              ' 父窗口（NULL 表示无父窗口）
    title As ZString Ptr                  ' 消息框标题
    message As ZString Ptr                ' 消息框内容
    numbuttons As Integer                 ' 按钮数量
    buttons As SDL_MessageBoxButtonData Ptr ' 按钮数组
    colorScheme As SDL_MessageBoxColorScheme Ptr ' 配色方案（NULL 使用系统默认）
End Type

' 函数声明
Declare Sub SDL_ShowSimpleMessageBox CDecl (ByVal flags As Uint32, ByVal title As ZString Ptr, ByVal message As ZString Ptr, ByVal window As SDL_Window Ptr)
Declare Function SDL_ShowMessageBox CDecl (ByVal messageboxdata As SDL_MessageBoxData Ptr, ByRef buttonid As Integer) As Integer

' 示例1：显示简易消息框（提示/警告/错误）
Sub ShowSimpleMessageBoxes()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "【示例1：显示简易消息框】")

    ' 1. 信息提示框
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "显示信息提示框...")
    SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_INFORMATION, _
        StrPtr("操作成功"), _
        StrPtr("文件已保存至默认路径！"), _
        NULL)

    ' 2. 警告提示框
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "显示警告提示框...")
    SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_WARNING, _
        StrPtr("低电量警告"), _
        StrPtr("当前电量不足 20%，请及时充电！"), _
        NULL)

    ' 3. 错误提示框
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "显示错误提示框...")
    SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_ERROR, _
        StrPtr("初始化失败"), _
        StrPtr("无法加载配置文件，请检查文件是否存在！"), _
        NULL)
End Sub

' 示例2：显示自定义消息框（多按钮 + 自定义配色）
Sub ShowCustomMessageBox()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【示例2：显示自定义消息框】")

    ' 1. 定义按钮（确定/取消/跳过）
    Dim As SDL_MessageBoxButtonData buttons(2)
    ' 按钮0：确定（回车默认）
    buttons(0).flags = SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT
    buttons(0).buttonid = 0
    buttons(0).text = StrPtr("确定")
    ' 按钮1：取消（ESC 默认）
    buttons(1).flags = SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT
    buttons(1).buttonid = 1
    buttons(1).text = StrPtr("取消")
    ' 按钮2：跳过
    buttons(2).flags = 0
    buttons(2).buttonid = 2
    buttons(2).text = StrPtr("跳过")

    ' 2. 自定义配色方案（可选）
    Dim As SDL_MessageBoxColorScheme colorScheme
    ' 背景色：浅灰色
    colorScheme.colors(SDL_MESSAGEBOX_COLOR_BACKGROUND) = Type<SDL_MessageBoxColor>(240, 240, 240)
    ' 文本色：黑色
    colorScheme.colors(SDL_MESSAGEBOX_COLOR_TEXT) = Type<SDL_MessageBoxColor>(0, 0, 0)
    ' 按钮背景色：浅蓝色
    colorScheme.colors(SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND) = Type<SDL_MessageBoxColor>(180, 210, 255)
    ' 按钮选中色：深蓝色
    colorScheme.colors(SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED) = Type<SDL_MessageBoxColor>(100, 140, 255)
    ' 按钮边框色：灰色
    colorScheme.colors(SDL_MESSAGEBOX_COLOR_BUTTON_BORDER) = Type<SDL_MessageBoxColor>(150, 150, 150)

    ' 3. 配置消息框数据
    Dim As SDL_MessageBoxData msgBoxData
    msgBoxData.flags = SDL_MESSAGEBOX_WARNING  ' 警告类型
    msgBoxData.window = NULL                   ' 无父窗口
    msgBoxData.title = StrPtr("更新提示")       ' 标题
    msgBoxData.message = StrPtr("检测到新版本 v2.0，是否立即更新？") ' 内容
    msgBoxData.numbuttons = 3                  ' 按钮数量
    msgBoxData.buttons = @buttons(0)           ' 按钮数组
    msgBoxData.colorScheme = @colorScheme      ' 自定义配色

    ' 4. 显示自定义消息框并获取用户选择
    Dim As Integer selectedButtonId
    Dim As Integer result = SDL_ShowMessageBox(@msgBoxData, selectedButtonId)

    If (result = 0) Then
        ' 处理用户选择
        Select Case selectedButtonId
            Case 0: SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "用户选择：确定（开始更新）")
            Case 1: SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "用户选择：取消（放弃更新）")
            Case 2: SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "用户选择：跳过（稍后更新）")
            Case Else: SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "用户选择了未知按钮")
        End Select
    Else
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "显示自定义消息框失败：%s", SDL_GetError())
    End If
End Sub

' 示例3：带父窗口的消息框（模拟与游戏窗口关联）
Sub ShowMessageBoxWithParent()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【示例3：带父窗口的消息框】")

    ' 创建一个临时窗口作为父窗口
    Dim As SDL_Window Ptr window = SDL_CreateWindow( _
        StrPtr("SDL 示例窗口"), _
        SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED, _
        640, 480, _
        SDL_WINDOW_SHOWN _
    )

    If (window <> NULL) Then
        ' 显示关联父窗口的错误消息框
        SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_ERROR, _
            StrPtr("游戏错误"), _
            StrPtr("无法初始化渲染器，请检查显卡驱动！"), _
            window)

        ' 销毁窗口
        SDL_DestroyWindow(window)
    End If
End Sub

' 主程序
Sub Main()
    ' 初始化 SDL（必须初始化视频子系统才能显示消息框）
    If (SDL_Init(SDL_INIT_VIDEO) < 0) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL 初始化失败：%s", SDL_GetError())
        Exit Sub
    End If

    ' 运行示例
    ShowSimpleMessageBoxes()
    ShowCustomMessageBox()
    ShowMessageBoxWithParent()

    ' 清理 SDL
    SDL_Quit()

    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "程序正常退出")
End Sub

' 运行主程序
Main()

核心知识点补充

1. 关键前置条件：

   • 显示消息框必须初始化 SDL 视频子系统（SDL_Init(SDL_INIT_VIDEO)），否则会调用失败；
   • 消息框默认是模态对话框，会阻塞当前线程直至用户操作完成。

2. SDL_MessageBoxFlags 常用值：	标志常量	作用	系统表现
   SDL_MESSAGEBOX_ERROR	错误类型	显示错误图标（如 Windows 的红色叉号）
   SDL_MESSAGEBOX_WARNING	警告类型	显示警告图标（如 Windows 的黄色感叹号）
   SDL_MESSAGEBOX_INFORMATION	信息类型	显示信息图标（如 Windows 的蓝色i）

3. 按钮标志使用规则：

   • SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT：设置为「回车」快捷键对应的按钮；
   • SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT：设置为「ESC」快捷键对应的按钮；
   • 一个消息框建议仅设置一个回车默认按钮和一个 ESC 默认按钮。

4. 平台兼容性：

   • ✅ Windows/macOS/Linux：完全支持自定义消息框和简易消息框，样式贴合系统原生；
   • ✅ 移动平台（Android/iOS）：简易消息框支持良好，自定义消息框会适配移动端样式；
   • ❗ 部分嵌入式系统：可能仅支持简易消息框，自定义配色/多按钮可能失效。

总结

1. 核心优势：

   • 跨平台统一的消息框接口，无需适配不同系统的原生对话框 API（如 Windows 的 MessageBox、GTK 的 gtk_message_dialog）；
   • 支持从极简到高度自定义的消息框需求，兼顾易用性和灵活性；
   • 自动适配系统原生样式，保证用户体验一致性；
   • 支持关联父窗口，实现模态对话框的层级关联。

2. 使用建议：

   • 基础提示场景优先使用 SDL_ShowSimpleMessageBox()（代码简洁、兼容性好）；
   • 需要用户选择（如确认/取消）时使用 SDL_ShowMessageBox()；
   • 自定义配色仅在特殊需求下使用，优先依赖系统默认配色（更符合用户习惯）；
   • 消息框文本建议简洁明了，避免过长内容影响阅读。

3. 关键点回顾：

   • 显示消息框必须初始化 SDL 视频子系统（SDL_INIT_VIDEO）；
   • SDL_ShowSimpleMessageBox 适用于单按钮提示，SDL_ShowMessageBox 适用于多按钮选择；
   • 按钮标志可设置回车/ESC 快捷键，提升操作便捷性；
   • 消息框为模态对话框，会阻塞调用线程直至用户操作完成。